0019: x-permdock-* extensions, registered fallbacks only, Overlay output

Status

Accepted, September 2026. Amends 0014: the 3.2 target and the integration hooks stand; the fallback naming and the --openapi-version flag described there are replaced by this decision.

Point 4 (target version policy) is superseded by 0025: --target 3.3 now emits the pinned OpenAPI 3.3 Security Profile draft with x-permdock-securityProfile as its twin. Points 1, 2, 3 and 5 stand.

Context

0014 chose OpenAPI 3.2 as the target and said 3.1 documents would receive "the x-oai-* names the OpenAPI Initiative documents". Checking the OpenAPI Initiative's Extension Registry shows that only three such names exist for the 3.2 security features: x-oai-deprecated, x-oai-deviceAuthorization and x-oai-deviceAuthorizationUrl. There is no x-oai-oauth2MetadataUrl; 0014 had assumed one. The Namespace Registry reserves oai for the OpenAPI Initiative and lists fdx, jsonschema, ms, oas, oas-draft, sap and scalar; permdock is not registered. Meanwhile the registry already carries x-agent-trust for agent-authenticated apiKey schemes, which overlaps with what the Web Bot Auth adapter will need to say.

Separately, permdock openapi emit was specified as a command that rewrites the OpenAPI document in place. In most projects the document is generated by a framework or owned by another team; rewriting it mixes PermDock's output into someone else's artefact and makes review and drift detection harder. The Overlay Specification 1.1.0 exists for exactly this: a separate, ordered list of update / remove / copy actions applied to a description at build time.

Finally, OpenAPI 3.3 is in development on v3.3-dev with a security focus (Security Profiles, FAPI 2.0 and GNAP under investigation) per the June 2026 newsletter. PermDock needs a policy for how its target version flag relates to unreleased versions.

Decision

1. Namespace. Every PermDock-specific field is an extension under x-permdock-: x-permdock-permissions, x-permdock-conditions, x-permdock-securityProfile, x-permdock-approval, x-permdock-oauth2MetadataUrl, x-permdock-catalog. Registering permdock in the OAI Namespace Registry (a PR to OAI/spec.openapis.org) is a Phase 2 deliverable alongside the emitter. The extension table lives on OpenAPI registries.
2. Registered fallbacks only. For --target 3.1, 3.2-only fields are downgraded to a registered extension when one exists (x-oai-deprecated, x-oai-deviceAuthorization, x-oai-deviceAuthorizationUrl) and to x-permdock-* otherwise. PermDock never coins an x-oai-* name. oauth2MetadataUrl therefore becomes x-permdock-oauth2MetadataUrl on 3.1 output; URI-referenced schemes are inlined. Registered extensions outside the oai namespace are reused too: the Web Bot Auth apiKey scheme carries x-agent-trust.
3. Overlay preferred, document optional. permdock openapi emit --format overlay emits an Overlay 1.1.0 document that targets operations by operationId and adds security, securitySchemes and x-permdock-* fields. --format document (the default, for continuity) writes the mutated description. The Overlay never contains remove on security or securitySchemes. --check works on both and is the CI contract. The adapter exposes the same output as overlay().
4. Target version policy. --target 3.1|3.2|3.3 replaces --openapi-version; the default is 3.2. 3.3 is accepted and marked experimental: it emits the 3.2 shape plus x-permdock-securityProfile and no field that exists only in v3.3-dev. When 3.3.0 is released with a native security-profile construct, --target 3.3 emits it and 3.1 / 3.2 targets keep the extension; the default moves to 3.3 no earlier than one minor release later. Drafts are not implemented as if final.
5. Security profile declaration. x-permdock-securityProfile (value fapi2) on security schemes and operations, written by --profile fapi2 or the adapter's securityProfile option, is the stable way to declare the FAPI 2.0 resource-server rules until OpenAPI has a native form.

Consequences

• Output is predictable: three x-oai-* names, the x-permdock-* set and x-agent-trust, nothing else. The emitter's fixtures fail on any other x-oai-* name.
• 3.1 consumers see x-permdock-oauth2MetadataUrl rather than a name that looks official but is not; PermDock's importer reads it, other tools ignore it.
• API teams keep ownership of their description; PermDock's contribution is a reviewable, diffable file. Projects need an Overlay applier in their build to use the preferred form, which is why the document form stays available and default.
• --check catches drift in either direction, including a hand-edited Overlay that adds a remove.
• Two flags (--target, --format) multiply the output matrix to six shapes; all six are covered by fixtures in @permdock/testing.
• The Phase 2 checklist gains a non-code item (the namespace registration PR); until it merges the prefix is valid but unreserved.
• 0014 remains the record for choosing 3.2; readers of its "fallbacks" bullets should follow this ADR.

Alternatives considered

• Mutate documents only. Rejected as the sole mode: it hides PermDock's changes inside a regenerated file, fights with generators that rewrite the document on every build, and makes "what did PermDock add" a diff of the whole description. Kept as an option because it needs no extra tooling.
• Use x-oai-* names freely. Rejected: oai is reserved for the OpenAPI Initiative, unregistered names impersonate the specification, and tools implementing the registered set would ignore or misread them. This is what 0014 implicitly allowed for oauth2MetadataUrl.
• Use only x-permdock-*, ignoring registered names. Rejected: where a registered extension exists, other tools already understand it; a private twin loses that for no gain.
• Wait for 3.3. Rejected: 3.3 is 42% through its milestone with no release date, and PermDock needs to emit security metadata in Phase 2. Tracking 3.3 on its own page and reserving the 3.3 target value costs nothing and avoids a flag change later.
• Ship an Overlay applier in @permdock/cli now. Deferred: any Overlay 1.x applier works, and the document form covers projects without one. Revisit if --check needs to validate applied output.

Related

• OpenAPI 3.2
• OpenAPI Overlay
• OpenAPI registries
• OpenAPI 3.3
• OpenAPI adapter and openapi command
• 0014: Target OpenAPI 3.2