Reference Object

OAS 3.1

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.