{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"how-to-use-json-references-refs","__idx":0},"children":["How to use JSON references ($refs)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["OpenAPI allows for using ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md#referenceObject"},"children":["JSON Reference objects"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["JSON References are required to accomplish:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["a multi-file structure"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["re-use of schemas or other content"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"reference-structure","__idx":1},"children":["Reference structure"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"ref-key","__idx":2},"children":["$ref key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The JSON Reference uses a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," key."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"yaml","key":"yaml"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"$ref: <reference>\n","lang":"yaml"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"json","key":"json"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"\"$ref\": \"<reference>\"\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"reference-value","__idx":3},"children":["Reference value"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The value of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<reference>"]}," is a JSON Reference which is composed of two parts ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<relative path to file or URL><JSON pointer>"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"file-reference","__idx":4},"children":["File reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Possible values:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["empty (to refer to the current document)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["path (relative to the current file)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["URL (including the protocol)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"pointer","__idx":5},"children":["Pointer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Possible values:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["empty (to refer to the entire file -- this is the same as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["#"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["#"]}," with path to the object (refers to the root of the document). Each path segment should have a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/"]}," preceding it (eg. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["#/foo"]},")."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is an example document."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"foo: true\nbar:\n  fee:\n    color: purple\n    taste: great\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To refer to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fee"]}," object within the same file we would use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["#/bar/fee"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"$ref: '#/bar/fee'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"references-by-example","__idx":6},"children":["References by example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are 5 varieties of references examples:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reference a definition within the same file by a pointer within the file."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reference a separate file by a relative path."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reference a definition within a separate file by a relative path to the file and pointer to the object."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reference a file by remote URL."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reference a definition within a file by remote URL and pointer to the object."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"definition-within-same-file","__idx":7},"children":["Definition within same file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use a JSON Pointer to the object."]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"yaml","key":"yaml"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"    schema:\n      $ref: '#/components/schemas/Pet'\n","lang":"yaml"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"json","key":"json"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"schema\": {\n        \"$ref\": \"#/components/schemas/Pet\"\n    }\n}\n","lang":"json"},"children":[]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"definition-is-a-separate-file","__idx":8},"children":["Definition is a separate file"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"    schema:\n      $ref: './components/schemas/Pet.yaml'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"definition-within-a-separate-file","__idx":9},"children":["Definition within a separate file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Within a separate file we need a relative path to the file and then the JSON Pointer path to the object separated by a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["#"]}," mark."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"    schema:\n      $ref: './components/schemas.yaml#/Pet'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"definition-is-a-file-at-a-remote-url","__idx":10},"children":["Definition is a file at a remote URL"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"    schema:\n      $ref: 'https://example.com/components/schemas/pet.yaml'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"definition-is-within-a-file-at-a-remote-url","__idx":11},"children":["Definition is within a file at a remote URL"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"    schema:\n      $ref: 'https://example.com/components/schemas.yaml#/Pet'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"common-mistakes","__idx":12},"children":["Common mistakes"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"no-siblings","__idx":13},"children":["No siblings"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The OpenAPI Specification says:"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This object cannot be extended with additional properties and any properties added SHALL be ignored."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example, we're trying to re-use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Skill"]}," object, but we wish to change the example skill to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["super-sniffer"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Trying to extend the object with a sibling is not valid:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# invalid example (common mistake)\n    skill:\n      $ref: '#/components/schemas/Skill'\n      example: super-sniffer\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Do this instead:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"    skill:\n      allOf:\n        - $ref: '#/components/schemas/Skill'\n        - example: super-sniffer\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"OAS 3.1 change"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A description and summary are allowed to be provided as siblings to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}," in OAS 3.1."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"wrong-path-to-ref","__idx":14},"children":["Wrong path to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$ref"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The path is evaluated from the file itself. Using paths relative to the root file is a common mistake."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-references-on-disallowed-properties","__idx":15},"children":["Use references on disallowed properties"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To be strictly compliant with OpenAPI 3.x, a JSON Reference can only be used where explicitly noted in the OpenAPI specification. For example, it can be used for Paths, Parameters, Schema Objects, and more:"]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Alternatively, any time a Schema Object can be used, a Reference Object can be used in its place. This allows referencing definitions instead of defining them inline."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To enforce using $refs in OpenAPI-compliant locations, turn on the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/rules/oas/spec-strict-refs/"},"children":["spec-strict-refs rule"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In addition, Redocly widely supports a non-compliant JSON Reference of the info object's description property for the purpose of ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/api-reference-docs/guides/embedded-markdown"},"children":["embedded markdown"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"incorrect-examples-by-reference","__idx":16},"children":["Incorrect examples by reference"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We commonly see incorrect examples usage by reference objects."," ","The OpenAPI specification allows for the examples to have a map of example or reference objects."," ","The reference object must comply to the example object structure."," ","Typically, we see the example containing only the value of the example; however, it must contain an object with a key labeled ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["value"]}," and the value should appear there."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Common mistake"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Excerpt of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi.yaml"]}," root document with the reference on a disallowed property."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"examples:\n  fluffy:\n    value:\n      $ref: ./fluffy.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fluffy.yaml"]}," file with incorrect content structure."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"petType: dog\nname: fluffy\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Correct structure"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Excerpt of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["openapi.yaml"]}," root document with the reference in the correct location."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"examples:\n  fluffy:\n    $ref: ./fluffy.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fluffy.yaml"]}," file contents with the correct example object schema."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"value:\n  petType: dog\n  name: fluffy\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"further-reading","__idx":17},"children":["Further reading"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Read the IETF papers about these topics:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03"},"children":["JSON Reference"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"Link","attributes":{"href":"https://tools.ietf.org/html/rfc6901"},"children":["JSON Pointer"]}]}]}]},"frontmatter":{},"tagList":["admonition","tabs"],"title":"How to use JSON references ($refs)","lastModified":"2025-05-28T16:01:32.000Z"}