Skip to content

feat(types): add @oasty/types with OpenAPI 3.0-3.2 type definitions - #1

Merged
dinwwwh merged 1 commit into
mainfrom
claude/openapi-types-package-ca064a
Aug 29, 2026
Merged

feat(types): add @oasty/types with OpenAPI 3.0-3.2 type definitions#1
dinwwwh merged 1 commit into
mainfrom
claude/openapi-types-package-ca064a

Conversation

@dinwwwh

@dinwwwh dinwwwh commented Aug 29, 2026

Copy link
Copy Markdown
Member

Adds the @oasty/types package: fully documented TypeScript types for the OpenAPI Specification, authored against 3.0.4, 3.1.2, and 3.2.0 — one module per minor version, exported as @oasty/types/v3.0v3.2 plus root namespaces and cross-version unions. Each version re-exports what is structurally unchanged from the previous one and redefines only what changed, so the spec's evolution (JSON Schema 2020-12 in 3.1, $self/QUERY/querystring/streaming in 3.2) is visible in the type layer itself.

Design

  • Type names mirror the spec's section names, and every field carries its spec description as JSDoc with @see links, @default, and @deprecated where the spec says so.
  • Conditional requiredness is encoded where the spec tables define it: security schemes and OAuth flows are discriminated unions, 1XX5XX response keys and /-prefixed paths are template-literal index signatures, and each version's openapi field is version-typed for narrowing.
  • SchemaObject<T = unknown> types the data-carrying fields (enum, default, example, and const/examples in 3.1+); the default keeps plain SchemaObject unchanged.
  • Semantic-only rules (mutual exclusions, at-least-one-of containers, per-location applicability) are documented rather than force-encoded, keeping error messages usable.

Verification

  • Reviewed field-by-field against the official spec documents; all confirmed discrepancies fixed.
  • All 83 official valid documents compile: the OAI example set (3.0/3.1/3.2) and both tests/schema/pass suites from the spec repo, committed as a regression corpus under packages/types/tests that root tsc re-checks; the popular Train Travel API also compiles clean.
  • Of the official tests/schema/fail documents, the type-expressible ones are rejected for the right reasons — including 3.2-only values (style: "cookie") failing in the 3.1 module.
  • Version boundaries are pinned by @ts-expect-error tests (nullable vs type arrays, boolean vs numeric exclusive bounds, no webhooks in 3.0, no QUERY before 3.2).

Tooling

  • Builds with unbuild using orpc-style dev/publish exports (src/*.ts in dev, dist/*.d.mts + .mjs when published); declarations keep all JSDoc.
  • sync:sponsors now lint-fixes exactly the files that changed, discovered via git rather than hardcoded paths, so future directories are covered automatically.
  • tsconfig.lib.json drops the DOM libs; type:check, lint:check, test, and the package build are all green.

TypeScript types for the OpenAPI Specification authored against 3.0.4,
3.1.2, and 3.2.0, one module per minor version. Later versions re-export
types that are structurally unchanged (including everything they
reference) from the previous module and redefine only what changed, so
the spec's own evolution is visible in the type layer.

Authored from the official spec documents and verified against them by
field-level review; validated by compiling the official OAI example set
and both schema-test pass suites (83 documents) plus a popular
real-world spec, committed as a regression corpus under
packages/types/tests.

Built with unbuild using orpc-style dev/publish exports. The
sync:sponsors script now lint-fixes whatever files changed, discovered
via git instead of hardcoded paths.
@dinwwwh
dinwwwh merged commit 1eda30b into main Aug 29, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant