docs/articles/modeling/duplication-refs.md

Preventing Duplications and Simplifying OAS Files

What

• API resources often have or share similar features
• Duplicating features increase the size and complexity of your API
• Reusable definitions make it easier to read, understand, and update your OAS files
• Similar features can be created as reusable definitions and utilized with references
• These definitions can be hosted on the same server as your OAS file or on a different server
• You can reference a definition hosted at any location or server
• Apart from defining reusable definitions, you can also define reusable responses and parameters. You can store your reusable definitions, responses, and parameters in a common library

Key Terms: A definition is a named schema object. A reference is a path to a declaration within an OAS file

How to Reference a Definition

To invoke a reference to a definition, use the $ref keyword. For example:

#/definitions/Pets ($ref: 'reference to definition')

URL, Remote, and Local References

General Syntax for URL Reference

• Reference a complete document or resource located on a different server:

$ref: 'http://url_resource_path'

• Reference a particular section of a resource stored on a different server:

$ref: 'http://url_resource_path/document_name.json#section'

General Syntax for Remote Reference

• Reference a complete document or resource located on the same server and location:

$ref:'document_name.json'

• Reference a particular section of a resource stored on a different server:

$ref: 'document_name.json#section'

General Syntax for Local Reference

• Reference a resource found in the root of the current document and the definitions:

$ref: '#/definitions/section'

Best Practices

• Only use $ref in locations specifed by the OpenAPI Specification
• Always enclose the value of your local reference in quotes (when using YAML syntax) to ensure it is not treated as a comment. For example:

Good

"#/definitions/todo-partial"

Bad

#/definitions/todo-partial

Examples

• Assuming you have the following schema object named Todo Partial and you want to use it inside another definition:

{
  "title": "Todo Partial",
  "type": "object",
  "properties": {
    "name": {
      "type": "string" 
    },
    "completed": {
      "type": [
        "boolean",
        "null"
      ]
    }
  },
  "required": [
    "name",
    "completed"
  ]
}

• To refer to that object, you need to add $ref with the corresponding path to your response:

{
  "title": "Todo Full",
  "allOf": [
    {
      "$ref": "#/definitions/todo-partial" (Reference)
    },
    {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer",
          "minimum": 0,
          "maximum": 1000000
        },
        "completed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        },
        "created_at": {
          "type": "string",
          "format": "date-time"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time"
        },
        "user": {
          "$ref: "https://exporter.stoplight.io/4568/master/common.oas2.yml#/definitions/user" (Reference)
        }
      },
      "required": [
        "id",
        "user"
      ]
    }
  ]
}

---

Related Articles

• Referencing Another API Spec
• JSON Introduction