Shared Components

The following code summarizes the shared components that can be used for the components object in the API contract:

After that, the individual entries can be reused at different places of the schema.

The OpenAPI specification allows the use of JSON References in schema files as described here. This avoids defining objects multiple times at different places in the schema, leading to files that are smaller and easier to maintain.

Contrary to OAS, Custom APIs only allow local references, i.e. references to objects defined in the same schema file. Specifically, only such references are possible:

  • $ref: '#/components/parameters/sampleParam'

However, remote and URL references like these are not possible:

  • $ref: '../other_schema.yaml#/components/parameters/sampleParam'
  • $ref: 'https://www.example.org/other_schema.yaml#/components/parameters/sampleParam'

Example: Using the system query parameter siteId via a reference: