Annotation-internal objects — the repeated entries inside tensorReferenceFrames, vectorReferenceFrames, frameTransforms, colorSpaces, audioChannels, spectralBands, and the component entries inside them — admit neither a description nor a concepts member. Every one of them is "additionalProperties": false, so an author cannot add either. Nothing in the schema can say what an individual entry is for.
The draft is aware of the problem and delegates it to the referenced definition. From the Vertical and Compound Systems section:
The axis direction comes from the referenced definition and not from the annotation, so whether the axis is positive up or positive down is a fact about the identified system. Where kind is type, the description of the meta-type or of its elements states it.
That works when the entries reference different definitions. It fails when they reference the same one, because one shared description cannot say different things about different positions.
The acute case: frames
FrameReference carries reference, kind, and an optional variance, and nothing else. It binds no members. Its whole meaning is its position in the array. Consider a piezoelectric strain tensor over one set of crystal axes:
"tensorReferenceFrames": [
{
"frames": [
{ "reference": { "$ref": "#/definitions/CrystalAxes" }, "kind": "type" },
{ "reference": { "$ref": "#/definitions/CrystalAxes" }, "kind": "type" },
{ "reference": { "$ref": "#/definitions/CrystalAxes" }, "kind": "type" }
],
"components": "d"
}
]Three byte-identical entries. Index 0 is the axis of the applied field; indices 1 and 2 are the axes of the strain it produces. Neither the annotation nor a description on CrystalAxes can carry that distinction, and no consumer or documentation generator can recover it.
This is not an edge case. The draft names the repeated-frame case as typical:
One frame MAY be named by more than one entry, and is so named for a stress, a strain, or a seismic moment tensor.
So the annotation cannot label index positions for exactly the tensors it cites as the common ones. FrameReference is the worst affected because it is the only entry type that binds nothing — VectorReferenceFrame, AudioChannel, and SpectralBand at least name their members through components, channels, and bands, so a reader has something to go on.
concepts on entries
concepts is currently reachable only through ConceptsAddIn, which attaches to a type definition and to property, collection item, map value, and choice member schemas. An annotation entry is none of those.
An entry is often exactly the thing worth pointing at a published term. The applied-field index of a piezoelectric tensor, a spectral band set, an audio channel group, a color space entry — each denotes something a vocabulary already names, and the entry is where that identity belongs. Today it has nowhere to go. The same argument applies to the component entries of tensorComponents and to codedValues, so this is probably worth doing uniformly rather than only where it was first noticed.
Note that concepts and description are not substitutes for each other here. One is for a machine, the other for a person, and the entries want both.
Proposal
- Permit an optional
description on every annotation-internal object, most importantly on FrameReference.
- Permit an optional
concepts on the same objects, with the same shape and semantics ConceptsAddIn already defines.
Both are additive and neither changes the meaning of an existing schema. Factoring them into a small abstract base that the entry types extend would keep the meta-schema from repeating itself, and would make it obvious that the rule is uniform.
The alternative for point 1 — leaving the descriptive burden on the referenced definition — should be stated explicitly in the draft if it is kept, together with an acknowledgement that it does not reach the repeated-frame case.
Annotation-internal objects — the repeated entries inside
tensorReferenceFrames,vectorReferenceFrames,frameTransforms,colorSpaces,audioChannels,spectralBands, and the component entries inside them — admit neither adescriptionnor aconceptsmember. Every one of them is"additionalProperties": false, so an author cannot add either. Nothing in the schema can say what an individual entry is for.The draft is aware of the problem and delegates it to the referenced definition. From the Vertical and Compound Systems section:
That works when the entries reference different definitions. It fails when they reference the same one, because one shared description cannot say different things about different positions.
The acute case:
framesFrameReferencecarriesreference,kind, and an optionalvariance, and nothing else. It binds no members. Its whole meaning is its position in the array. Consider a piezoelectric strain tensor over one set of crystal axes:Three byte-identical entries. Index 0 is the axis of the applied field; indices 1 and 2 are the axes of the strain it produces. Neither the annotation nor a description on
CrystalAxescan carry that distinction, and no consumer or documentation generator can recover it.This is not an edge case. The draft names the repeated-frame case as typical:
So the annotation cannot label index positions for exactly the tensors it cites as the common ones.
FrameReferenceis the worst affected because it is the only entry type that binds nothing —VectorReferenceFrame,AudioChannel, andSpectralBandat least name their members throughcomponents,channels, andbands, so a reader has something to go on.conceptson entriesconceptsis currently reachable only throughConceptsAddIn, which attaches to a type definition and to property, collection item, map value, and choice member schemas. An annotation entry is none of those.An entry is often exactly the thing worth pointing at a published term. The applied-field index of a piezoelectric tensor, a spectral band set, an audio channel group, a color space entry — each denotes something a vocabulary already names, and the entry is where that identity belongs. Today it has nowhere to go. The same argument applies to the component entries of
tensorComponentsand tocodedValues, so this is probably worth doing uniformly rather than only where it was first noticed.Note that
conceptsanddescriptionare not substitutes for each other here. One is for a machine, the other for a person, and the entries want both.Proposal
descriptionon every annotation-internal object, most importantly onFrameReference.conceptson the same objects, with the same shape and semanticsConceptsAddInalready defines.Both are additive and neither changes the meaning of an existing schema. Factoring them into a small abstract base that the entry types extend would keep the meta-schema from repeating itself, and would make it obvious that the rule is uniform.
The alternative for point 1 — leaving the descriptive burden on the referenced definition — should be stated explicitly in the draft if it is kept, together with an acknowledgement that it does not reach the repeated-frame case.