Skip to content

4.0: every value list is a closed enum or an open vocabulary, with one extension-term schema, checked by the build #9002

Open

Description

@KonstantinMirin

Revised 2026-11-14: every enum takes the open form, except discriminators; x-closed is dropped.

Problem

A value list whose receivers must accept unknown values isn't an enum, yet the schemas declare every such list with enum, which a strict validator enforces. So a conforming strict receiver rejects what the versioning page tells it to accept:

Clients must tolerate unknown values and fall back to sensible defaults. (versioning.mdx L228)

With #8915, a 3.3 adagents.json using the new match_keys value full_name fails 3.2.10 validation as a whole file. advertiser-industry.json says "Sellers MUST accept unknown values", and its own enum rejects them.

In static/schemas/source at main bf4aa6dbb3:

enum sites Count
All string enums, outside tests such as not and if 1,006
Discriminators, which stay closed 18
Everything else, lifecycles included, which takes the open form 988
Extension branches beside an enum 4, in three grammars: custom:{key}, x_{key}, an HTTPS URI
Values containing : 3, in chroma_subsampling

This gist has every site, the citations and the scripts.

Proposal for 4.0

  1. One form for every list. Every enum takes the open form:
    {"oneOf": [{"enum": ["automotive", "finance"]},
               {"$ref": "/schemas/core/extension-term.json"}]}
    A minor adds core values, and anyone may send an extension term. Only discriminators differ: a one-value enum becomes const, and a branch-selecting key stays plain.
  2. One extension-term schema. A term is {domain}:{key}, on a domain its definer controls, as in BrandRef, so no registry is needed. Core values never contain :, so oneOf is exact; chroma_subsampling is respelled.
  3. No exemption. The tolerate-unknown text goes: a sender uses a core value only with peers served a release that defines it, as with fields.
  4. Unknown terms. Each open position's x-adcp-unknown-term is ignore or the core value an unknown term counts as.
  5. One lint. Every enum is a discriminator or an open-form core, and every extension branch references the shared schema. Its 4.0.0 baseline is empty.

Why 4.0

Moving custom:, x_ and the URI branches to the shared grammar changes wire values, and dropping the exemption changes what sellers may send. It fits T2 beside #8900 and #8901. For #8885, error.code takes the open form.

I'm happy to take this on.

Analyzed and generated with the help of Claude, fully reviewed by me.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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