Allow metadata JSON properties starting with _

[jpraet]

https://www.belgif.be/specification/rest/api-guide/#rule-jsn-naming

do not use underscores (_), hyphens (-) or dots (.) in a property name, nor use a digit as first letter

Could a general exception to this rule be made for metadata properties?

e.g. HATEAOS "_links", and CBSS uses "_filters" to communicate to the client that certain fields that are defined in the contract, but they are not authorized for, have been filtered from the response.

[pvdbosch]

Underscores are currently not used for other metadata, like for pagination, href and self links. HAL "_links" are not recommended in the guide: https://www.belgif.be/specification/rest/api-guide/#links

You'd have the define when a property is considered metadata, i.e. is creation date or last modification date of a code in /refData considered metadata?

That said, the rule does allow deviations from other standards:

Properties used from other standards, like OpenID Connect and OAuth2, are allowed to deviate from this rule.

This devation could apply to JSON-LD which defines metadata properties with the @ prefix.

[jpraet]

The suggestion to use _ as prefix for metadata at CBSS came from you @pvdbosch :wink:

[06/02 16:58] Jimmy Praet (KSZ-BCSS) Dag Peter, in je draft guidelines voor data filters in REST API's: weet je nog waarom je "_filters" gekozen hebt vs "filters"?

[06/02 16:59] Peter Van Den Bosch (Smals) was om naming collissions te voorkomen ; en zoiets soms tegengekomen om wat duidelijker onderscheid te maken tussen metadata en werkelijke gegevens

[06/02 17:00] Peter Van Den Bosch (Smals) maar is wel nog niet eerder gebruikt denk ik in onze guide, dus da's wel mss niet heel consistent

[pvdbosch]

I know :) I meant to re-evaluate it (because "da's wel mss niet heel consistent"), but the matter wasn't really pressing at the time...

[jpraet]

FWIW, CBSS decided to return the applied data filters in a HTTP response header instead of a "_filters" property in the body.