API specifications

The description of a new REST API SHOULD be provided using OpenAPI 3.0. OpenAPI uses the OpenAPI Schema Object to describe the JSON representation of resources, which is a variant of JSON Schema, with some significant incompatibilities.

More recent OpenAPI 3.x versions improve upon OpenAPI 3.0, but SHOULD NOT be used to avoid interoperability problems because they are not yet sufficiently supported by tooling.

OpenAPI documents SHOULD be made available in YAML format, and OPTIONALLY in JSON format as well.

YAML is a superset of JSON which allows a simpler notation, and also allows comments. According to usage, a conversion step to JSON might be necessary considering limitations of tools.

OpenAPI authors SHOULD add sufficient documentation so that the OpenAPI can be used as an entry point to start using the API. Documentation SHOULD be geared towards users, and SHOULD NOT document the internal implementation of the API.

Alongside the definitions of allowed interactions (operations, schemas, …​), sufficient additional documentation SHOULD be provided by:

Free-text documentation can be added throughout an OpenAPI:

When an API has many operations, tags SHOULD be used to group them together.

An operation SHOULD NOT have more than one tag.

Each tag used on an operation SHOULD also be declared in the top level tags list of the OpenAPI document, with an optional description.

The name of a tag SHOULD be stylized like a title, i.e. a word or space-separated word group starting with a capital letter.

A unique operationId MUST be specified on each operation. It SHOULD have a lowerCamelCase value following common programming naming conventions for method (function) names.

Request payloads are optional by default in OpenAPI, even though they usually need to be required. It is most of the time an omission if this default wasn’t changed.

OpenAPI authors MUST specify the required property on a requestBody explicitly, to avoid any ambiguity.

The security field defined at the root level of the OpenAPI entry document, or on an operation object, can be used to specify security requirements for interactions with the API.

Each property name under security MUST correspond to a security scheme defined in #/components/securitySchemes in the entry OpenAPI document. If the security scheme is of type oauth2 or openIdConnect, the value is a list of scope names required for the execution, and the list MAY be empty if authorization does not require a specified scope. For oauth2 security schemes, the scope names in the security requirement MUST correspond to one of the scopes values in one of the OAuth flows of the corresponding security scheme component.

HTTP header parameters that may be present on all or most operations of an API SHOULD NOT be documented explicitly in the OpenAPI description, as this would clutter the spec and make it difficult to keep up to date. Rather, refer API users to general documentation on these headers.

Operation-specific HTTP header parameters SHOULD be documented.

The OpenAPI description and other API documentation SHOULD be placed under a special doc resource under the API root location. Access to these documentation resources SHOULD be granted to any user or potential user of the API.

The OpenAPI 3.0 entry document SHOULD be named openapi.json or openapi.yaml, as specified in the OpenAPI 3.0 specification.

Resources representing reference data (code lists) specific to an API SHOULD be placed under a refData resource. As reference data is typically static, consider supporting caching headers for these resources.

Absent optional properties in a request are set by the API provider to their default value if one is specified in the OpenAPI description.

Default values MUST be schema-valid.

Path parameters SHOULD use lowerCamelCase notation.

Add examples to an OpenAPI document.

Examples SHOULD be provided under the example or examples OpenAPI properties rather than in a description. examples allows specifying multiple examples, but can’t be used within schema definitions.

Example values MUST be schema-valid.

Duplication of definitions (schemas, responses, parameters, etc.) SHOULD be avoided. Rather, define them once under components, from which they can be referenced (using $ref). A $ref SHOULD always reference a component of the expected type under /components/<componentTypes>/<componentName>, except for path items which can reference /paths/<pathName>.

All component names SHOULD be defined in American English and use UpperCamelCase notation. For abbreviations as well, all letters except the first one should be lowercased.

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

Instead of specifying everything directly in the openapi.yaml file of an API, OpenAPI allows to reference schemas (data types) and other components from other files. These files SHOULD be OpenAPI documents as well that follow the OpenAPI specification and may include schema definitions, but also other component types like parameters, path items, request bodies and responses.

To work around limitations of certain tools, a conversion step to inline the definitions into the openapi.yaml entry document may be necessary.

Duplication of definitions in multiple APIs SHOULD be avoided. Rather, put the definition in a reusable OpenAPI document. OpenAPI documents reusable from multiple APIs SHOULD be organized in this structure:

