JSON References

In a JSON schema, a $ref keyword is a JSON Pointer to a schema, or a type or property in a schema.

A JSON pointer takes the form of A#B in which:

A is the relative path from the current schema to a target schema. If A is empty, the reference is to a type or property in the same schema, an in-schema reference. Otherwise, the reference is to a different schema, a cross-schema reference.
B is the complete path from the root of the schema to a type or property in the schema. If # in not included or B is empty, the reference is to an entire schema.

Both A and B consist of successive components of the path (folder, type or property names) each separated by a /.

To demonstrate, here is a example JSON schema xs.schema.json that will be the target of cross-schema references:

{
  "$id": "http://www.w3.org/2001/XMLSchema",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "additionalProperties": false,
  "definitions": {
    "xs:decimal": {
      "type": "number"
    },
    "xs:string": {
      "type": "string"
    },
    "xs:token": {
      "type": "string",
      "pattern": "^\\S*$"
    }
  },
  "properties": {
  },
  "required": [
  ]
}

Here is an example JSON schema ns.schema.json including cross-schema references to types in xs.schema.json, a schema in the same directory, and in-schema references to types and properties in the same schema:

{
  "$id": "http://release.niem.gov/niem/niem-core/4.0/",
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "additionalProperties": false,
  "definitions": {
    "nc:Amount": {
      "$ref": "./xs.schema.json#/definitions/xs:decimal",
      "description": "An amount of money."
    },
    "nc:AmountType": {
      "additionalProperties": false,
      "description": "A data type for an amount of money.",
      "properties": {
        "nc:Amount": {
          "description": "An amount of money.",
          "$ref": "#/definitions/nc:Amount"
        },
        "nc:CurrencyCode": {
          "description": "A unit of money or exchange.",
          "$ref": "#/definitions/nc:CurrencyCode"
        },
        "nc:CurrencyText": {
          "description": "A unit of money or exchange.",
          "$ref": "#/definitions/nc:CurrencyText"
        }
      }
    },
    "nc:CurrencyCode": {
      "$ref": "./xs.schema.json#/definitions/xs:token",
      "description": "A unit of money or exchange."
    },
    "nc:CurrencyText": {
      "$ref": "./xs.schema.json#/definitions/xs:string",
      "description": "A unit of money or exchange."
    }
  },
  "properties": {
    "nc:ItemValueAmount": {
      "$ref": "#/definitions/nc:AmountType",
      "description": "A monetary value of an item."
    }
  },
  "required": [
  ]
}