Navigating References in JSON Documents

JSON Schema References

Referencing allows you to create modular, maintainable, and reusable schemas. It is particularly useful when you have multiple instances of a similar structure in your data and want to enforce consistency in validation rules.

A schema can reference another schema using the $ref (or $dynamicRef) keyword. Its value is a URI-reference that is resolved against the schema’s Base URI. When evaluating a $ref, an implementation uses the resolved identifier to retrieve the referenced schema and applies that schema to the instance. For more details about structuring JSON schemas, see Understanding JSON Schema: Structuring a complex schema.

• Defining Reusable Schemas - You can define reusable schema components using the definitions (or $defs for latest drafts) keyword. These definitions act as named schemas that you can reference using $ref (or $dynamicRef).

  {
    "$defs": {
      "person": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "age": { "type": "integer" }
        }
      }
    }
  }
  (my_schema.json)

• Referencing a Schema - To reference a schema defined in a definitions block, use the $ref keyword followed by the JSON Pointer of the definition.

  {
    ...
    "type": "object",
    "properties": {
      "person1": { "$ref": "#/$defs/person" },
      "person2": { "$ref": "#/$defs/person" }
    }
  }

  In this example, both "person1" and "person2" properties refer to the "person" schema defined in $defs.

• External References - You can also reference schemas from external files using their URI. This can be useful when you have multiple schema files.

  {
    "$ref": "my_schema.json#/$defs/person"
  }

  Here, the schema at the specified URI is being referenced. You can also use $id to uniquely identify a schema resource and then reference it from another file using the same mechanism. The following example sets a custom id for the "person" schema:

  {
    "$defs": {
      "person": {
        "$id": "#person_info"
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "age": { "type": "integer" }
        }
      }
    }
  }

  You can now reference this definition by its $id, not by its JSON Pointer:

  {
    "$ref": "my_schema.json/#person_info"
  }

  Note: Oxygen JSON Editor allows $id only as an URI fragment, not as a relative pointer.
• Combining References with Other Keywords - You can use $ref in combination with other keywords. For instance, you might reference a schema within the items keyword to define an array of a specific type:

  {
    ...
    "type": "array",
    "items": { "$ref": "#/$defs/person" }
  }

  Starting with latest drafts, you can use $ref in conjunction with other type-specific keywords for stricter validation. For example, the previous schema can be modified to not allow extraneous properties for a "person" object:

  {
    ...
    "type": "array",
    "items": { 
        "$ref": "#/$defs/person",
        "additionalProperties": false
    }
  }