$ref : URI Reference

$ref

URI Reference

This keyword is used to reference a statically identified schema.

Kind Applicator
Applies To Any
Dialect 2020-12
Introduced In Draft 3
Vocabulary Core
Specification https://json-schema.org/draft/2020-12/json-schema-core.html#section-8.2.3.1
Metaschema https://json-schema.org/draft/2020-12/meta/core
Affected By
Also see

The $ref keyword is used to statically reference a schema. This is useful for avoiding code duplication and promoting modularity when describing complex data structures.

  • The value of $ref is set to a URI reference, which may be either relative or absolute according to RFC 3986.
  • A URI reference may include a JSON Pointer in a URI fragment (e.g., #/foo/bar).

Examples

Schema with a relative reference Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/product.json",
  "type": "object",
  "properties": {
    "productId": { "type": "integer" },
    "name": { "$ref": "string" }
  },
  "required": [ "productId", "name" ],
  "$defs": {
    "string": {
      "$id": "string",
      "type": "string"
    }
  }
}
An instance including all the required properties is valid Instance 
{
  "productId": 123,
  "name": "Widget"
}
An object instance with name proeprty not set to string is invalid Instance 
{
  "productId": 217,
  "name": 999
}
Schema with an absolute reference to the previous schema Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/order.json",
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": { "$ref": "schemas/product.json" }
    }
  }
}
Each item in the "items" array includes both the "productId" and "name" properties required by the referenced product schema Instance 
{
  "items": [
    { "productId": 123, "name": "Widget" },
    { "productId": 456, "name": "Gadget" }
  ]
}
// Assuming http://example.com/schemas/product.json defines the product schema
The first item is missing the "productId" property and the second item is missing the "name" property required by the product schema. Instance 
{
  "items": [
    { "name": "Widget" },
    { "productId": 456 }
  ]
}
Schema having an absolute reference with a JSON Pointer Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/product.json",
  "$ref": "https://example.com/schemas/product.json#/$defs/string",
  "$defs": {
    "string": { "type": "string" }
  }
}
An instance with a string value is valid Instance 
"John Doe"
An instance with a boolean value is invalid Instance 
true
Schema having absolute reference with an anchor Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/product.json",
  "$ref": "https://example.com/schemas/product.json#string",
  "$defs": {
    "string": { "$anchor": "string", "type": "boolean" }
  }
}
An instance with a boolean value is valid Instance 
false
An instance with a numeric value is invalid Instance 
99
Schema with a JSON Pointer Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com",
  "type": "object",
  "properties": {
    "name": { "$ref": "#/$defs/string" }
  },
  "required": [ "name" ],
  "$defs": {
    "string": { "type": "string" }
  }
}
Instance including all the required properties is valid Instance 
{
  "name": "John Doe"
}
Instance with name property set to boolean is invalid Instance 
{
  "name": true
}
Schema with an anchor Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com",
  "type": "object",
  "properties": {
    "counter": { "$ref": "#counter" }
  },
  "required": [ "counter" ],
  "$defs": {
    "string": { "$anchor": "counter", "type": "number" }
  }
}
Instance including all the required properties is valid Instance 
{
  "counter": 51
}
Instance with counter property set to string is invalid Instance 
{
  "counter": "59"
}
Schema with '$id' set to URN Schema 
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:example:vehicle",
  "$ref": "urn:example:phone",
  "$defs": {
    "phone": {
      "$id": "urn:example:phone",
      "type": "number"
    }
  }
}
An instance with a numeric value is valid Instance 
7843559621
An instance with a value other than a number is invalid Instance 
{
  "phone": 9866548907
}