openapi library

The libs/openapi/ area: a single Nx library, @oshun/openapi, that owns the platform's OpenAPI surface — loading, validating, generating, and drift-checking the REST specs (and the typed clients) for every Oshun domain.

What this area is#

libs/openapi/ is one Nx project — @oshun/openapi (libs/openapi/project.json, sourceRoot libs/openapi/src) — not a cluster. It is the place where the monorepo's REST contracts stop being scattered hand-written YAML and become a managed, generated, drift-checked artifact set. The package is private, ESM-only (package.json "type": "module", version 0.1.0), and its description is authoritative: "OpenAPI specifications for Oshun REST APIs."

The library has four jobs, all visible in its source. First, loading: src/utils/loader.ts reads and parses the canonical YAML specs under src/specs/ (and the V2 surface under v2/) into OpenAPIV3_1.Document objects, and can mergeSpecs(...) several into one. Second, a registry: src/utils/registry.ts declares the ApiDomain union (tara, arete, veritas, lilith, yemaya, isis, sophia, hathor, bellona, calliope, nyx, nisaba, metis, v2, v3, oshun-bff, shared), the SPEC_PATHS map of every spec file, and a SPEC_REGISTRY of per-spec SpecMetadata (name, version, basePath, tags), plus extractEndpoints / extractSchemas helpers that walk a parsed document. Third, generation: src/oshun-v1/spec-builder.ts builds OpenAPI 3.1 documents directly from Zod contracts rather than from hand-edited YAML. Fourth, drift detection: scripts/drift-check.ts compares each canonical YAML against the openapi-typescript-generated TS mirror in src/generated/.

The generation path is the most domain-specific part. buildOshunV1SpecArtifacts() reads V1_OBJECT_PERSISTENCE_CONTRACTS and V1_ENUM_PERSISTENCE_CONTRACTS from @oshun/persistence plus the DOMAIN_REGISTRY from @oshun/domain-registry, and for each of the six V1 API domains (tara, arete, veritas, nyx, nisaba, metis) emits a per-domain service spec, then a consolidated oshun-bff spec. Each object contract is converted to JSON Schema with z.toJSONSchema(...) ($schema stripped) and expanded into a uniform CRUD surface — list / create / get / upsert / tombstone operations, bearerAuth security, cursor pagination (LimitParam / CursorParam), and shared ErrorResponse / PageInfo / TombstoneResponse components. The BFF spec re-uses the same builder with componentNameMode: 'prefixed' and the registry's bff-base-path, so the BFF routes and the per-domain routes describe the same schemas under different prefixes. This is why a contract change is a single source edit, not an N-place YAML rewrite.

Alongside the V1 generator there are sibling generators driven from the package.json scripts and Nx targets: generate-v3-spec.ts / generate-v3-clients.ts (the V3 v3.yaml and the typed clients in src/v3-clients/), generate-calliope-spec.ts, generate-docs.ts (Redoc HTML under docs/), and the validators validate.ts / validate-v3-spec.ts. The Nx project exposes these as openapi:gen, generate:oshun-v1-specs(:check), generate:oshun-v1-clients(:check), generate:v3(:check), validate:v3, and an openapi:validate target that lints src/specs/ with @redocly/cli.

How it fits the wider system#

@oshun/openapi sits downstream of the contract libraries and upstream of every REST consumer. Its hard dependency edges (package.json) are @oshun/contracts, @oshun/persistence, @oshun/domain-registry, and @calliope/core — it reads their Zod contracts and domain metadata as the canonical source and turns them into specs. It does not sit on the request path: nothing here serves HTTP. Instead it produces three kinds of artifact that others consume. Domain services and the BFF use the generated specs (and the :check targets in CI) to keep their routes honest against the contracts. TypeScript callers import the typed fetch clients from @oshun/openapi/v3-clients (e.g. tara-studio, saraswati-stage, lilith-platform, lilith-commons) which share the v3JsonRequest / V3ApiError transport in src/v3-clients/base.ts. And reviewers/docs tooling read the rendered Redoc pages and openapi.yaml files under docs/. The drift checker is the guardrail that ties the three together: when a spec is edited but its generated mirror is not regenerated, drift:check exits non-zero rather than letting the contract and the client types silently diverge.