Skip to content

Binary content keyword examples use short key names (encoding, compression, mediaType) instead of the normative content* names #32

Description

@clemensv

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).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions