Updated to use standard schema

Author: robertpitt

README.md

@@ -2,26 +2,27 @@
 
 Contract-first, type-safe API definitions for itty-router.
 
-`itty-spec` is a small layer on top of itty-router that turns an API contract into:
+`itty-spec` is a super lightweight dependency that builds on [itty-router](https://itty.dev/itty-router), [Standard Schema V1](https://github.com/standard-schema/spec), and [Standard Community](https://github.com/standard-community) packages. Designed for small workers, lambdas, and backend servers, it turns an API contract into:
 
 - A ready-to-export `fetch` handler
 - Automatic request parsing and validation (params, query, headers, body)
-- Fully inferred TypeScript types in your route handlers
+- Fully inferred TypeScript types in your route handlers with end-to-end type safety
 - Typed, contract-checked responses (status code + content type + body)
-- Optional OpenAPI 3.1 spec generation from the same contract (Zod v4 supported)
+- Optional OpenAPI 3.1 spec generation and serving from the same contract
 
-If you like itty-router’s “tiny router for Fetch” mental model, `itty-spec` keeps that model and adds a single source of truth: the contract.
+If you like itty-router's "tiny router for Fetch" mental model, `itty-spec` keeps that model and adds a single source of truth: the contract. Perfect for Cloudflare Workers, AWS Lambda, Node.js servers, Bun, and Deno.
 
 ---
 
 ## What this project provides
 
 - **Contract-first API design**: define routes, inputs, and outputs once.
-- **Runtime validation**: invalid requests are rejected before your handler runs.
-- **End-to-end TypeScript inference**: handlers receive typed, validated data.
-- **Typed response builder**: responses must match the contract (status/content-type/body).
+- **Fully typed TypeScript experience**: complete type inference from contract to handler, with compile-time guarantees for request/response shapes.
+- **Runtime validation**: invalid requests are rejected before your handler runs, using Standard Schema V1 compatible validators.
+- **End-to-end TypeScript inference**: handlers receive typed, validated data (`validatedParams`, `validatedQuery`, `validatedBody`, `validatedHeaders`).
+- **Typed response builder**: responses must match the contract (status/content-type/body) - TypeScript errors catch mismatches at compile time.
 - **Fetch-first compatibility**: works in any environment that supports the Fetch API.
-- **OpenAPI generation (optional)**: generate an OpenAPI 3.1 document from the contract (currently Zod v4).
+- **OpenAPI generation and serving**: generate and serve OpenAPI 3.1 specifications from the same contract using `@standard-community/standard-openapi`.
 
 ## What this project is not
 
@@ -31,6 +32,18 @@ If you like itty-router’s “tiny router for Fetch” mental model, `itty-spec
 
 ---
 
+## Foundation
+
+`itty-spec` is built on a lightweight foundation of battle-tested libraries:
+
+- **[itty-router](https://itty.dev/itty-router)** (v5): The tiny router for Fetch that powers routing and request handling.
+- **[Standard Schema V1](https://github.com/standard-schema/spec)** (`@standard-schema/spec`): Provides a common interface for schema validation, enabling compatibility with multiple schema libraries.
+- **[Standard Community OpenAPI](https://github.com/standard-community/standard-openapi)** (`@standard-community/standard-openapi`): Converts Standard Schema V1 schemas to OpenAPI 3.1 format for documentation and tooling.
+
+This architecture ensures minimal bundle size while providing maximum type safety and developer experience. The library is designed to work seamlessly in edge/serverless environments where every byte counts.
+
+---
+
 ## Installation
 
 ```bash
@@ -146,6 +159,21 @@ export default {
 
 ---
 
+## Target environments
+
+`itty-spec` is designed to be lightweight and efficient, making it ideal for:
+
+- **Cloudflare Workers**: Edge computing with minimal cold start times
+- **AWS Lambda**: Serverless functions with size constraints
+- **Node.js servers**: Traditional backend servers
+- **Bun**: Fast JavaScript runtime
+- **Deno**: Secure runtime for JavaScript and TypeScript
+- **Any Fetch-compatible environment**: Works wherever the Fetch API is available
+
+The library's minimal dependencies and small bundle size ensure fast startup times and low memory footprint, critical for edge and serverless deployments.
+
+---
+
 ## Core concepts
 
 ### Contract
@@ -174,32 +202,64 @@ The shape of that response is type-checked against the contract for the current
 
 ## Schema support
 
-`itty-spec` is designed to work with schema libraries that implement the Standard Schema V1 interface. In practice:
+`itty-spec` uses the [Standard Schema V1](https://github.com/standard-schema/spec) interface, which provides a common abstraction layer for schema validation. This means you can use any Standard Schema V1 compatible library:
+
+* **Zod (v4)**: Fully supported with excellent TypeScript inference and OpenAPI generation. Recommended for the best developer experience.
+* **Valibot**: Fully supported with OpenAPI generation via `@standard-community/standard-openapi`.
+* **Other Standard Schema compatible libraries**: Can be used for validation; OpenAPI support depends on the library's Standard Schema V1 implementation.
 
-* Zod (v4) is supported and is the best experience today (including OpenAPI generation).
-* Other Standard Schema compatible libraries can be used for validation; OpenAPI support may vary.
+The Standard Schema V1 interface ensures that your contracts remain portable across different schema libraries while maintaining type safety and runtime validation.
 
 ---
 
-## OpenAPI 3.1 generation (optional)
+## OpenAPI 3.1 generation and serving (optional)
 
-If you want a formal API spec (documentation, SDK generation, Postman/Insomnia import), generate an OpenAPI document directly from your contract:
+Generate an OpenAPI 3.1 specification directly from your contract and serve it as a documentation endpoint:
 
 ```ts
 import { createOpenApiSpecification } from "itty-spec/openapi";
+import { createRouter } from "itty-spec";
 import { contract } from "./contract";
+import { z } from "zod";
 
-const openApiSpec = createOpenApiSpecification(contract, {
+// Generate the OpenAPI spec
+const openApiSpec = await createOpenApiSpecification(contract, {
   title: "My API",
   version: "1.0.0",
   description: "Example API built with itty-spec",
   servers: [{ url: "https://api.example.com", description: "Production" }],
 });
 
-console.log(JSON.stringify(openApiSpec, null, 2));
+// Serve it as a route in your router
+const router = createRouter({
+  contract: {
+    ...contract,
+    getSpec: {
+      path: "/openapi.json",
+      method: "GET",
+      responses: {
+        200: {
+          "application/json": { body: z.any() },
+        },
+      },
+    },
+  },
+  handlers: {
+    ...yourHandlers,
+    getSpec: async (request) => {
+      return request.respond({
+        status: 200,
+        contentType: "application/json",
+        body: openApiSpec,
+      });
+    },
+  },
+});
 ```
 
-OpenAPI generation currently supports Zod v4 schemas via `toJSONSchema()`.
+OpenAPI generation uses `@standard-community/standard-openapi` to convert Standard Schema V1 schemas to OpenAPI 3.1 format. This supports Zod v4 and Valibot schemas out of the box. You can then use tools like [Swagger UI](https://swagger.io/tools/swagger-ui/), [Redoc](https://github.com/Redocly/redoc), or [Elements](https://github.com/stoplightio/elements) to render interactive documentation from the served specification.
+
+See the `examples/simple` and `examples/complex` directories for complete examples of serving OpenAPI documentation.
 
 
 ## Repository layout
@@ -210,7 +270,9 @@ OpenAPI generation currently supports Zod v4 schemas via `toJSONSchema()`.
 
 ## References
 
-- [itty-router](https://itty.dev/itty-router)
+- [itty-router](https://itty.dev/itty-router) - The tiny router for Fetch
+- [Standard Schema V1](https://github.com/standard-schema/spec) - Common schema interface
+- [Standard Community OpenAPI](https://github.com/standard-community/standard-openapi) - OpenAPI generation from Standard Schema
 
 ## License
 

examples/complex/index.ts

@@ -15,7 +15,7 @@ import { join } from 'path';
 /**
  * Convert the contract to an OpenAPI specification
  */
-const openApiSpecification = createOpenApiSpecification(contract, {
+const openApiSpecification = await createOpenApiSpecification(contract, {
   title: 'Complex API',
   version: '1.0.0',
   description: readFileSync(join(import.meta.dirname, 'description.md'), 'utf8'),

examples/simple/index.ts

@@ -13,7 +13,7 @@ import { IRequest } from 'itty-router';
 /**
  * Convert the contract to an OpenAPI specification so we can serve it from the router
  */
-const openApiSpecification = createOpenApiSpecification(contract, {
+const openApiSpecification = await createOpenApiSpecification(contract, {
   title: 'Simple API',
   version: '1.0.0',
   // markdown description showing of the markdown syntax

examples/valibot/index.ts

@@ -15,7 +15,7 @@ import {
 /**
  * Convert the contract to an OpenAPI specification so we can serve it from the router
  */
-const openApiSpecification = createOpenApiSpecification(contract, {
+const openApiSpecification = await createOpenApiSpecification(contract, {
   title: 'Simple API (Valibot)',
   version: '1.0.0',
   // markdown description showing of the markdown syntax

package.json

@@ -1,6 +1,6 @@
 {
   "name": "itty-spec",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Type-safe contract first itty-router",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -69,6 +69,7 @@
     "@types/bun": "^1.3.4",
     "@types/node": "^25.0.1",
     "@valibot/to-json-schema": "^1.5.0",
+    "zod-openapi": "^4.0.0",
     "@vitest/coverage-v8": "^4.0.15",
     "@whatwg-node/server": "^0.10.17",
     "husky": "^9.1.7",
@@ -81,6 +82,7 @@
     "zod": "v4"
   },
   "dependencies": {
+    "@standard-community/standard-openapi": "^0.2.0",
     "@standard-schema/spec": "^1.0.0",
     "itty-router": "^5"
   }