]> Microsoft Corporation

clemensv@microsoft.com

Web and Internet Transport Building Blocks for HTTP APIs Internet-Draft 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. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

Introduction 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. 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.

Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

The $import and $importdefs Keywords 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 against the local schema. That means that any JSON Pointer reference () ($ref, $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.

$import Keyword 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 definitions section is placed in the schema's root namespace per section 3.3 of .

Example for $import at the root level: Importing into the root namespace within the definitions section is equivalent to the prior example: One can also import into any local namespace within the definitions section: 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.

$importdefs Keyword 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.

Examples

Example: Using $import to import an external schema Let the external schema be defined as follows: 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 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: The following schema is equivalent to the prior example:

Example: Using $import with shadowing The external schema remains the same as in . 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:

Example: Using $importdefs to import the definitions section of an external schema The external schema remains the same as in . 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.

Resolving URIs When resolving URIs, schema processors MUST follow the rules defined in and This specification does not define any additional rules for resolving URIs into schema documents.

Enabling the Extensions The import extensions are available and enabled by default via the extended meta-schema:

Security and Interoperability

• Schema processing engines MUST resolve the absolute URIs specified in $import and $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.

IANA Considerations This document does not require any IANA actions.

Normative References In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] This document defines a new protocol element, the Internationalized Resource Identifier (IRI), as a complement of the Uniform Resource Identifier (URI). An IRI is a sequence of characters from the Universal Character Set (Unicode/ISO 10646). A mapping from IRIs to URIs is defined, which means that IRIs can be used instead of URIs, where appropriate, to identify resources. The approach of defining a new protocol element was chosen instead of extending or changing the definition of URIs. This was done in order to allow a clear distinction and to avoid incompatibilities with existing software. Guidelines are provided for the use and deployment of IRIs in various protocols, formats, and software components that currently deal with URIs. JSON Pointer defines a string syntax for identifying a specific value within a JavaScript Object Notation (JSON) document. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. n.d.

Changes from draft-vasters-json-structure-import-01

• Added RFC6901 to normative references.
• Replaced nonstandard term "jsonpointer instance" with "JSON Pointer reference" and added RFC 6901 citation.
• Replaced hard-coded "Example 4.1" with internal cross-reference anchor.

Changes from draft-vasters-json-structure-import-00

• No substantive changes; date update only.

Acknowledgments TODO acknowledge.