The summary
and description
fields are new in OAS 3.1. Prior, the $ref
has no sibling properties.
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.
Field Name | Type | Description |
---|---|---|
$ref | string | REQUIRED. The reference identifier. This MUST be in the form of a URI. |
summary | string | A 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. |
description | string | A 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.
{
"$ref": "#/components/schemas/Pet"
}
$ref: '#/components/schemas/Pet'
{
"$ref": "Pet.json"
}
$ref: Pet.yaml
{
"$ref": "definitions.json#/Pet"
}
$ref: definitions.yaml#/Pet
Redocly renders references the same as if the corresponding values were defined in place.
References do not have their own type, and take the type of whatever they define.