OpenAPI registries

Status: planned Phase: 2

What it is

The OpenAPI Initiative maintains a set of registries that give shared names to things the specification itself leaves open:

Registering is a pull request against OAI/spec.openapis.org that adds a Markdown file under registries/_{registryName}. The Namespace Registry requires the prefix format x-{namespace}- with lowercase identifiers; registered namespaces are fdx, jsonschema, ms, oai (reserved for the OpenAPI Initiative), oas-draft, oas, sap and scalar.

The Extension Registry entries that matter to PermDock:

• x-oai-deprecated: marks a Security Scheme deprecated in documents older than 3.2.
• x-oai-deviceAuthorization: the OAuth 2.0 device authorization flow inside flows, pre-3.2.
• x-oai-deviceAuthorizationUrl: the RFC 8628 device authorization endpoint, pre-3.2.
• x-agent-trust: a trust-level metadata block for agent-authenticated apiKey security schemes, carrying the signature algorithm, a trust level vocabulary and a JWKS endpoint for local verification.

There is no registered x-oai-oauth2MetadataUrl, and permdock is not a registered namespace today.

Why it matters for PermDock

PermDock puts permission keys, portable conditions, approval metadata and security-profile declarations into OpenAPI documents so gateways, SDK generators, portals and agents can read them. Every one of those fields is an extension. Two things go wrong when extensions are named casually:

• Collisions. An x-permissions field means something different to every tool that emits one. A registered namespace makes x-permdock-permissions mean exactly one thing.
• Impersonation. Writing an unregistered x-oai-* name looks official and is not; a viewer that implements the registered x-oai-* set will ignore it or, worse, misread it. oai is reserved for the OpenAPI Initiative.

Conversely, when a registered extension already says what PermDock needs to say, reusing it means other tools understand the output without knowing PermDock exists. That is why the 3.1 fallbacks for device authorization and deprecation use the x-oai-* names, and why the Web Bot Auth security scheme carries x-agent-trust rather than an x-permdock-* twin.

How PermDock uses it

The permdock namespace

Registering permdock in the Namespace Registry is a Phase 2 action item, done in the same phase as the permdock/openapi entry and permdock openapi:

1. Open a pull request against OAI/spec.openapis.org adding a Markdown file for the permdock namespace under the namespace registry directory.
2. Prefix: x-permdock-; identifiers are lowercase, camelCase after the prefix as in x-permdock-securityProfile (the registry constrains the namespace token, not the suffix).
3. Point the entry at this page as the description of every field in the namespace.

Until the registration lands, the extensions are still valid OpenAPI (any x- field is), but the prefix is not reserved. Nothing in PermDock's output changes when it is.

PermDock extensions

Every value is plain JSON that survives the same round trips as a permission leaf; nothing in an extension is a reference to a runtime object.

{
  "paths": {
    "/posts/{id}": {
      "delete": {
        "operationId": "deletePost",
        "security": [{ "permdockOAuth": ["post:delete"] }],
        "x-permdock-permissions": ["post.delete"],
        "x-permdock-conditions": {
          "post.delete": { "op": "eq", "field": "authorId", "value": { "ref": "subject.id" } }
        },
        "x-permdock-approval": { "post.delete": { "reason": "human" } },
        "x-permdock-securityProfile": "fapi2",
        "responses": { "204": { "description": "Deleted" }, "403": { "$ref": "#/components/responses/PermDockDenied" } }
      }
    }
  }
}

Registered names PermDock reuses

For Web Bot Auth, PermDock documents signed agent traffic as an apiKey scheme with in: header and name: Signature-Agent, the header through which the verifier discovers the signer's keys. The x-agent-trust block on that scheme carries the signature algorithm, the trust level (using the vocabulary the registry entry defines) and the JWKS endpoint the adapter verifies against. PermDock does not define its own trust vocabulary; the field names and allowed values are taken from the registry entry when the Phase 4 HTTP adapters implement verification.

Rules

1. Never invent an x-oai-* name. The oai namespace belongs to the OpenAPI Initiative; if a 3.2 or 3.3 feature has no registered pre-3.2 extension, the fallback is x-permdock-* (as for oauth2MetadataUrl).
2. Use a registered extension whenever one exists for the purpose, including extensions outside the oai namespace (x-agent-trust).
3. Otherwise use x-permdock-*, document it in the table above, and version its shape through x-permdock-catalog.v.
4. Never write into another registered namespace (x-ms-, x-sap-, x-scalar-, x-jsonschema-), nor into an unregistered vendor namespace a consumer reads as its own: gateway import fields (x-amazon-apigateway-*, x-google-*, x-kong-*, x-zuplo-*), docs-host and generator fields (x-mint, x-mcp, x-topics, x-fern-*, x-speakeasy-*, x-stainless-*, x-readme), nor another party's extension for a protocol PermDock has not adopted (the community x-gnap; see GNAP). A team that wants one of those derived from PermDock's fields writes its own consumer-side overlay (OpenAPI ecosystem), even when a field there looks close.
5. The importer reads the native fields, the registered fallbacks and the x-permdock-* set; unknown extensions are preserved untouched, never dropped.
6. Draft-only native fields (today the type: profile scheme and securityProfileRequirements on --target 3.3, and the Overlay 1.2 components.actions shape on --overlay 1.2) are emitted only behind an experimental flag, always with a stable twin (the x-permdock-* extension, or the 1.1 Overlay form), and with the pinned revision written into x-permdock-catalog.drafts (ADR 0025).

The emitter's test fixtures enforce rule 1 mechanically: output containing any x-oai-* name outside the three registered ones fails the suite.

Mapping table

Sources

• OpenAPI Initiative registries.
• Namespace Registry.
• Extension Registry.
• OAI/spec.openapis.org, where registrations are submitted.

Related

• OpenAPI 3.2: the 3.1 fallback table.
• OpenAPI Overlay: how the extensions are delivered without mutating the source document.
• OpenAPI 3.3: why x-permdock-securityProfile exists and what it twins on 3.3 output.
• ADR 0025: the draft pin in x-permdock-catalog.drafts.
• Web Bot Auth: the scheme that carries x-agent-trust.
• OpenAPI adapter and CLI: openapi.
• ADR 0019.

Open questions

• Whether x-permdock-permissions should become an array of { key, scope } objects so a document is self-describing without the catalog; today the scope is only readable from security.
• The exact x-agent-trust field names and trust-level values, to be copied from the registry entry when Phase 4 starts.
• Whether x-permdock-catalog should carry a hash of the catalog or its v and generator version only.