Wiki · Concept · Last reviewed June 25, 2026

OpenAPI Specification

The OpenAPI Specification is a vendor-neutral description format for HTTP APIs: the written contract that lets humans, software tools, and AI agents inspect what an API claims to do before they call it.

Category: Concept / API Contracts Updated: June 25, 2026 Tags: OpenAPI, API governance, tool use, agents, JSON Schema

Definition

The OpenAPI Specification, or OAS, is a standard for describing HTTP APIs in a structured document. The OpenAPI Initiative's current published specification is v3.2.0, dated September 19, 2025. The specification defines an API description that can be read by developers, validators, documentation generators, testing systems, API gateways, client generators, and increasingly by agent hosts that need to turn remote APIs into controlled tools.

OpenAPI matters to Spiralism because it changes an interface from rumor into record. A model asked to "use the billing API" should not infer the contract from prose, snippets, or memory. It should have a declared surface: servers, paths, operations, parameters, request bodies, responses, media types, authentication methods, and versioned evidence about what was reviewed.

That does not make an API safe. It makes part of the API legible. A strong OpenAPI description is a map of allowed shapes and documented intentions; it is not authorization, business judgment, privacy review, or proof that the live service behaves exactly as described.

Mechanism

An OpenAPI document is a JSON object that can be represented in JSON or YAML. Its root OpenAPI Object identifies the OAS version and usually includes info, servers, paths, components, and security-related fields. The info object names and versions the described API. The servers array defines base URLs. The paths object maps relative URL paths to Path Item Objects, and those Path Item Objects define HTTP operations such as get, post, put, patch, and delete.

The Operation Object is the practical workbench. It can define an operationId, tags, summaries, parameters, request bodies, response objects, callbacks, links, security requirements, and operation-specific servers. The Components Object holds reusable definitions such as schemas, responses, parameters, examples, request bodies, headers, security schemes, links, callbacks, path items, and extension points. Schema Objects are aligned with JSON Schema dialects, but the OpenAPI publications page warns that schemas do not catch every specification violation; when a schema and the prose specification disagree, the prose specification controls.

Agent Context

OpenAPI is becoming part of the background machinery of Tool Use and Function Calling. A tool platform can read an OpenAPI description, select operations, transform them into model-callable functions, generate client code, create tests, or put a gateway in front of the service. The OpenAPI Initiative describes the standard as useful for understanding APIs, generating clients, creating tests, and applying design standards.

The agent version of that workflow is tempting and dangerous. An operationId can become a tool name. A request schema can become a constrained argument shape. A response schema can become an expected observation. But tool safety is not inherited from the description. The host still needs authentication, rate limits, network egress controls, human approval for irreversible actions, semantic validation for money or identity changes, and logs that show exactly which OpenAPI document produced which tool definition.

Governance Use

A serious OpenAPI governance record should identify the OAS version, API version, document URL, document hash, owner, review date, servers, exposed operations, security schemes, OAuth scopes, dangerous operations, generated artifacts, validators, tests, and deployment gates. For agent use, it should also record the transformation from API operation to tool contract: omitted operations, renamed operations, added descriptions, narrowed schemas, approval policies, and reasons for exclusion.

This matters because API descriptions drift. A service may add a side effect, change an enum, alter an error response, deprecate an endpoint, or move an operation behind a different scope. If an agent is allowed to act from a stale OpenAPI file, the interface can look clean while the live system has changed underneath it.

Limits

OpenAPI is not a permission system, privacy impact assessment, terms-of-service analysis, threat model, consent mechanism, or guarantee of current implementation. It can describe headers and schemes; it cannot ensure a caller is authorized. It can describe a refund endpoint; it cannot decide whether a refund is legitimate. It can describe a schema; it cannot capture every business rule, social consequence, abuse case, or cross-system side effect.

The specification can also become false authority. Neat documentation makes weak governance look disciplined. A generated client or tool wrapper can multiply the error by turning an inaccurate description into software, tests, docs, and agent affordances. The remedy is not to reject OpenAPI. The remedy is to treat it as reviewable evidence, not as reality itself.

Review Record

Source Discipline

Claims about the standard should cite the exact OpenAPI version, not a generic memory of "Swagger" or an older OAS release. The document's openapi field names the specification version; the info.version field names the API being described. Those are different facts. Claims about current publication status should use the OpenAPI Initiative publications page or the latest-spec redirect, and claims about schema validation should preserve the distinction between formal schemas and the authoritative specification text.

Spiralist Reading

Spiralism reads OpenAPI as contract before command. Before a machine reaches into a service, the community should be able to inspect the declared shape of that reach. The discipline is modest: name the operation, narrow the inputs, state the authority, keep the evidence, and remember that no interface description absolves the human institution that chose to expose it.

Sources

Return to Wiki