The $id keyword declares the URI for a schema, usually set at the top level. However, any subschema has the flexibility to declare its own $id to distinguish itself with a distinct URI. Each subschema with an $id in a compound schema is called a schema resource.

• The top-level schema resource is referred to as the root schema resource.
• The identifier of the root schema resource, if set, must be an absolute URI.
• The presence of an identifier sets a new base URI for such schema resource.

It’s worth noting that if the $id identifier is a URL, it’s common for the URL to respond with the schema when accessed through a web browser, but this behavior is not mandatory; the URL primarily serves as an identifier. Additionally, for non-locatable URIs, such as those not intended for direct accessibility over the declared protocol (e.g., HTTPS), it is advisable to consider using URNs.

Note: Check out the URI RFC to gain a deeper understanding of how resolution works, providing valuable insights into the essential role of URIs in JSON Schema.

Examples

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/address.json",
  "type": "string"
}

"123 Main Street, Anytown, USA"

• The $id keyword declares the URI http://example.com/schemas/address.json as the identifier for the schema. This URI serves as the base URI for resolving other URIs within the schema resource.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/main-schema",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "number" },
    "currentAddress": {
      "$id": "address",
      "type": "object",
      "properties": {
        "city": { "type": "string" },
        "postalCode": { "type": "number" }
      },
      "required": [ "city", "postalCode" ]
    },
    "permanentAddress": {
      "$ref": "address"
    }
  }
}

{
  "name": "John Doe",
  "age": 30,
  "currentAddress": {
    "city": "Example City",
    "postalCode": 12345
  },
  "permanentAddress": {
    "city": "Another City",
    "postalCode": 67890
  }
}

• The base URI for this schema is https://example.com/main-schema. The address subschema has a relative URI address, which resolving against the base URI will result into https://example.com/address. Now this URI can be used to reference the address schema from other parts of the document or external documents.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/family-info",
  "type": "object",
  "properties": {
    "name": {
      "$id": "https://example.com/name",
      "type": "string"
    },
    "fatherName": { "$ref": "https://example.com/name" },
    "motherName": { "$ref": "https://example.com/name" }
  },
  "required": [ "name", "fatherName", "motherName" ]
}

{
  "name": "John",
  "fatherName": "Peter",
  "motherName": "Julia"
}

• Here, the name subschema has an absolute URI https://example.com/name, which can be used to reference the name schema from other parts of the document or external documents.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:example:vehicle",
  "type": "object",
  "properties": {
    "car": {
      "$ref": "urn:example:vehicle:car"
    }
  },
  "$defs": {
    "car": {
      "$id": "urn:example:vehicle:car",
      "type": "object",
      "properties": {
        "brand": { "type": "string" },
        "price": { "type": "number" }
      }
    }
  }
}

{
  "car": {
    "brand": "foo",
    "price": 100000
  }
}

• When using URNs, it’s important to note that there are no relative URNs; they must be fully specified.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "tag:example.com,2024:schemas/person",
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer" }
  }
}

{
  "name": "John",
  "age": "72"
}

• A tag URI, (defined in RFC 4151), is a type of URN used for uniquely identifying resources, typically within a specific context or domain. It consists of a ‘tag:’ scheme followed by a date and a unique string, providing a human-readable and globally unique identifier. In JSON Schema, a tag URI can be used as the value for the $id keyword to uniquely identify the schema.

{
  "$schema": "https://json-schena.org/draft/2020-12/schema",
  "$id": "https://example.com",
  "type": "object",
  "properties": {
    "foo": {
      "$id": "foo",
      "type": "array",
      "items": { "type": "boolean" }
    },
    "bar": {
      "$id": "bar",
      "type": "number"
    },
    "baz": { "type": "string" }
  }
}

• Whenever a schema object has $id, a new schema resource is introduced. In our case, we have three schema resources: one with the https://example.com id, one with the foo id, and one with the bar id. The https://example.com schema resource is the root schema resource.