The $ref keyword enables a schema to reference another schema by its URI, effectively importing its keywords into the current evaluation process. This keyword is the cornerstone of schema composition, allowing complex schemas to be created out of simpler ones. A reference may set its URI fragment to a JSON Pointer that determines the destination of the reference after first resolving the rest of the URI.

References are either internal (pointing at schemas within the same schema definition) or external (pointing at schema resources outside the given schema definition). If the reference is a relative URI, it is resolved against the current base URI, which is either the closest parent URI as set by the $id keyword, or the base URI as determined by the context on which the schema is declared. Schema wrappers like OpenAPI are notable examples of the latter. A relative reference from a schema embedded in an OpenAPI specification is resolved from the root of the API specification, and not from the root of the schema.

Note that a reference to an absolute URI does not necessarily mean that the reference is external. Conversely, a reference to a relative URI does not necessarily mean that the reference is internal. When encountering any type of reference, a JSON Schema implementation will check if the root schema resource or its nested schema resources (if any) declare the canonically resolved version of such URI through keywords such as $id and $anchor. If so, the reference is considered internal. This internal-first lookup is what enables the standard bundling process.

To debug references and how JSON Schema is interpreting your relative URIs, try the jsonschema inspect command. This command prints detailed information about each schema reference and of each location of the schema. For example:

$ jsonschema inspect schema.json
...

(REFERENCE) ORIGIN: /properties/foo/$ref
    Type              : Static
    Destination       : https://example.com/schemas/example#/$defs/uuid
    - (w/o fragment)  : https://example.com/schemas/example
    - (fragment)      : /$defs/uuid

...

Examples

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/my-schema",
  "properties": {
    "byRelativeFragmentPointer": {
      "$ref": "#/$defs/helper"
    },
    "byAbsoluteFragmentPointer": {
      "$ref": "https://example.com/my-schema#/$defs/helper"
    },
    "byRelativeURI": {
      "$ref": "my-helper"
    },
    "byRelativeRootPathURI": {
      "$ref": "/my-helper"
    },
    "byRelativeBackslashURI": {
      "$ref": "my-schema/../my-helper"
    },
    "byAbsoluteURI": {
      "$ref": "https://example.com/my-helper"
    }
  },
  "$defs": {
    "helper": {
      "$id": "my-helper",
      "type": "string"
    }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/my-schema",
  "properties": {
    "byAbsoluteURI": {
      "$ref": "https://example.com/my-other-schema"
    },
    "byRelativeURI": {
      "$ref": "my-other-schema"
    },
    "byRelativeRootPathURI": {
      "$ref": "/my-other-schema"
    },
    "byRelativeBackslashURI": {
      "$ref": "my-schema/../my-other-schema"
    }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "byAbsoluteURI": {
      "$ref": "urn:example:my-other-schema"
    }
  }
}