feat: Clarify "reference" properties spec

[B13rg]

#751

Clarifies usages of "reference" in the spec to specify what field references.

[github-actions[bot]]

MLCommons CLA bot All contributors have signed the MLCommons CLA ✍️ ✅

[B13rg]

Here is a diagram descibing the object relations as I understand them:

[B13rg]

Some uncertainties:

• Reference Property Descriptions: The Field reference "@id" values are clunky, how can it be phrased better? It needs to cleanly communicate it's a reference, not embedded object.
• "parentField" and "subField" properties: clarify what should happen with circular references, or if a referenced field is missing. Should this be considered an error, or are there fallback behaviors?

[benjelloun]

Here is a diagram descibing the object relations as I understand them:

Nice picture!

[benjelloun]

Some uncertainties:

• Reference Property Descriptions: The Field reference "@id" values are clunky, how can it be phrased better? It needs to cleanly communicate it's a reference, not embedded object.

That comes from JSON-LD:

@id Used to uniquely identify node objects that are being described in the document with IRIs or blank node identifiers. This keyword is described in § 3.3 Node Identifiers. A node reference is a node object containing only the @id property, which may represent a reference to a node object found elsewhere in the document.

• "parentField" and "subField" properties: clarify what should happen with circular references, or if a referenced field is missing. Should this be considered an error, or are there fallback behaviors?

Circular references and missing referenced field should both be errors.