TypeSpec Contract Authority Standard

TypeSpec is the central structural authority for new Wavenumber-owned contracts that cross language or process boundaries. This standard is independent of web, GUI, frontend, and application-framework guidance. Backend services, CLIs, configuration packages, native applications, libraries, workers, and data systems can adopt it directly.

CapabilityName

Names a cross-cutting standard capability independently of project profile.

default_typespec_contract_standard

Returns the TypeSpec contract-authority capability rules.

default_capability

Returns a named cross-cutting standard capability.

render_typespec_contract_standard

Renders the TypeSpec contract-authority capability as text or JSON.

render_capability

Renders a named cross-cutting standard capability as text or JSON.

Applicability

Posture	Applies when
Required	A new Wavenumber-owned contract crosses a language or process boundary, including APIs, events, worker messages, local services, command envelopes, and shared serialized payloads.
Strongly recommended	A durable root object or configuration format is initially single-language but is persisted, externally consumed, tool-facing, or likely to gain another implementation.
Optional	A private serialized shape has one owner, no durable compatibility promise, and no likely cross-language consumer.
Not the authority	A format is owned upstream, or the concern is implementation behavior, effects, transactions, orchestration, or runtime-only state rather than structural data.

Authority Boundary

TypeSpec owns names, fields, required and optional properties, scalar constraints, unions, discriminators, operation shapes, error envelopes, event payloads, and compatibility-visible evolution. Generated JSON Schema, OpenAPI, Python, Rust, TypeScript, and other outputs are projections of that authority and must not be hand-edited.

Handwritten domain code owns behavior that a structural contract cannot faithfully express: validation requiring external state, transactions, effects, identity resolution, scheduling, orchestration, and business methods.

Contract Units

TypeSpec governance is a cross-cutting capability, not a primary-language profile. A repository may declare one or more named contract units. The configuration surface has this shape:

[contracts]
[[contracts.units]]
id = "library-domain"
authority = "typespec"
root = "contracts/library-domain"
entrypoint = "contracts/library-domain/main.tsp"
config = "contracts/library-domain/tspconfig.yaml"
compatibility = "versioned"
toolchain_manifest = "package.json"
lockfile = "package-lock.json"
emitter_packages = ["@typespec/json-schema", "@typespec/openapi3"]
generated_policy = "docs/generated-files.md"

[contracts.units.commands]
generate = "npm run generate"
freshness = "npm run check:generated"
conformance = "npm test"

[[contracts.units.projections]]
kind = "json-schema"
output = "generated/schema/library-domain"
required = true
support = "supported"
consumer_evidence = ["tests/node/schema.test.mjs", "tests/python/conformance.py"]

[[contracts.units.projections]]
kind = "typescript"
output = "generated/typescript/library-domain"
required = true
support = "supported"
consumer_evidence = ["frontend:typecheck", "frontend:test"]

The surface represents authority ownership, source/config paths, pinned tooling, outputs, real consumer requirements, regeneration, freshness, conformance, publication, and reviewed exceptions.

Toolchain And Generation

Pin the TypeSpec compiler, libraries, and emitters.
Treat compiler warnings as errors in signoff.
Provide deterministic generate and freshness-check commands.
Keep generated output in declared generated roots.
Document source of truth, regeneration, release inclusion, and editing policy.
Compile or validate real consumers against every required projection.
Do not generate an unused language merely to satisfy a generic checklist.

Projection Support

The standard uses three support states: fully supported and tested, experimental, and extension seam. A projection is fully supported only when its emitter is independently installable, generation is reproducible, and consumer or conformance evidence is part of signoff.

Projection	Reference support	Evidence
JSON Schema	Supported	Generated by the pinned TypeSpec emitter; consumed by Node and Python conformance tests.
OpenAPI	Supported when HTTP operations exist	Generated by the pinned TypeSpec emitter and used as the TypeScript input.
TypeScript declarations	Supported	Generated from OpenAPI and compiled by a real TypeScript consumer.
Python source generation	Extension seam	The reference validates JSON Schema from Python but does not claim a Python model emitter.
Rust source generation	Extension seam	No Rust emitter is claimed until an independently pinned generator and consumer test are added.

The first reference floor is TypeSpec compilation, JSON Schema, one generated language projection consumed by executable code, and shared conformance vectors exercised by a second independent runtime. Python and Rust generation are added only when their emitters meet the same bar.

Compatibility

Durable root payloads carry explicit identity and version posture.
Variant families use stable discriminators.
Breaking changes require a new version or a documented migration.
Deprecation retains enough evidence for active consumers to migrate.
Events define identity, ordering, correlation, and replay expectations.

Exceptions

An exception must name the exact contract unit and construct, explain why TypeSpec is not authoritative or why a projection is lossy, identify the temporary authority, and define a review trigger. Upstream ownership is a valid boundary, but it must identify the upstream specification.

Audit And Signoff Boundary

Dev-std audit validates declarations, paths, ownership, output placement, pinning posture, documentation, exceptions, and signoff wiring without installing dependencies or running arbitrary commands. Project or Rack signoff executes compilation, generation, freshness, consumer compilation, and conformance tests.

Template Distribution

Version-matched templates are packaged resources exposed through dev-std template copy and remain browsable in the corresponding source release tag. A template must be private and copy-owned after adoption; it is not a shared runtime framework.

Executable Evidence

docs/templates/typespec-contract/ is the canonical runnable evidence for this contract. Its TypeSpec source, generated JSON Schema and OpenAPI, generated TypeScript declarations, and Node/Python conformance tests are exercised from clean copies during release signoff. Maintainer commands are defined in Build Documentation.