OpenAPI data types

Reusable OpenAPI 2.0 and 3.0 data types are maintained in the openapi-* GitHub repositories, organized per domain. Releases can be downloaded from GitHub, in OpenAPI 2.0 (Swagger) or 3.0 variants. Apache Maven users can also download them from Maven Central.

In the future, they will be published on a website as well (#61).

The OpenAPI files are organized in following directory structure (as discussed in #29):

• <domain>/<version>/<domain-version>.yaml
• <domain>/<subdomain>/<version>/<domain-subdomain-version>.yaml

Examples:

• common/v1/common-v1.yaml
• location/v1beta/location-v1beta.yaml
• person/identifier/v1/person-identifier-v1.yaml

Data types for technical concepts are defined by the REST design WG (common and problem domains).

For functional concepts, the REST design WG defines data types in collaboration with the functional WG:

1. The functional WG agrees on naming and semantics of a concept and publishes it in the vocabularies
2. REST design WG evaluates which representation fits most use cases for REST APIs. If no single common representation is found, no OpenAPI data type is defined. If one is found, a draft data type is added in a beta version of an OpenAPI file. Names and description are based on those in the vocabularies.
3. A data type validated by both REST design and functional working groups.
4. The data type is declared stable (moved to a non-beta version) once the latest version has been accepted by both WGs. This may only be done after the corresponding entry in the vocabularies is stable (i.e. present in the tab "Standard" in the spreadsheet).