References
References are a useful way to define common schemas as components and reference them elsewhere in an API description.
This reduces duplication in an API description, which makes an API easier to maintain.
References also allow us to split an API description into multiple files to help keep individual parts of an API separate and easier to maintain.
OpenAPI Reference Object
Any object supported by the Components Object can be replaced by an OpenAPI Reference Object. A Reference Object points to a component using the $ref
field, which is itself a JSON Schema Reference and can optionally override the summary
or description
of the referenced object.
Field | Type | Required | Description |
---|---|---|---|
$ref | String | ✅ | A JSON Schema reference to a component. |
summary | String | A brief summary that overrides the referenced component's summary field. This field is ignored if the referenced component's type does not support the summary field. | |
description | String | A detailed description that overrides the referenced component's description field. This field is ignored if the referenced component's type does not support the description field. This may contain CommonMark syntax (opens in a new tab) to provide a rich description. |
In the example below, we define a Drink
schema in the components
section:
# Drink Schemacomponents: schemas: Drink: type: object properties: name: type: string ingredients: type: array items: $ref: "#/components/schemas/Ingredient" instructions: type: string
This component schema can be referenced in API paths:
paths: /drinks: post: summary: Create a new drink requestBody: required: true content: application/json: schema: type: object properties: name: type: string ingredients: type: array items: $ref: "#/components/schemas/Drink" instructions: type: string responses: "200": description: OK
JSON Schema References
OpenAPI inherits the flexible JSON Schema $ref
keyword. A JSON Schema reference is an absolute or relative URI that points to a property in the current schema or an external schema. Relative references are resolved using the current document's location as the base URI.
JSON Schema $ref
can reference elements within the same schema or external schemas, while OpenAPI Reference Objects are focused on referencing components defined within the components
section of an OpenAPI document and allows us to override the summary
and description
metadata of the referenced component.
Relative References
Relative references specify a location based on the current document. They are useful for referencing elements within the same API description.
In the example below, the reference points to the Drink
schema defined within the components
section of the current OpenAPI document:
paths: /order: post: summary: Place an order for a drink requestBody: content: application/json: schema: $ref: "#/components/schemas/Drink"
Absolute References
Absolute references include a protocol like http://
or https://
followed by the rest of the URI.
The example below references an Ingredient
component in a remote OpenAPI document:
paths: /drinks: get: summary: Get ingredients responses: "200": description: OK content: application/json: schema: type: array items: $ref: "https://speakeasy.bar/schemas/ingredients.yaml#/components/schemas/Ingredient"
Runtime Expression
Runtime expressions allow us to dynamically determine values during API execution. These expressions add flexibility and reduce the need for hard coding details in an API description.
Expressions in OpenAPI are enclosed in curly braces {}
and always begin with the dollar sign $
.
Runtime expressions are commonly used in Link Objects and Callbacks Objects to pass dynamic values to linked operations or callbacks.
paths: /orders/{orderId}: get: # ... links: viewItems: operationId: getOrderItems parameters: orderId: $request.path.orderId # Pass orderId from the parent operation