HAL link definition clashing with naming conventions

[acabarbaye]

Describe the bug
When describing hal links (http://stateless.co/hal_specification.html) (as property), their naming convention defers from other properties:
e.g. _links, _embedded, _metadata
https://tools.ietf.org/html/draft-kelly-json-hal-08

To Reproduce
e.g.

title: Items
      type: object
      properties:
        _links:
          $ref: "#/components/schemas/LinksDefinition"

results in

*ERROR* in model Items '_embedded' -> property should be in camelCase
*ERROR* in model Items '_links' -> property should be in camelCase
*ERROR* in model Items '_metadata' -> property should be in camelCase

Expected behavior
No error raised for HAL links specific keywords (i.e._links, _embedded, _metadata) as we have no control over their naming

[JFCote]

@acabarbaye Thanks for reporting this. I've never heard of HAL link definition. I will need to read on the subject and think of a clean solution for this. Meanwhile, if you have time and want to try, you can submit a PR and we can start from there.

[JFCote]

@acabarbaye Here is what I would do:

We could have a new property called acceptHALProperties. When this is true (false by default), properties that are not following the configuration will also be validated against the HAL property list and considered valid.

Would that be a good solution for your use case?

[acabarbaye]

@acabarbaye Here is what I would do:

We could have a new property called acceptHALProperties. When this is true (false by default), properties that are not following the configuration will also be validated against the HAL property list and considered valid.

Would that be a good solution for your use case?

I think it would definitely work.

[JFCote]

Moved this to milestone 1.7.0 because we will release version 1.6.0 very soon with lots of bug fixes and this is a new feature.

[baurceanu]

Hi,
'_metadata' is not a reserved property according to the JSON+HAL spec.
Moreover, different hypermedia formats use different reserved properties (e.g. HAL+FORMS declares '_links' and 'templates'). IMHO, it looks redundant to add a new boolean parameter for each hypermedia MIME type. It can be an alternative solution to add a new 'allowedModelProperties' parameter in which library users could list ignored properties that they need.

[JFCote]

@baurchanu Thanks for your advice.
I will definitely revisit this feature when I have time.

[gervaisb]

Can't we add another naming convention, one for each hypermedia format? So that we can use "propertiesNamingConvention": "JsonHal".

Or, for a bigger change, create a new "hypermediaFormat" configuration key, that will validate the naming and other specialities to this format. Those may be seen as a set of preconfigured values.

[JFCote]

@acabarbaye , @baurchanu and @gervaisb
I think I will first follow @baurchanu suggestion and add something like allowedModelProperties where developers will be able to define their "allowlist". Creating presets for each hypermedia format is risky. It will create a dependency between this project and these format.

Most of the documentation shared in this thread are marked as "draft" or "experimental" which is never a good sign.

The goal of openapi-style-validator is to be lightweight and easy to configure.

Therefore, just so I test this correctly, @acabarbaye can you share me a complete YAML file with this kind of hypermedia (HAL). The test will simply be that the style validator do not throw errors after the new configuration is applied.

Thanks

[acabarbaye]

@JFCote as requested. Inside the model section you can see some HAL links being defined
exampleAPI.txt