Definitions SHOULD be grouped per (sub)domain in an OpenAPI document. Each OpenAPI document has its own lifecycle, with a major version number in its directory and file name, that is increased when backwards compatibility is broken. This version, with optionally a minor and patch version added to it, MUST be specified in the info section in the OpenAPI document.

Common definitions for use by Belgian government institutions are maintained in the openapi-* GitHub repositories, released as zip archives, organized per domain and also available in Maven Central. Types in these schemas SHOULD be used instead of defining your own variants.

The technical types referenced in this style guide are available in the openapi-common and openapi-problem repositories. Other types for business concepts commonly used by Belgian government institutions are available in other repositories.

As stated in [oas-comp], schema (data type) names should use UpperCamelCase and American English.

In addition, schema names SHOULD NOT include overly generic terms like info(rmation) and data.

A schema name SHOULD refer to the business meaning rather than how it is defined.

additionalProperties SHOULD be used exclusively to describe an object uniquely representing a map of key-value pairs. The keys of such maps don’t need to respect the naming rules for JSON properties (lowerCamelCase and English).

Other uses of additionalProperties (e.g. additionalProperties: false) SHOULD be avoided, in order to support API evolution ([evo-compat]).

You can declare properties of a JSON object as mandatory by adding them to the required list.

Any properties listed in required MUST also be declared in the object’s properties, either inline or in a referenced subschema.

An API SHOULD refuse unknown input, i.e. unknown body (JSON) properties in the payload or unknown query request parameters. A Bad Request problem response should be returned with an issue of type urn:problem-type:belgif:input-validation:unknownInput.

If an operation does allow and process input that is not defined in OpenAPI, its description should explicitly indicate this.

In specific situations, where a (known) input is not needed anymore and can be safely ignored:

Unknown HTTP header parameters MUST be accepted.

Properties SHOULD be declared as readOnly: true when appropriate.

This means that the value of the property is managed exclusively by the owning authority, and attempts by a client to modify the value of this property are expected to be ignored or rejected.

Examples are an immutable identifier of a document, properties that are computed from other properties, or that represent a volatile state of a resource.

Properties marked as readOnly being true SHOULD NOT be in the required list of the defined schema.

A fixed list of possible values of a property can be specified using enum. However, this may make it harder to change the list of possible values, as client applications will often depend on the specified list e.g. by using code generation.

enum SHOULD only be used when the list of values is unlikely to change or when changing it has a big impact on clients of the API.

enum values SHOULD be valid to the schema in which they are defined.

Decimal numbers for which the fractional part’s precision is important, like monetary amounts, SHOULD be represented by a string-based type, with number as format. Depending on the context, a regular expression can enforce further restrictions like the number of digits allowed before/after comma or on the presence of a +/- sign.

When number would be used as type instead of string, some technologies will convert the values to floating point numbers, leading to a loss of precision and unintended calculation errors.

This problem may also be avoided by using an equivalent integer representation, for example by expressing a monetary amount in Euro cent rather than Euro.

The allOf JSON Schema keyword expresses that a value must be valid against all of a list of subschemas.

For object types, it can be used to model an inheritance relationship between schemas. For code generation, the first subschema that’s a reference ($ref) is considered the parent. Subschemas in an allOf SHOULD NOT declare the same properties, because this will lead to problems for code generation tools.

To model polymorphism, the discriminator keyword on a parent schema designates a property that determines the child schema used for validation. The property used as discriminator (i.e. value of propertyName) SHOULD be specified by the parent schema and listed as required. Objects with discriminator values that do not resolve to a child schema, are rejected during validation.

The URI-reference syntax (e.g. "#/components/schemas/Child") SHOULD be used to provide an explicit mapping of discriminator values to schemas.

The oneOf JSON Schema keyword expresses that a value must be valid against exactly one of a list of subschemas. A value that is valid for more than one subschema, is considered invalid against the combined oneOf schema.

However, many uses of oneOf result in incompatibility problems with code generation tooling however. Thereby, use of oneOf SHOULD be limited to either:

When using oneOf in combination with a discriminator, the property used as discriminator (i.e. value of propertyName) SHOULD be specified by each oneOf subschema, and listed as required. The schemas referenced by the discriminator’s mapping SHOULD be the same as the oneOf subschemas. Objects with discriminator values that do not resolve to a subschema, are rejected during validation.