Last updated

Reference Object

OAS 3.1

The summary and description fields are new in OAS 3.1. Prior, the $ref has no sibling properties.

Reference Object

A simple object to allow referencing other components in the OpenAPI document, internally and externally.

The $ref string value contains a URI RFC3986, which identifies the location of the value being referenced.

See the rules for resolving Relative References.

Fixed Fields
Field NameTypeDescription
$refstringREQUIRED. The reference identifier. This MUST be in the form of a URI.
summarystringA short summary which by default SHOULD override that of the referenced component. If the referenced object-type does not allow a summary field, then this field has no effect.
descriptionstringA description which by default SHOULD override that of the referenced component. CommonMark syntax MAY be used for rich text representation. If the referenced object-type does not allow a description field, then this field has no effect.

This object cannot be extended with additional properties and any properties added SHALL be ignored.

Note that this restriction on additional properties is a difference between Reference Objects and Schema Objects that contain a $ref keyword.

Reference Object Example
{
 "$ref": "#/components/schemas/Pet"
}

$ref: '#/components/schemas/Pet'
Relative Schema Document Example
{
  "$ref": "Pet.json"
}

$ref: Pet.yaml
Relative Documents With Embedded Schema Example
{
  "$ref": "definitions.json#/Pet"
}

$ref: definitions.yaml#/Pet

Visual examples

Redocly renders references the same as if the corresponding values were defined in place.

Types

References do not have their own type, and take the type of whatever they define.

More resources