openapi

Documentation

Overview

Package openapi builds the committed OpenAPI 3.1 / JSON-Schema artifacts from the Go schema source. This schema module is the source of truth; the village vendors + serves + enforces these specs (GH #53). Every spec is generated by a Build*Spec function and emitted (byte-for-byte) to generated/ at the module root by GenerateSpecArtifacts; the codegen-freshness test (cmd/schema-gen) diffs the committed copies against a fresh regen and fails on any drift.

Versioning policy (doc-surface semver)

Each spec carries its OWN info.version, which is an INDEPENDENT doc-surface semantic version describing that spec's API SURFACE — not a shared release number across specs:

• Additive change (new route, new schema/component, new enum value) ⇒ MINOR bump.
• Breaking change (removed/renamed route or field, changed type, tightened constraint) ⇒ MAJOR bump.

Example: adding the /api/v1/pull surface to the village-api spec was purely additive, so VillageAPIVersion went 0.1.0 → 0.2.0 (minor).

This doc-surface semver is a SEPARATE axis from the runtime WIRE-CONTRACT versions. The push/pull content contracts are negotiated at runtime via the [Min, Current] windows in internal/defaults/schema.go (PushContractVersion / PullContractVersion) over GET /api/v1/schema/version. Those windows govern whether a given CLI may talk to a given village; the spec's info.version only documents the HTTP surface. The two move independently — EXCEPT that an envelope-SHAPE change (a breaking change to the publish/pull wire envelope) is simultaneously a contract-version bump (it shifts the negotiated window) AND a spec major bump (the documented surface changed). A spec-only additive bump does NOT touch the contract windows, and a window slide that does not alter the HTTP surface does NOT bump the spec.

Single source per spec

Each spec's version is written in EXACTLY ONE place — the const block in artifacts.go (VillageAPIVersion, PeasantLocalAPIVersion, TypesVersion). That const feeds, by derivation and never by retyping:

• info.version, via WithVersion(<Const>) in each Build*Spec function;
• the versioned artifact filename (e.g. "village-api-0.2.0.json"), in GenerateSpecArtifacts;
• the human-readable doc labels ("Village API v0.2.0") in cmd/schema-gen;
• the freshness test's artifact-key assertions.

To cut a new spec version, edit ONLY the relevant const and run `go run ./cmd/schema-gen` (NOT `go generate ./...`, which no-ops on this nested module). Filenames are versioned; there is no unversioned "latest" alias.

Publish-body enforcement schema (derived, not separately reflected)

The village ENFORCES incoming publish bodies (422 on schema violation) against a standalone PublishRequest JSON Schema it vendors as backend/internal/handler/openapispec/publish-request.schema.json. That schema is produced by BuildPublishRequestSchema, which EXTRACTS the SchemaPublishRequest component — with its full transitive $ref closure, bundled into "$defs" — out of the village-api spec itself (JSON Schema 2020-12, the dialect the village's santhosh-tekuri validator supports). Deriving the enforced schema FROM the documented spec (rather than a separate reflector) means the two can never drift. Its filename and "$id" are versioned by VillageAPIVersion, the spec it is extracted from.

This REPLACED the retired legacy builders BuildJSONSchema + BuildOpenAPISpec (which emitted the push-contract-keyed "openapi-<v>.{json,yaml}" artifacts). The retirement is pinned by an enforcement-PARITY gate (publish_schema_parity_test.go): a frozen copy of the old BuildJSONSchema output (testdata/legacy-publish-request.schema.json) and the new extracted schema must return IDENTICAL accept/reject verdicts across a corpus of valid + malformed bodies. See GH #53.

Index

• Constants
• func AddPeasantLocalExamples(spec *openapi31.Spec)
• func AddVillageExamples(spec *openapi31.Spec)
• func BuildPeasantLocalAPISpec() (*openapi31.Spec, error)
• func BuildPublishRequestSchema(version string) ([]byte, error)
• func BuildTypesSpec() (*openapi31.Spec, error)
• func BuildVillageAPISpec() (*openapi31.Spec, error)
• type SpecArtifacts
  • func GenerateSpecArtifacts() (SpecArtifacts, error)

Constants

const (
	// VillageAPIVersion is the info.version of the Village API spec.
	VillageAPIVersion = schema.VillageAPIVersion
	// PeasantLocalAPIVersion is the info.version of the local dashboard API spec.
	PeasantLocalAPIVersion = schema.PeasantLocalAPIVersion
	// TypesVersion is the info.version of the types spec.
	TypesVersion = schema.TypesVersion
)

Versioned-spec info.version values are re-exported from the root schema package (the single source of truth — see versions.go there). The spec builders in this package reference them unqualified, and the root accessor schema.VillageAPISpecJSON() keys its embedded-bytes lookup off the same constants, so a version bump stays a one-line edit at the root and flows here automatically. They are kept exported here for backward compatibility with existing openapi.* call sites.

Functions

func AddPeasantLocalExamples

func AddPeasantLocalExamples(spec *openapi31.Spec)

AddPeasantLocalExamples injects operation-level response examples into the local dashboard API spec.

func AddVillageExamples

func AddVillageExamples(spec *openapi31.Spec)

AddVillageExamples injects operation-level examples into the village API spec. Covers POST /api/v1/transcripts/publish request body and 200 response.

func BuildPeasantLocalAPISpec

func BuildPeasantLocalAPISpec() (*openapi31.Spec, error)

BuildPeasantLocalAPISpec builds an OpenAPI 3.1 specification for the local web dashboard API v1.0. It includes REST routes (/health, /sessions, /config/mock, /shutdown) and WebSocket channel message schemas (DashboardPayload, SessionsPayload, SessionDetailPayload, TrendsPayload, QualityPayload) as JSON Schema components.

func BuildPublishRequestSchema

func BuildPublishRequestSchema(version string) ([]byte, error)

BuildPublishRequestSchema EXTRACTS the PublishRequest component — with all of its transitive $ref dependencies, bundled and self-contained — out of the village-api OpenAPI 3.1 spec into a standalone JSON Schema 2020-12 document.

This is the SINGLE SOURCE OF TRUTH for the village's publish-body enforcement: the village vendors the bytes returned here as backend/internal/handler/openapispec/publish-request.schema.json and compiles them with santhosh-tekuri/jsonschema to reject malformed publish bodies (422). Deriving it from the village-api spec (rather than a separate reflector) means the documented HTTP surface and the enforced wire schema can never drift — they come from one Build*Spec function (GH #53: peasant is the source of truth, the village vendors + enforces).

The returned document:

• sets "$schema" to the JSON Schema 2020-12 dialect (pinned explicitly so the village validator selects the right draft);
• sets "$id" to urn:peasant:publish-request:<VillageAPIVersion> (derived from the single-source version const, never retyped);
• hoists SchemaPublishRequest's own keywords (type, properties) to the root;
• bundles every transitively-referenced component under "$defs", with all "#/components/schemas/X" $refs rewritten to "#/$defs/X".

version is the doc-surface version stamped into "$id" (callers pass VillageAPIVersion).

func BuildTypesSpec

func BuildTypesSpec() (*openapi31.Spec, error)

BuildTypesSpec builds an OpenAPI 3.1 specification registering foundational shared domain types as reusable components. No paths — this is a pure type catalog for SDK code generators and type-sharing across API boundaries.

Registered entry-point types (7 top-level components):

• Provider, Role, SessionID, ModelID (primitive domain types)
• Visibility (access control)
• SessionEntry (content layer)
• QualityMetrics (analytics)

Transitively referenced types (ToolCallKind, StopReason, EntryType, SessionOutcome, etc.) are collected via CollectDefinitions and registered as separate top-level components. All component names and $ref paths are normalized to plain names (no "Schema" prefix).

func BuildVillageAPISpec

func BuildVillageAPISpec() (*openapi31.Spec, error)

BuildVillageAPISpec builds an OpenAPI 3.1 specification for the Village API v1.1. It includes POST /api/v1/transcripts/publish with PublishRequest/PublishResponse, GET /api/v1/auth/cli/login and POST /api/v1/auth/cli/exchange for CLI authentication, and registers all content-layer types (SessionEntry, ToolCallKind, StopReason, Visibility) as reusable components.

Types

type SpecArtifacts

type SpecArtifacts map[string][]byte

SpecArtifacts is the set of generated OpenAPI spec files, keyed by filename (e.g. "village-api-0.2.0.json"), each mapping to the exact bytes written to generated/ at the module root. It is the single source of truth for what the generator emits, shared by cmd/schema-gen (which writes them) and the codegen-freshness test (which diffs them against the committed copies). It does NOT include the HTML docs/CLI reference — those are non-contract artifacts.

func GenerateSpecArtifacts

func GenerateSpecArtifacts() (SpecArtifacts, error)

GenerateSpecArtifacts builds every committed OpenAPI JSON/YAML spec from the Go schema source and returns them as filename->bytes. The marshaling here MUST match cmd/schema-gen exactly (both call this function), so a clean tree regenerates byte-for-byte and the freshness test only fails on real drift.