Section The $uses Keyword says:
The value of $uses MUST be a set of strings that are either:
- add-in names advertised in the
$offers keyword of the schema document referenced by the $schema keyword of the instance document or
- JSON Pointers to add-in schema definitions in the same meta-schema document.
It does not say what happens when the meta-schema referenced by $schema reaches other add-ins indirectly, and there are two indirections in common use.
The case
An extension meta-schema that imports Extended and offers one feature of its own:
{
"$schema": "https://json-structure.org/meta/extended/v0/#",
"$id": "https://json-structure.org/meta/characteristics/v0/#",
"$import": "https://json-structure.org/meta/extended/v0/#",
"$uses": ["JSONStructureUnits", "JSONStructureImport",
"JSONStructureConditionalComposition", "JSONStructureValidation"],
"$offers": {
"JSONStructureCharacteristics": ["#/definitions/features/ConceptsAddIn", "..."]
}
}A document that references it:
{
"$schema": "https://json-structure.org/meta/characteristics/v0/#",
"$uses": ["JSONStructureCharacteristics", "JSONStructureAlternateNames"]
}JSONStructureAlternateNames is advertised in the $offers of the Extended meta-schema. It is not in the $offers of the characteristics meta-schema, and it is not in that meta-schema's own $uses either. On the letter of the rule quoted above, the document is invalid. In practice this is exactly what an extension meta-schema author wants to allow, and every SDK accepts it.
What implementations do
json-structure-check --extended accepts the document above, and rejects "$uses": ["JSONStructureCharacteristics", "TotallyBogusFeatureName"] with SCHEMA_USES_UNKNOWN_EXTENSION. So the resolution is against a registry of extensions the implementation knows about, not against the $offers of the document named by $schema. Whatever the intended rule is, this is not it, and the spec gives an implementer nothing to test against.
Questions
- Are the
$offers entries of a document reached through $import visible to $uses in a document that references the importing document?
- Does an add-in have to appear in the importing meta-schema's own
$uses before a downstream document may name it in its $uses, or is $offers visibility enough?
- Is
$uses resolved against the $offers chain at all, or against a registry of known extension names? If the latter, what registers a name?
Proposal
State the resolution rule explicitly, along these lines:
The set of add-in names available to $uses in a document is the union of the $offers of the schema document referenced by $schema and the $offers of every schema document that document reaches transitively through $import. An add-in name that is not in that set MUST be rejected.
and add the negative case — a name that is in no reachable $offers — to the test assets so that implementations converge. If the intent is instead that an importing meta-schema must re-declare what it wants to pass on, say that, because the current SDK behaviour would then be wrong in the other direction.
Either way an author needs to be able to tell, from the spec alone, whether the second example above is a conforming document. Today they cannot.
Section The
$usesKeyword says:It does not say what happens when the meta-schema referenced by
$schemareaches other add-ins indirectly, and there are two indirections in common use.The case
An extension meta-schema that imports Extended and offers one feature of its own:
{ "$schema": "https://json-structure.org/meta/extended/v0/#", "$id": "https://json-structure.org/meta/characteristics/v0/#", "$import": "https://json-structure.org/meta/extended/v0/#", "$uses": ["JSONStructureUnits", "JSONStructureImport", "JSONStructureConditionalComposition", "JSONStructureValidation"], "$offers": { "JSONStructureCharacteristics": ["#/definitions/features/ConceptsAddIn", "..."] } }A document that references it:
{ "$schema": "https://json-structure.org/meta/characteristics/v0/#", "$uses": ["JSONStructureCharacteristics", "JSONStructureAlternateNames"] }JSONStructureAlternateNamesis advertised in the$offersof the Extended meta-schema. It is not in the$offersof the characteristics meta-schema, and it is not in that meta-schema's own$useseither. On the letter of the rule quoted above, the document is invalid. In practice this is exactly what an extension meta-schema author wants to allow, and every SDK accepts it.What implementations do
json-structure-check --extendedaccepts the document above, and rejects"$uses": ["JSONStructureCharacteristics", "TotallyBogusFeatureName"]withSCHEMA_USES_UNKNOWN_EXTENSION. So the resolution is against a registry of extensions the implementation knows about, not against the$offersof the document named by$schema. Whatever the intended rule is, this is not it, and the spec gives an implementer nothing to test against.Questions
$offersentries of a document reached through$importvisible to$usesin a document that references the importing document?$usesbefore a downstream document may name it in its$uses, or is$offersvisibility enough?$usesresolved against the$offerschain at all, or against a registry of known extension names? If the latter, what registers a name?Proposal
State the resolution rule explicitly, along these lines:
and add the negative case — a name that is in no reachable
$offers— to the test assets so that implementations converge. If the intent is instead that an importing meta-schema must re-declare what it wants to pass on, say that, because the current SDK behaviour would then be wrong in the other direction.Either way an author needs to be able to tell, from the spec alone, whether the second example above is a conforming document. Today they cannot.