JSON Schema, OpenAPI and Problem Details

spec 1.0-draft-1

Field	Value
Status	Adopt
Version pinned	JSON Schema 2020-12 (16 June 2022); OpenAPI 3.1.0 (15 February 2021); RFC 9457 (July 2023)
Source	https://json-schema.org/draft/2020-12/json-schema-core
What is taken	Wire shapes, API description and the error format
Why	The generated artefacts and their drift checks depend on them
What is extended or replaced	Adds the closed registry of urn:autonym:error:* types
Specification home	A8, B4, generated contracts

Version pinned

JSON Schema draft 2020-12: Core (draft-bhutton-json-schema-01) and Validation (draft-bhutton-json-schema-validation-01), published by json-schema.org on 16 June 2022 in Internet-Draft format, with the meta-schema https://json-schema.org/draft/2020-12/schema. It is a final json-schema.org release; it was never adopted by the IETF.
OpenAPI 3.1.0: OpenAPI Specification v3.1.0, 15 February 2021, which the generated openapi/autonym-v1.yaml declares.
Problem Details: RFC 9457, July 2023, Proposed Standard.

What is taken

Every schema in spec/schemas/ and every embedded schema in the OpenAPI document and MCP tool definitions is JSON Schema 2020-12, generated from packages/schema with Zod.
The recipient REST contract is an OpenAPI 3.1.0 document in JSON syntax, which is valid YAML (B4.1).
Errors are RFC 9457 application/problem+json objects (problem.json), with OAuth errors keeping their OAuth representation (B4.3).

Why

Generated artefacts and the drift check (pnpm check:generated) make the schemas the single source of truth; widely supported formats let implementers generate clients and validators instead of reading prose.

What is extended

A closed error registry, errors.json, of urn:autonym:error:<code> types, each naming the sections that raise it. No unregistered code may be returned. The registry also lists the OAuth codes the text cites and the codes the B1 grant binding takes from its base specification, which keep their own representation (B4.3).
Problem objects carry no rejected value, record content, credential or existence hint (B4.3).

What is replaced or not used

Nothing is replaced. OpenAPI 3.2 is not used.

Deviations

OpenAPI 3.1.2 (19 September 2025) is the latest 3.1 patch release. Patch releases clarify the text but do not change the 3.1 feature set; the generated document stays at 3.1.0 until a change entry moves it.

Conformance checks

TRANSPORT-01 in the conformance manifest, with runtime evidence pending; structural conformance is proven today by pnpm check:generated.

References to other standards and projects describe intended technical alignment only and do not imply endorsement or partnership.