OpenAPI Spec Class Specification

Class: openapi-spec Version: 1.0.0-draft Conforms to: schema-atoms/design-spec/[email protected]

What This Class Covers

The openapi-spec class represents REST/HTTP API contracts expressed as OpenAPI 3.x documents. It captures the complete interface surface of an HTTP API: paths, operations, request/response schemas, security schemes, and server definitions.

Accepted Asset Formats

• .yaml — YAML-serialized OpenAPI document (preferred for human authorship)
• .json — JSON-serialized OpenAPI document

Normative Requirements

• An openapi-spec atom MUST contain a single asset file whose root object includes an openapi key declaring a version string of the form 3.x.y (OpenAPI 3.x).
• The asset MUST be valid against the OpenAPI 3.x JSON Schema.
• The atom MUST NOT bundle implementation code; it describes the contract only.

Example Atom Reference

schema-atoms/api-spec/[email protected]
├── atom.toml   (class = "openapi-spec")
└── openapi.yaml

This atom would declare the HTTP contract for a payments API, including all paths, request bodies, and response schemas, in a single OpenAPI 3.x document.

# atom.toml — class specification atom for openapi-spec
id          = "schema-atoms/design-spec/openapi-spec-class-spec"
version     = "1.0.0-draft"
content_hash = "8651dbc728ebf50c672bb5c89f22a2ab223aff7ee77b20ab6ee372143fc8b8ee"
lifecycle   = "draft"
created_at  = "2026-05-23T00:00:00Z"

[spec]
class       = "design-spec"
title       = "OpenAPI Spec Class Specification"
summary     = "Normative definition of the openapi-spec atom class in schema-atoms."
authors     = ["convergent-systems-co"]
conforms_to = "schema-atoms/design-spec/[email protected]"
asset       = "spec.md"