link from data types to vocabularies

[pvdbosch]

In GitLab by @pvdbosch on Dec 11, 2019, 21:01

Most gCloud business data types in Swagger/OpenAPI are related to concepts defined in functional work group, (international) standards or, in the future, ICEG work groups.
The functional work group provides artifacts with more information about the concept.
It would be useful to add links to these definitions.

First discuss how to these links would look like, in a manner that they are clear and easy to keep updated.

[pvdbosch]

Some ideas:

• use a custom extension property (Swagger allows custom properties starting with 'x-'), for instance x-vocab-uri
  • this would allow some automatic processing by tooling
  • is the URI always dereferencable? Is it where the location where the best documentation is provided?
  • would it be applied at every level of a data type? (Schema Objects and properties)
• add link in externalDocs
  • only a single external link is permitted, both in OpenAPI 2.0 and 3.0
  • add link in description field (which can be MarkDown format)
  • only applicable on HTTP body in OpenAPI 2.0 (i.e. not on query/path params)
  • not properly displayed by SwaggerUI

Example:

  Gender:
    description: "Gender of a person, following the ISO 5218 standard: 0 = Unknown, 1 = male, 2 = female. More info in [Belgif vocabularies](https://github.com/belgif/fedvoc/blob/master/FederalServicePlatform-Vocabularies.xlsx)"
    type: integer
    enum:
    - 0
    - 1
    - 2
    # code 9 in ISO 5218 signifies "not applicable" (e.g. when the gender property is applied to a genderless object) but is omitted here as it is not expected to be used in most use cases
    x-vocab-uri: http://vocab.belgif.be/auth/gender#id
    externalDocs:
      description: Belgif Federal Vocabularies 
      url: https://github.com/belgif/fedvoc/blob/master/FederalServicePlatform-Vocabularies.xlsx