Version Compatibility

Feature	1.0	2.0	2.1
JSON, YAML, TOML decoding	Yes	Yes	Yes
configs and handlers	No	Yes	Yes
number parameter	No	Yes	Yes
Custom parameter fields	No	Yes	Yes
Metadata and $schema	No	No	Yes
UI language dictionaries	No	No	Yes
URL path/query interpolation	No	No	Yes
Enum options and scalar default	No	No	Yes
show_if	No	No	Yes
Request body type/template	No	No	Yes
Polling	No	No	Yes
Generalized response.media	No	No	Yes
Legacy response.image	Yes	Yes	Yes

Missing Version

A document without APICORE_version retains 2.0 semantics unless the parser finds a 2.1-only field or localized UI value. Recognized 2.1 features include metadata, language mappings, enum options, show_if, request body configuration, polling, and response.media.

Use an exact version= argument when automatic detection is not appropriate:

legacy = load("legacy.api.json", version="2.0")

Family And Exact Selectors

• v1 selects the APICORE 1 family and defaults undeclared input to 1.0.
• v2 selects the APICORE 2 family. Undeclared input uses the same feature-based 2.0/2.1 detection as the default parser behavior.
• 1.0, 2.0, and 2.1 select exact versions.
• v2.1 is accepted as an alias for exact 2.1.

An exact override conflicting with a declared version raises ValidationError.

Version Isolation

The parser rejects v2.1-only metadata, i18n values, enum options, conditional parameters, body configuration, polling, and media structures in explicitly declared v1/v2.0 documents. This prevents legacy consumers from receiving model shapes they do not understand.