Companion Spec: Relations and Identity

[clemensv]

Summary

Based on the discussion in PR #8, propose a companion specification for modeling relationships/associations between objects in JSON Structure.

Proposal

For objects and tuples, add a new keyword relations that is similar to properties but specifically defines relationship properties. relations and properties share a namespace, so they can't define conflicting names.

The relations declarations are not modeled as types, because they must be able to cross-reference properties within the same tuple/object. They are similar to properties in that they are represented just like properties in the instances.

A relation is a named object (via the relations map) that has two 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)

The targettype's identity declaration functions like the tuple keyword for establishing the type of references, meaning that if the target's identity clause references two properties, the reference value in the relation source is a tuple-encoded list of values matching that identity.

Relation Instance Structure

An instance of a single relation is an object with the following properties:

• ref - a JSON pointer to the target object
• identity - a tuple that reflects the target object identity values

A relationship MAY be established either through a direct link (ref) or through an identity match against all known instances of the target type.

Qualifier Support

Relations can also support qualifiers (like link properties in a graph):

• qualifiertype - defines/references a type to qualify the relationship further

Example Schema

{
  "definitions": {
    "Library": {
      "Author": {
        "type": "object",
        "properties": {
          "id":   { "type": "uuid" },
          "name": { "type": "string" }
        },
        "required": ["id", "name"],
        "identity": ["id"]
      },
      "Book": {
        "type": "object",
        "properties": {
          "isbn":  { "type": "string" },
          "title": { "type": "string" }
        },
        "required": ["isbn", "title"],
        "identity": ["isbn"],
        "relations": {
          "authors": {
            "cardinality": "multiple",
            "targettype":  { "$ref": "#/definitions/Library/Author" }
          }
        }
      }
    }
  }
}

References

• PR Propose targettype keyword for associations #8: Propose targettype keyword for associations #8
• Issue Feature: Support Associations #4: Feature: Support Associations #4
• Discussion: Propose targettype keyword for associations #8 (comment)

cc @Fannon