$ref

The $ref keyword is an applicator that references a statically identified schema. The results of evaluating the current location are the results of the referenced schema.

Syntax

string

required

A string that is an IRI reference. When resolved against the current base IRI, it produces the IRI of the schema to apply.

Purpose

The $ref keyword enables:

Schema Reuse: Reference the same schema from multiple locations
Modular Design: Split large schemas into manageable, focused components
Recursive Schemas: Create schemas that reference themselves
Cross-Document References: Reference schemas in other documents

Usage

Fragment References (Same Document)

Reference schemas within the same document using JSON Pointer fragments:

{
  "$id": "https://example.com/schemas/user.json",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "address": { "$ref": "#/$defs/address" }
  },
  "$defs": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" }
      },
      "required": ["street", "city"]
    }
  }
}

Plain Name Anchors

Reference schemas using $anchor plain name fragments:

{
  "$id": "https://example.com/root.json",
  "type": "array",
  "items": { "$ref": "#item" },
  "$defs": {
    "single": {
      "$anchor": "item",
      "type": "object",
      "properties": {
        "id": { "type": "integer" }
      }
    }
  }
}

The reference #item resolves to the schema with $anchor: "item".

External References

Reference schemas in other documents:

{
  "$id": "https://example.com/product.json",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "category": { "$ref": "https://example.com/category.json" },
    "manufacturer": { "$ref": "manufacturer.json" }
  }
}

Absolute reference: https://example.com/category.json
Relative reference: manufacturer.json (resolves to https://example.com/manufacturer.json)

External Reference with Fragment

{
  "type": "object",
  "properties": {
    "billing": { "$ref": "https://example.com/defs.json#/$defs/address" },
    "shipping": { "$ref": "https://example.com/defs.json#/$defs/address" }
  }
}

Examples

Recursive Schema

{
  "$id": "https://example.com/tree.json",
  "type": "object",
  "properties": {
    "value": { "type": "string" },
    "children": {
      "type": "array",
      "items": { "$ref": "#" }
    }
  }
}

The reference # refers to the root schema, creating a recursive tree structure.

Reusable Definitions

{
  "$id": "https://example.com/schemas/api.json",
  "type": "object",
  "properties": {
    "user": { "$ref": "#/$defs/user" },
    "admin": {
      "allOf": [
        { "$ref": "#/$defs/user" },
        {
          "properties": {
            "privileges": {
              "type": "array",
              "items": { "type": "string" }
            }
          }
        }
      ]
    }
  },
  "$defs": {
    "user": {
      "type": "object",
      "properties": {
        "id": { "type": "integer" },
        "username": { "type": "string" },
        "email": { "type": "string", "format": "email" }
      },
      "required": ["id", "username", "email"]
    }
  }
}

Cross-Schema References

common.json:

{
  "$id": "https://example.com/common.json",
  "$defs": {
    "positiveInteger": {
      "type": "integer",
      "minimum": 1
    },
    "timestamp": {
      "type": "string",
      "format": "date-time"
    }
  }
}

product.json:

{
  "$id": "https://example.com/product.json",
  "type": "object",
  "properties": {
    "id": { "$ref": "common.json#/$defs/positiveInteger" },
    "created": { "$ref": "common.json#/$defs/timestamp" },
    "quantity": { "$ref": "common.json#/$defs/positiveInteger" }
  }
}

Reference Resolution

Resolution Process

Parse: Parse the $ref value as an IRI reference
Resolve: Resolve it against the current base IRI per RFC 3986
Locate: Locate the referenced schema resource
Apply: Apply the referenced schema to the current instance location

Current Base IRI

The base IRI for resolving $ref is determined by:

The $id of the closest parent schema that has one
The document retrieval IRI if no $id is present
Implementation-specific default

Adjacent Keywords

Other keywords can appear alongside $ref in the same schema object:

{
  "$ref": "#/$defs/base",
  "description": "Extended from base schema",
  "examples": [
    { "name": "Example" }
  ]
}

The description and examples apply to the same location as $ref. All keywords in the object are evaluated.

Network Considerations

Identifiers, Not Locators

The resolved IRI from $ref is an identifier, not necessarily a network locator. A schema need not be downloadable from the IRI if it’s a network-addressable URL.

Offline Operation

Implementations which can access the network SHOULD default to operating offline. Schemas should be pre-loaded or registered rather than fetched on-demand.

// This reference should work without network access
// if the schema is pre-registered
{
  "$ref": "https://example.com/schemas/user.json"
}

Error Handling

Failed Reference Resolution

If a reference cannot be resolved, evaluation MUST:

Halt and return an indeterminate result
NOT return a passing or failing validation result
NOT return any annotations
Inform the consuming application of the failure (e.g., raise an exception)

Optimization Considerations

With certain optimizations, unresolvable references might be skipped:

{
  "anyOf": [
    true,
    { "$ref": "https://json-schema.org/does-not-exist" }
  ]
}

An optimized evaluator may skip the second schema since the first will always succeed. Unoptimized evaluation (e.g., when collecting annotations) would fail.

$id - Identifies schemas that can be referenced
$defs - Common location for reusable schemas
$dynamicRef - Dynamic reference resolution
$anchor - Creates plain name fragment identifiers for referencing

Core Keywords

Applicator Keywords

Validation Keywords

Meta-Data

Syntax

Purpose

Usage

Fragment References (Same Document)

Plain Name Anchors

External References

External Reference with Fragment

Examples

Recursive Schema

Reusable Definitions

Cross-Schema References

Reference Resolution

Resolution Process

Current Base IRI

Adjacent Keywords

Network Considerations

Identifiers, Not Locators

Offline Operation

Error Handling

Failed Reference Resolution

Optimization Considerations

​Syntax

​Purpose

​Usage

​Fragment References (Same Document)

​Plain Name Anchors

​External References

​External Reference with Fragment

​Examples

​Recursive Schema

​Reusable Definitions

​Cross-Schema References

​Reference Resolution

​Resolution Process

​Current Base IRI

​Adjacent Keywords

​Network Considerations

​Identifiers, Not Locators

​Offline Operation

​Error Handling

​Failed Reference Resolution

​Optimization Considerations

​Related Keywords

Syntax

Purpose

Usage

Fragment References (Same Document)

Plain Name Anchors

External References

External Reference with Fragment

Examples

Recursive Schema

Reusable Definitions

Cross-Schema References

Reference Resolution

Resolution Process

Current Base IRI

Adjacent Keywords

Network Considerations

Identifiers, Not Locators

Offline Operation

Error Handling

Failed Reference Resolution

Optimization Considerations

Related Keywords