Summary
All three examples in the binary content annotation keyword sections use key names that do not match the keywords those sections define. The prose is correct throughout; only the examples are wrong.
A reader who copies an example gets a schema with unrecognized properties and no content annotations.
Occurrences
draft-vasters-json-structure-core.md, five occurrences across three examples:
| Line |
Example is in |
Uses |
Should be |
| 1471 |
The contentEncoding Keyword |
"encoding" |
"contentEncoding" |
| 1496 |
The contentCompression Keyword |
"encoding" |
"contentEncoding" |
| 1497 |
The contentCompression Keyword |
"compression" |
"contentCompression" |
| 1514 |
The contentMediaType Keyword |
"encoding" |
"contentEncoding" |
| 1515 |
The contentMediaType Keyword |
"mediaType" |
"contentMediaType" |
Why the content* names are the correct ones
Every normative mention in the spec uses them:
- Line 296,
binary type: "The type annotation keywords contentEncoding, contentCompression, and contentMediaType can be used to specify the encoding, compression, and media type of the binary data."
- Line 302: "specified in the
contentEncoding keyword."
- The three section headings and their anchors:
{#contentencoding-keyword}, {#contentcompression-keyword}, {#contentmediatype-keyword}.
- Every sentence inside those three sections.
The SDK agrees. sdk/python/src/json_structure/schema_validator.py lists contentEncoding and contentMediaType in STRING_VALIDATION_KEYWORDS and validates both under those names.
Suggested fix
{
"type": "binary",
"contentEncoding": "base64"
}
{
"type": "binary",
"contentEncoding": "base64",
"contentCompression": "gzip"
}
{
"type": "binary",
"contentEncoding": "base64",
"contentMediaType": "image/png"
}
Separate observation, not part of this issue
contentCompression does not appear in the Python SDK validator, while contentEncoding and contentMediaType do. That may be deliberate, since compression affects the decoded value rather than its lexical form, but it seemed worth flagging to whoever picks this up.
Context
Found while writing the OpenAPI binding draft, which has to state how a JSON Structure binary value is represented in a JSON body. Same class as the $uses key-name corrections currently open in validation (#7), units (#7), import (#4), and conditional-composition (#4).
Summary
All three examples in the binary content annotation keyword sections use key names that do not match the keywords those sections define. The prose is correct throughout; only the examples are wrong.
A reader who copies an example gets a schema with unrecognized properties and no content annotations.
Occurrences
draft-vasters-json-structure-core.md, five occurrences across three examples:contentEncodingKeyword"encoding""contentEncoding"contentCompressionKeyword"encoding""contentEncoding"contentCompressionKeyword"compression""contentCompression"contentMediaTypeKeyword"encoding""contentEncoding"contentMediaTypeKeyword"mediaType""contentMediaType"Why the
content*names are the correct onesEvery normative mention in the spec uses them:
binarytype: "The type annotation keywordscontentEncoding,contentCompression, andcontentMediaTypecan be used to specify the encoding, compression, and media type of the binary data."contentEncodingkeyword."{#contentencoding-keyword},{#contentcompression-keyword},{#contentmediatype-keyword}.The SDK agrees.
sdk/python/src/json_structure/schema_validator.pylistscontentEncodingandcontentMediaTypeinSTRING_VALIDATION_KEYWORDSand validates both under those names.Suggested fix
{ "type": "binary", "contentEncoding": "base64" }{ "type": "binary", "contentEncoding": "base64", "contentCompression": "gzip" }{ "type": "binary", "contentEncoding": "base64", "contentMediaType": "image/png" }Separate observation, not part of this issue
contentCompressiondoes not appear in the Python SDK validator, whilecontentEncodingandcontentMediaTypedo. That may be deliberate, since compression affects the decoded value rather than its lexical form, but it seemed worth flagging to whoever picks this up.Context
Found while writing the OpenAPI binding draft, which has to state how a JSON Structure
binaryvalue is represented in a JSON body. Same class as the$useskey-name corrections currently open invalidation(#7),units(#7),import(#4), andconditional-composition(#4).