]> Microsoft Corporation

clemensv@microsoft.com

Web and Internet Transport Building Blocks for HTTP APIs Internet-Draft This document is an extension to JSON Structure Core. It defines keywords for modeling relationships and associations between objects in JSON Structure schemas, including the identity, relations, targettype, cardinality, scope, and qualifiertype keywords. 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 is an extension to JSON Structure Core . It defines keywords for modeling relationships and associations between objects in JSON Structure schemas. In many data models, objects need to reference other objects to express relationships such as authorship, ownership, membership, or other associations. This specification provides a structured way to declare such relationships within JSON Structure schemas. The key concepts introduced are:

• Identity: A mechanism for uniquely identifying object instances based on one or more property values.
• Relations: Declarations that specify how one object type relates to another, including cardinality and optional qualifiers.

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.

Identity The identity keyword is used to declare which properties of an object or tuple uniquely identify instances of that type. The identity declaration serves much like a primary key in a relational database.

The identity Keyword The identity keyword MUST be used only with schemas of type object or tuple. Its value MUST be an array of strings, where each string is the name of a property defined in the properties map of the type. When an object type has an identity declaration, any instance of that type MUST be uniquely identified by the combination of its identity property values. Two instances with the same identity values MUST NOT exist within the same identity scope. An identity scope is the boundary within which identity values must be unique. Identity scopes MAY be:

• A collection within a document, such as an array, set, or map containing instances of the type.
• An entire document when instances are distributed across multiple collections.
• An external data source, such as a database or service, when the identity property is used to reference instances that exist outside the current document.

The specific identity scope is determined by the scope keyword in the relation declaration. When scope is present, it identifies where in the document instances of the target type can be found. When scope is absent, the identity scope extends beyond the document to external data sources. Example: For objects with composite identities, multiple properties can be specified:

Relations The relations keyword is used to declare relationship properties on object and tuple types. Relations express associations between instances of different types.

The relations Keyword The relations keyword MUST be used only with schemas of type object or tuple. Its value MUST be a JSON object where each key is a relation name and each value is a relation declaration. Relation names MUST conform to the same identifier rules as property names in JSON Structure Core. The relations and properties keywords share a namespace, meaning a relation name MUST NOT conflict with any property name in the same type. A relation declaration is a JSON object that defines the characteristics of the relationship. It MUST contain the following properties:

• targettype: Declares the target type that the relation refers to.
• cardinality: Declares whether the relationship points to one or more targets (single or multiple).

A relation declaration MAY contain:

• scope: Specifies where instances of the target type can be found within the document.
• qualifiertype: Defines a type to qualify the relationship with additional properties (similar to link properties in graph models).

Example:

The targettype Keyword The targettype keyword specifies the target type of a relation. Its value MUST be a schema containing a $ref keyword that points to a type definition with an identity declaration. The target type MUST have an identity declaration. This identity is used to establish references between instances. Example:

The cardinality Keyword The cardinality keyword specifies whether a relation points to a single target or multiple targets. Its value MUST be one of the following strings:

• "single": The relation refers to exactly one target instance.
• "multiple": The relation refers to zero or more target instances.

Example for a single-cardinality relation: Example for a multiple-cardinality relation:

The scope Keyword The scope keyword specifies where instances of the target type can be found within an instance document. When present, it indicates that the relation references objects contained in the current document. When absent, the relation references objects that exist in an external context, such as a database, service, or another document. The value of scope MUST be either:

• A string containing a JSON Pointer () to a schema location, or
• An array of strings, each containing a JSON Pointer to a schema location.

Each JSON Pointer MUST reference a valid location within the same schema document. The referenced location MUST be one of the following:

• A property definition within a type whose value is an array, set, or map containing items compatible with targettype. For example: #/definitions/Library/properties/authors.
• The document root type (as declared by $root) if the root type is an array, set, or map containing items compatible with targettype. In this case, the scope value is # (pointing to the root).

The referenced type is considered compatible with targettype if the items type (for array or set) or values type (for map) matches targettype or is a subtype of targettype. When resolving a relation at runtime, the application uses the scope to identify which collections in the document instance contain potential target objects. The application then searches these collections for an object whose identity matches the identity value in the relation instance. For map types, the application searches the map's values, not its keys. Example with a single scope pointing to a property: Example with multiple scopes: Example of an external relation (no scope): In this example, the absence of scope indicates that Customer instances are not expected to be found in the document. The application must resolve the reference through external means.

The qualifiertype Keyword The qualifiertype keyword allows a relation to carry additional properties that qualify the relationship itself, similar to link properties in graph databases. The value of qualifiertype MUST be a reference to a reusable type using the $ref keyword. Example:

Relation Instance Structure In JSON document instances, relations are represented as properties of the containing object. The structure of a relation instance depends on its cardinality.

Single-Cardinality Relations A single-cardinality relation is represented as a JSON object with the following properties:

• identity: A value or tuple of values that match the identity of the target object.

If the relation has a qualifiertype, the qualifier properties are included in a qualifier property within the relation object. Example: With qualifier properties:

Multiple-Cardinality Relations A multiple-cardinality relation is represented as a JSON array. Each element of the array is a relation object with the same structure as a single-cardinality relation. Example: With qualifier properties:

Identity Values The identity property in a relation object contains the identity value(s) of the target object.

• If the target type's identity declaration specifies a single property, the identity value is a scalar matching that property's type.
• If the target type's identity declaration specifies multiple properties (composite identity), the identity value is a JSON array containing the values in the same order as declared in the identity keyword.

Example with single-property identity: Example with composite identity:

Reference Resolution A relationship is established through the identity property in a relation instance, which contains the identity value(s) of the target object. The resolution mechanism depends on whether the relation declaration includes a scope:

• With scope: The application uses the schema pointers in scope to identify the corresponding collections in the document instance. It searches these collections for an object whose identity matches the identity value. For map collections, the search is performed on the map's values.
• Without scope: The relation references an object that exists outside the document. The application must resolve the reference through external means, such as querying a database or service.

Complete Example This example demonstrates a library schema with books and authors: Example instance document:

Reserved Keywords This specification adds the following keywords to the JSON Structure reserved keyword list:

• identity
• relations
• targettype
• cardinality
• scope
• qualifiertype

Security Considerations Relations create references between objects that may span different parts of a document or different documents. Implementations MUST ensure that:

• Identity values are validated against the expected target type.
• Circular references are handled appropriately to prevent infinite loops during traversal.
• Identity matching across documents does not expose sensitive information through unintended correlations.

IANA Considerations This document has no 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. 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. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. This specification defines UUIDs (Universally Unique IDentifiers) -- also known as GUIDs (Globally Unique IDentifiers) -- and a Uniform Resource Name namespace for UUIDs. A UUID is 128 bits long and is intended to guarantee uniqueness across space and time. UUIDs were originally used in the Apollo Network Computing System (NCS), later in the Open Software Foundation's (OSF's) Distributed Computing Environment (DCE), and then in Microsoft Windows platforms. This specification is derived from the OSF DCE specification with the kind permission of the OSF (now known as "The Open Group"). Information from earlier versions of the OSF DCE specification have been incorporated into this document. This document obsoletes RFC 4122. n.d.

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

• Added missing BCP 14 references (RFC 2119, RFC 8174).
• Improved phrasing of identity keyword description.
• Fixed modal placement: "MUST only be used" → "MUST be used only".

Acknowledgments TODO acknowledge.