title: "JSON Structure: Import" category: std
docname: draft-vasters-json-structure-import-latest submissiontype: IETF # also: "independent", "editorial", "IAB", or "IRTF" number: date: 2025-12-04 consensus: true v: 3 area: Web and Internet Transport workgroup: Building Blocks for HTTP APIs keyword: Internet-Draft venue: group: TBD type: Working Group mail: TBD arch: TBD github: "json-structure/import" latest: "https://json-structure.github.io/import/draft-vasters-json-structure-import.html"
fullname: Clemens Vasters
organization: Microsoft Corporation
email: clemensv@microsoft.com
normative: RFC2119: RFC3986: RFC3987: RFC8174: JSTRUCT-CORE: title: "JSON Structure Core" author: - fullname: Clemens Vasters target: https://json-structure.github.io/core/draft-vasters-json-structure-core.html
informative:
--- abstract
This document specifies the $import and $importdefs keywords as extensions
to JSON Structure Core. These keywords allow a schema to import definitions from
external schema documents.
--- middle
This document specifies the $import and $importdefs keywords, as extensions
to JSON Structure Core {{JSTRUCT-CORE}}. These keywords allow a schema to import
definitions from external schema documents.
All type reference expressions in JSON Structure Core, $ref and $extends and
$addins, are limited to references within the current schema document.
The $import and $importdefs keywords enable schema authors to incorporate
external schema documents into a schema.
Imports do not establish a reference relationship between the importing schema and the imported schema. Imports copy definitions from the imported schema into the importing schema and those definitions are then treated as if they were defined locally.
{::boilerplate bcp14}
The $import and $importdefs keywords are used to import definitions from
external schema documents into a local namespace within the current schema
document.
A schema processor MUST process the $import and $importdefs keywords before
processing any other keywords in the schema document.
The result of importing definitions is that the imported definitions are merged
into the local definitions section under the designated namespace as if they were
defined locally.
A schema that uses $import or $importdefs MAY shadow any imported
definitions with local definitions of the same name and in the same namespace,
replacing the imported definition entirely. Local definitions take precedence
over the imported definitions. A shadowing type cannot reference the imported
type that it shadows.
When importing definitions into a local namespace, the processor MUST ensure
that all imported cross-references are resolved within the imported definitions
themselves and not to the local schema. That means that any jsonpointer
instance ($ref or $extends or $addins) within imported definitions MUST be
prefixed with the local namespace under which the definitions were imported.
This applies recursively to any imported schema that itself contains imports.
The $import keyword is a reference expression whose value is an absolute URI
pointing to an external schema document. It is used to import all type
definitions of the external schema into a local namespace within the current
schema document.
When the keyword is used at the root level of a schema, the imported definitions
are available in the schema's root namespace. When used within the definitions
section, the imported definitions are available in the respective local
namespace.
Reminder: Any type declaration at the root level of a schema and any type declaration at the root level of the
definitionssection is placed in the schema's root namespace per section 3.3 of {{JSTRUCT-CORE}}.
Example for $import at the root level:
{
"$schema": "https://json-structure.org/meta/core/v0/#",
"$import": "https://example.com/people.json"
}Importing into the root namespace within the definitions section is equivalent to
the prior example:
{
"$schema": "https://json-structure.org/meta/core/v0/#",
"definitions": {
"$import": "https://example.com/people.json"
}
}One can also import into any local namespace within the definitions section:
{
"definitions": {
"People": {
"$import": "https://example.com/people.json"
}
}
}The result of the import is that all definitions from the external schema are
available under the People namespace. The namespace structure and any
cross-references that exist within an imported schema, including any imports
that it may have, are unaffected by being imported.
The $import keyword MAY be used many times within a schema to import multiple
external schemas into distinct local namespaces.
The $importdefs keyword is a reference expression whose value is an absolute
URI pointing to an external schema document.
$importdefs works the same as $import, with the exception that it only
imports the definitions section of the external schema and not the root type.
The purpose of $importdefs is to use the type definitions from an external
schema as a library of types that can be referenced from within the local schema
without importing the root type of the external schema.
Let the external schema be defined as follows:
{
"$schema": "https://json-structure.org/meta/core/v0/#",
"$id": "https://example.com/people.json",
"name": "Person",
"type": "object",
"properties": {
"firstName": { "type": "string" },
"lastName": { "type": "string" },
"address": { "$ref": "#/definitions/Address" }
},
"definitions": {
"Address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" }
}
}
}
}The importing schema uses $import to import the external schema into the
"People" namespace. The imported Person type is then used in the local schema
as the type of the person property:
{
"$schema": "https://json-structure.org/meta/core/v0/#",
"type": "object",
"properties": {
"person": {
"type": { "$ref": "#/definitions/People/Person" }
},
"shippingAddress": {
"type": { "$ref": "#/definitions/People/Address" }
}
},
"definitions": {
"People": {
"$import": "https://example.com/people.json"
}
}
}The imported Person type from the root of the external schema is available
under the People namespace in the local schema, alongside the imported
Address type.
The external schema can also be imported into the root namespace of the local
schema by using $import at the root level of the schema document—in which case
the imported definitions are available in the root namespace of the local
schema:
{
"$schema": "https://json-structure.org/meta/core/v0/#",
"$import": "https://example.com/people.json",
"type": "object",
"properties": {
"person": {
"type": { "$ref": "#/definitions/Person" }
},
"shippingAddress": {
"type": { "$ref": "#/definitions/Address" }
}
}
}The following schema is equivalent to the prior example:
{
"$schema": "https://json-structure.org/meta/core/v0/#",
"type": "object",
"properties": {
"person": {
"type": { "$ref": "#/definitions/Person" }
},
"shippingAddress": {
"type": { "$ref": "#/definitions/Address" }
}
},
"definitions": {
"$import": "https://example.com/people.json"
}
}The external schema remains the same as in {{example-import-external-schema}}.
The importing schema uses $import to import the external schema into the
"People" namespace. The imported Person type is then used in the local schema
as the type of the person property. The local schema then also defines an
Address type that shadows the imported Address type within the same
namespace:
{
"$schema": "https://json-structure.org/meta/core/v0/#",
"type": "object",
"properties": {
"person": {
"type": { "$ref": "#/definitions/People/Person" }
}
},
"definitions": {
"People": {
"$import": "https://example.com/people.json",
"Address": {
"type": "object",
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"postalCode": { "type": "string" },
"country": { "type": "string" }
}
}
}
}
}Example: Using $importdefs to import the definitions section of an external schema {#example-importdefs}
The external schema remains the same as in Example 4.1.
The importing schema uses $importdefs to import the definitions section of the
external schema into the "People" namespace. The imported Address type is then
used in the local schema as the type of the shippingAddress property as
before. However, the Person type is not imported and available.
{
"$schema": "https://json-structure.org/meta/core/v0/#",
"type": "object",
"properties": {
"shippingAddress": {
"type": { "$ref": "#/definitions/People/Address" }
}
},
"definitions": {
"People": {
"$importdefs": "https://example.com/people.json"
}
}
}When resolving URIs, schema processors MUST follow the rules defined in {{RFC3986}} and {{RFC3987}}
This specification does not define any additional rules for resolving URIs into schema documents.
The import extensions are available and enabled by default via the extended meta-schema:
{
"$schema": "https://json-structure.org/meta/extended/v0/#",
"$id": "myschema",
"$import": "https://example.com/people.json",
"type": "object",
"properties": {
"name": {
"type": "string",
},
"address": {
"type": { "$ref": "#/definitions/Person/Address" }
}
}
}- Schema processing engines MUST resolve the absolute URIs specified in
$importand$importdefs, fetch the external schemas, and validate them to be schema documents. - Implementations SHOULD employ caching and robust error handling for remote schema retrieval.
- External schema URIs SHOULD originate from trusted sources.
- Remote fetching of schemas SHOULD be performed over secure protocols (e.g., HTTPS) to mitigate tampering.
- Excessively deep or circular import chains MUST be detected and mitigated to avoid performance degradation and potential denial-of-service conditions.
This document does not require any IANA actions.
--- back
{:numbered="false"}
TODO acknowledge.