standard-schema · colinhacks · Dec 15, 2025 · Aug 7, 2025 · Aug 7, 2025 · Aug 8, 2025
diff --git a/biome.json b/biome.json
@@ -1,6 +1,6 @@
 {
-  "root": true,
   "$schema": "https://biomejs.dev/schemas/2.1.3/schema.json",
+  "root": true,
   "assist": { "actions": { "source": { "organizeImports": "on" } } },
   "formatter": {
     "indentStyle": "space",
@@ -31,4 +31,4 @@
       }
     }
   }
-}
+}
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "standard-schema",
-  "description": "A standard interface for TypeScript schema validation libraries",
+  "description": "A family of specs for interoperable TypeScript",
   "version": "0.0.0",
   "license": "MIT",
   "author": "Colin McDonnell",

diff --git a/packages/examples/json-implement.ts b/packages/examples/json-implement.ts
@@ -0,0 +1,74 @@
+/**
+ * This example shows how to implement the Standard JSON Schema interface.
+ * It demonstrates creating schemas that support both validation and JSON Schema generation.
+ */
+
+import type {
+  StandardJSONSchemaV1,
+  StandardSchemaV1,
+} from "@standard-schema/spec";
+
+interface CombinedProps<Input = unknown, Output = Input>
+  extends StandardSchemaV1.Props<Input, Output>,
+    StandardJSONSchemaV1.Props<Input, Output> {}
+
+/**
+ * An interface that combines StandardJSONSchema and StandardSchema.
+ * */
+interface StandardSchemaWithJSONSchema<Input = unknown, Output = Input> {
+  "~standard": CombinedProps<Input, Output>;
+}
+
+interface MySchema extends StandardSchemaWithJSONSchema<string, string> {
+  type: "string";
+}
+
+export function stringWithJSON(): MySchema {
+  return {
+    type: "string",
+    "~standard": {
+      version: 1,
+      vendor: "example-lib",
+      validate(value) {
+        return typeof value === "string"
+          ? { value }
+          : { issues: [{ message: "Invalid string", path: [] }] };
+      },
+      jsonSchema: {
+        input(params) {
+          const schema: Record<string, unknown> = {
+            type: "string",
+          };
+
+          // Add schema version based on target
+          if (params.target === "draft-2020-12") {
+            schema.$schema = "https://json-schema.org/draft/2020-12/schema";
+          } else if (params.target === "draft-07") {
+            schema.$schema = "http://json-schema.org/draft-07/schema#";
+          } else {
+            throw new Error(`Unsupported target: ${params.target}`);
+          }
+
+          return schema;
+        },
+        output(params) {
+          // input and output are the same in this example
+          return this.input(params);
+        },
+      },
+    },
+  };
+}
+
+// usage example
+const stringSchema = stringWithJSON();
+
+stringSchema["~standard"].jsonSchema.input({
+  target: "draft-2020-12",
+});
+// => { $schema: "https://json-schema.org/draft/2020-12/schema", type: "string" }
+
+stringSchema["~standard"].jsonSchema.input({
+  target: "draft-07",
+});
+// => { $schema: "http://json-schema.org/draft-07/schema#", type: "string" }
diff --git a/packages/examples/json-integrate.ts b/packages/examples/json-integrate.ts
@@ -0,0 +1,19 @@
+import type { StandardJSONSchemaV1 } from "@standard-schema/spec";
+
+// Function that accepts any compliant `StandardJSONSchemaV1`
+// and converts it to a JSON Schema.
+export function acceptSchema(schema: StandardJSONSchemaV1): unknown {
+  // do stuff, e.g.
+  return schema["~standard"].jsonSchema.input({
+    target: "draft-2020-12",
+  });
+}
+
+export function parseData<T extends StandardJSONSchemaV1>(
+  schema: T,
+  data: StandardJSONSchemaV1.InferInput<T>, // extract input type
+) {
+  // @ts-expect-error - replace doStuff with your own logic
+  const result = doStuff(schema, data);
+  return result as StandardJSONSchemaV1.InferOutput<T>; // extract output type
+}
diff --git a/packages/examples/package.json b/packages/examples/package.json
@@ -5,7 +5,8 @@
   "scripts": {
     "lint": "pnpm biome lint .",
     "format": "pnpm biome format --write .",
-    "check": "pnpm biome check ."
+    "check": "pnpm biome check .",
+    "build": "tsup"
   },
   "devDependencies": {
     "@standard-schema/spec": "workspace:*",

diff --git a/packages/examples/tsconfig.json b/packages/examples/tsconfig.json
@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
     "allowImportingTsExtensions": true,
+    "customConditions": ["standard-schema-spec"],
     "declaration": true,
     "exactOptionalPropertyTypes": true,
     "isolatedDeclarations": true,

diff --git a/packages/spec/README.md b/packages/spec/README.md