Clarication needed for RESERVED

[wking]

We currently have a single RESERVED property (descriptor data) and are probably about to add more (#672), but the spec doesn't explain what the RESERVED keyword means. The current context includes:

The following field keys are reserved and MUST NOT be used by other specifications.

and:

This key is RESERVED for future versions of the specification.

neither of which impact neither JSON authors nor JSON consumers.

So what happens to the JSON handlers? Are JSON authors free to set those properties? Are JSON consumers free to act on those properties as long as they don't specify how they interpret them?

Will making platform.features reserved make the current Docker docs (which are fairly spec-like) non-compliant for breaking the MUST NOT be used by other specifications? Or are they ok because they define a different media type? What happens for backwards-compat?

I think we need to define RESERVED here, and expect there's prior art we can lean on. Does anyone have a good reference off hand? I'll dig around as well and report back if I find anything.

[vbatts]

😕 hmm

[wking]

C99 (which we use for “unspecified”, “undefined”, and “implementation-defined” [1]) has wording for “Reserved identifiers” [2]. This has explicit wording forbidding user-supplied external names (equivalent to properties set in supplied JSON for us) from matching reserved identifiers (equivalent to our spec-defined properties). I think we want something like that definition in our spec. [1]: https://github.com/opencontainers/image-spec/blob/v1.0.0-rc5/spec.md#notational-conventions [2]: http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=119