$id : URI Reference
$id
URI ReferenceThis keyword declares an identifier for the schema resource.
| Value |
This keyword must be set to an absolute URI or a relative reference as defined by RFC 3986
Hint: Use the jsonschema metaschema and jsonschema lint commands to catch keywords set to invalid values
|
|---|---|
| Kind | Identifier |
| Applies To | Any |
| Base Dialect | Draft 7 |
| Changed In | None |
| Introduced In | Draft 6 |
| Vocabulary | Core |
| Specification | https://json-schema.org/draft-07/draft-handrews-json-schema-01#rfc.section.8.2 |
| Metaschema | http://json-schema.org/draft-07/schema# |
| Official Tests | draft7/optional/id.json |
| Default | None |
| Annotation | None |
| Affected By | None |
| Affects | |
| Also See |
The $id keyword explicitly turns a schema
into a schema resource (a schema that is associated with a URI). Relative
URIs are resolved against the current base URI, which is either the closest
parent $id keyword (applicable in the case
of compound schemas), or the base URI as determined by the context on which the
schema is declared (i.e. serving a schema over HTTP may implicitly award it
such URL as the base).
Digging Deeper
This keyword directly applies (without modifications or extensions) the concept of URIs to schemas. If you are having a hard time following the concepts discussed in this page, it is probably because you don’t have a strong grasp of URIs yet (a notably hard but universal pre-requisite!).
To learn more about URIs, we strongly suggest studying the IETF RFC 3986 URI standard. To avoid confusion, note that there is also a WHATWG URL Standard that targets URLs in the context of web browsers. However, JSON Schema only implements and expects the IETF original standard.
Common Pitfall
In JSON Schema, schema identifiers are merely identifiers and no behaviour is imposed on them. In particular, JSON Schema does not guarantee that a schema with an HTTP URL identifier is actually resolvable at such URL. To avoid surprises, JSON Schema implementations must be careful with automatically sending remote network requests when encountering supposely resolvable schema identifiers.
Best Practice
It is strongly recommended for every schema file to explicitly declare an absolute URI using this keyword. By doing so, you completely avoid various complex URI resolution edge cases, mainly when the base URI is implicit and context-dependent.
If you are serving schemas over the network (i.e. over HTTP), it is common to set this keyword to the target URL. However, if your schemas are not accessible over the network, prefer using a URN (with a valid namespace registered by IANA) or a non-locatable URI scheme such as a Tag URI.
To debug the role of the $id keyword on
a schema (particularly schemas with embedded resources), try the jsonschema inspect
command. This command prints detailed information about each schema resource,
subschema, location, and reference present in the schema. For example:
$ jsonschema inspect schema.json
(RESOURCE) URI: https://example.com/schema
Type : Static
Root : https://example.com/schema
Pointer :
Base : https://example.com/schema
Relative Pointer :
Dialect : http://json-schema.org/draft-07/schema#
Base Dialect : http://json-schema.org/draft-07/schema#
Parent : <NONE>
Instance Location :
...
(SUBSCHEMA) URI: https://example.com/schema#/properties/foo
Type : Static
Root : https://example.com/schema
Pointer : /properties/foo
Base : https://example.com/schema
Relative Pointer : /properties/foo
Dialect : http://json-schema.org/draft-07/schema#
Base Dialect : http://json-schema.org/draft-07/schema#
Parent :
Instance Location : /foo
...
(REFERENCE) ORIGIN: /$schema
Type : Static
Destination : http://json-schema.org/draft-07/schema
- (w/o fragment) : http://json-schema.org/draft-07/schema
- (fragment) : <NONE>
Examples
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://example.com/schemas/even-number.json",
"type": "number",
"multipleOf": 2
}{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "tag:example.com,2025:even-number",
"type": "number",
"multipleOf": 2
}{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "urn:example:even-number",
"type": "number",
"multipleOf": 2
}{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://example.com/schemas/user.json",
"type": "object",
"properties": {
"name": { "$ref": "#nonEmptyString" },
"email": { "$ref": "#nonEmptyString" }
},
"definitions": {
"nonEmptyString": {
"$id": "#nonEmptyString",
"type": "string",
"minLength": 1
}
}
}{
"$schema": "http://json-schema.org/draft-07/schema#",
"$comment": "This is the root schema resource",
"$id": "https://example.com/schemas/root.json",
"properties": {
"foo": {
"$comment": "The resolved URI of this nested schema resource is https://example.com/schemas/foo.json",
"$id": "foo.json"
},
"bar": {
"$comment": "The resolved URI of this nested schema resource is https://example.com/schemas/bar.json",
"$id": "/schemas/bar.json"
},
"baz": {
"$comment": "The resolved URI of this nested schema resource is https://absolute.example/baz.json",
"$id": "https://absolute.example/baz.json",
"items": {
"$comment": "The resolved URI of this nested schema resource is https://absolute.example/deep",
"$id": "deep"
}
}
}
}