Feature: Support Associations

[Fannon]

In my experience, one of the biggest gaps of JSON Schema is that it's not possible to describe associations. Both IDs and associations are just "string" or maybe "UUID" format if you're lucky. This is probably due to JSON Schema only focusing on validation, not on describing models.

JSON Structure is already much better suited to describe models, but it would be important to also explicitly model the associations, e.g. to express FK relationships in database schemas or references / associations in API models.

There are many ways to go about it, we could collect them here.

PRs

• Add id keyword to objects to state primary IDs #7
• Propose targettype keyword for associations #8

Initial Proposal

A first initial, simpler proposal (partially discussed with Clemens) could look like this.

• Add new structural keyword id to object and , which is an array of property names that are the "primary ID" that are used to reference to it. This is usually one value, but if its multiple, we have a "composite ID".
• Add a new structural keyword targettype to properties, the value is a JSON Pointer to the association target object. The target MSUT be an object and MUST have use the id keyword.
• Cardinality is known through required and whether the association is within an array or not.
• We do not need a dedicated association type, because it's useful to know the type of the ID itself (could be string, UUID, number, ...). We know something is an ID, because we marked it with id and we know something is an association by having the targettype keyword in it.
• Polymorphic associations could probably be covered by wrapping this into a choice. (@clemensv ?)

Gaps / Open Questions

• For composite IDs and References, we still don't know which source object property maps to which target object property. If this is needed to understand (e.g. to automatically construct query join conditions or code that joins the associations), we need to define this mapping.
  • Maybe we could add a targetproperty in this case, where the property name for the corresponding ID is stated. EDIT: This alone is not sufficient if one object has more than one association to the same target. In this case, it's necessary to know which properties on the source object together form one composite association to the target objects composite ID (and how the properties each map).
• Not sure if we could also use abstract objects for polymorphic associations. In this case, you could point to the abstract object, it defines the shared id. All concrete implementations of the abstract object are then valid association targets.

[clemensv]

I think of your proposal as three (!) features that compose:

1. The targettype annotation for jsonpointer typed schemas simply creates a constraint for what JSON node the JSON Pointer may point at, nothing more.

2. The optional, array-of-string valued id annotation for object (and tuple) establishes a set of identifiers that MUST, in combination, be unique for each instance. That is also a feature that puts a constraint on instances (the check will have to span instances of all usages of the type independent of where they appear in a document).

3. If a jsonpointer points from some type property to another targettype, and that targettype has a declared id, a mapping into a database can use that information to construct a foreign key relationship. If there are mutual relationships, of that sort, that may cause an extra table to be created. That's basically a side-product of 1) and 2).

Polymorphic associations would point to a choice, yes. For an inline discriminator choice, the base class would have to define the id already.

[Fannon]

Yes, it makes sense to compose it to separate feature requests / PRs. Maybe an additional one to support composite IDs via targetproperty (or something else) - but that is not needed for a first iteration.

Those 2 first features could be separate PRs (should I create them?) and work together to get the associations as a feature into JSON Structure.

Feature 3 is then more of a implication?

[clemensv]

Yes, 3 is a result of 1 and 2. If you want to create PRs, go right ahead!