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
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.
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
Initial Proposal
A first initial, simpler proposal (partially discussed with Clemens) could look like this.
idto 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".targettypeto properties, the value is a JSON Pointer to the association target object. The target MSUT be an object and MUST have use theidkeyword.requiredand whether the association is within anarrayor not.associationtype, 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 withidand we know something is an association by having thetargettypekeyword in it.choice. (@clemensv ?)Gaps / Open Questions
targetpropertyin 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).abstractobjects for polymorphic associations. In this case, you could point to the abstract object, it defines the sharedid. All concrete implementations of the abstract object are then valid association targets.