Add an options keyword: open, non-constraining enumeration for documented values

[clemensv]

Summary

Introduce an options keyword: an open, non-constraining enumeration that
documents a set of recognized values for a scalar property without restricting
the instance to them (unlike enum, which constrains).

Motivation

Several places in JSON Structure and its extensions need to publish a set of
recognized values while explicitly keeping the set open — i.e. a value
outside the list is still valid and MUST be preserved. Today this is expressed
only in prose ("the enumeration is open; the values defined here are …"), which
a generator, form builder, or documentation tool cannot pick up.

Concrete example: the JSON Structure: Characteristics extension defines many
kind classifiers and value enumerations (observedProperty.kind,
codedValues.kind, weighting, timeWeighting, calibration, observer, …)
that are open — the listed values are documentation anchors, not
constraints. There is currently no machine-readable way to carry both the value
and its description while signalling "this list does not constrain."

Proposal

Add an options keyword usable on scalar-typed schemas:

"options": [
  { "key": "a", "description": "text" },
  { "key": "b", "description": "text" }
]

Semantics

• options is a documentation / discoverability annotation. On its own it
  does not constrain the instance value: a value not present as any key
  is still valid.
• Each entry is an object with:
  • key — REQUIRED. The recognized value. Its type MUST be the type of the
    annotated property. Therefore key MUST be a scalar (string, number,
    boolean); an option key cannot be an object (and, by extension, not an
    array).
  • description — OPTIONAL (RECOMMENDED). Human-readable text for the value.
  • (open to additional documented metadata later, e.g. deprecated,
    display labels.)
• key values within one options array MUST be distinct.

Interaction with enum

• With enum: enum constrains; options is then a documentation
  anchor that annotates (a subset or all of) the permitted values with
  descriptions. Every key SHOULD also appear in enum (an options entry for
  a value that enum forbids is contradictory).
• Without enum: the value set is open — options documents recognized
  values without forbidding others. This is the case the Characteristics
  extension needs for its open kind/value enumerations.

Example

Open (non-constraining) — documents recognized kinds but permits others:

{
  "type": "string",
  "options": [
    { "key": "itu",  "description": "An ITU-R/ITU-T Recommendation." },
    { "key": "type", "description": "An in-schema meta-type." }
  ]
}

Constraining enum + documentation options:

{
  "type": "string",
  "enum": ["fast", "slow"],
  "options": [
    { "key": "fast", "description": "Fast time weighting." },
    { "key": "slow", "description": "Slow time weighting." }
  ]
}

Notes / open questions

• Placement: validation extension vs. core? It is non-constraining, so it is
  closer to description/annotation than to enum; but pairing with enum
  argues for co-location with the validation vocabulary.
• Should options on a numeric property allow key to carry a unit-aware
  value, or is it purely the raw scalar? (Proposed: raw scalar of the property
  type.)
• Tooling: code generators can emit named constants; form builders can render a
  combo box that still accepts free input when there is no enum.