rest-guide icon indicating copy to clipboard operation
rest-guide copied to clipboard

Add rule about using fedvoc naming

Open jpraet opened this issue 2 years ago • 2 comments

The rest-guide currently lists these as not covered:

Topics not covered in this guide:

  • Semantics of common business data (e.g. social security number, address, …​). These are managed by the REST Functional Working Group in the belgif fedvoc repository.
  • OpenAPI specifications for common data types can be found in the openapi-* GitHub repositories.

While I agree that the specifics of these topics are indeed out of scope for the rest-guide, I think it would be worthwhile to formalize that API providers should use the belgif types and fedvoc naming?

Rule: Use Belgif OpenAPI data types. [belgif-types]

API providers SHOULD use the standardized Belgif OpenAPI data types.

Rule: Use FedVoc vocabulary. [fedvoc]

API providers SHOULD follow the standard FedVoc vocabulary naming conventions.

jpraet avatar Nov 16 '23 14:11 jpraet

Rule on OpenAPI data types is already present: Rule: Common definitions for Belgian government institutions [oas-comdef]

Rule on FedVoc TODO, may with some guidance on how to map these to OpenAPI (e.g. property, Class ->types name); column inOpenAPI(yes/no)

pvdbosch avatar Nov 17 '23 08:11 pvdbosch

Rule on OpenAPI data types is already present: Rule: Common definitions for Belgian government institutions [oas-comdef]

Thanks, I overlooked that one somehow.

jpraet avatar Nov 17 '23 11:11 jpraet