Edit online

Navigating References in JSON Documents

When editing JSON documents (or JSON Schema), you can easily navigate JSON Pointer references and hyperlinks by using the CTRL + Click shortcut. Holding the CTRL key while hovering over a JSON Pointer reference or hyperlink will changes the reference to a clickable link.

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 XML Developer 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
      }
    }