schema-brief 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 schema-brief contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,147 @@
+# schema-brief
+
+Compact JSON Schema into LLM-ready instructions, extract JSON from model output, and validate the response with the same contract.
+
+`schema-brief` is designed for TypeScript AI applications that need structured output without adding a heavy validation or prompt-engineering dependency. It supports the most common JSON Schema subset used for model outputs: objects, arrays, primitives, `required`, `enum`, `const`, string/number bounds, array bounds, and `additionalProperties`.
+
+## Why this exists
+
+Recent JavaScript ecosystem signals point toward three strong open-source opportunities:
+
+- TypeScript-first libraries keep gaining share across web and AI tooling.
+- AI applications increasingly need reliable structured output contracts.
+- Teams want small, auditable packages at LLM boundaries instead of framework lock-in.
+
+This package sits at that boundary: one schema becomes prompt instructions, validation, and retry guidance.
+
+## How It Is Different
+
+`schema-brief` is intentionally smaller than an AI framework and more LLM-focused than a general JSON Schema validator.
+
+| Alternative | Best for | Difference |
+| --- | --- | --- |
+| LangChain structured output | Agent pipelines and retries inside LangChain | `schema-brief` is framework-neutral and has no provider/runtime dependency. |
+| Vercel AI SDK structured output | Full-stack apps already using AI SDK | `schema-brief` can be used before or after any model call, including local models and custom SDKs. |
+| AJV and JSON Schema validators | Full JSON Schema compliance and high-throughput validation | `schema-brief` optimizes for the common LLM-output subset and also generates prompt/repair text. |
+| JSON extraction utilities | Pulling JSON out of messy model text | `schema-brief` couples extraction with schema prompt generation and validation feedback. |
+| Zod/Valibot-based helpers | TypeScript schema-first apps | `schema-brief` starts from portable JSON Schema, which fits OpenAPI, MCP, and provider-native structured outputs. |
+
+## Install
+
+```sh
+npm install schema-brief
+```
+
+## Quick Start
+
+```js
+import { brief, parseStructured, repairPrompt } from "schema-brief";
+
+const schema = {
+  title: "IssueTriage",
+  type: "object",
+  required: ["severity", "summary", "labels"],
+  additionalProperties: false,
+  properties: {
+    severity: { enum: ["low", "medium", "high"] },
+    summary: {
+      type: "string",
+      maxLength: 140,
+      description: "A concise human-readable issue summary"
+    },
+    labels: {
+      type: "array",
+      minItems: 1,
+      maxItems: 5,
+      items: { type: "string" }
+    }
+  }
+};
+
+const systemPrompt = brief(schema);
+// Send systemPrompt to your model.
+
+const result = parseStructured(modelText, schema);
+
+if (!result.ok) {
+  const retryPrompt = repairPrompt(schema, result.issues);
+  // Send retryPrompt with the invalid JSON.
+}
+```
+
+## API
+
+### `brief(schema, options?)`
+
+Returns compact prompt text for a JSON Schema subset.
+
+Options:
+
+- `title`: override schema title in the prompt.
+- `includeDescriptions`: include field descriptions. Defaults to `true`.
+- `examples`: include valid JSON examples.
+- `maxDepth`: limit prompt rendering depth. Defaults to `8`.
+
+### `extractJson(text)`
+
+Extracts and parses the first complete JSON object or array from raw text or markdown fences.
+
+### `validate(schema, value)`
+
+Validates a value against the supported JSON Schema subset.
+
+Returns:
+
+```ts
+{ ok: true, value }
+// or
+{ ok: false, issues: [{ path, code, message }] }
+```
+
+### `parseStructured(text, schema)`
+
+Combines `extractJson` and `validate`.
+
+### `repairPrompt(schema, issues)`
+
+Creates a concise prompt asking a model to repair invalid JSON.
+
+## Supported Schema Keywords
+
+- `type`
+- `title`
+- `description`
+- `enum`
+- `const`
+- `properties`
+- `required`
+- `additionalProperties`
+- `items`
+- `minItems`
+- `maxItems`
+- `minLength`
+- `maxLength`
+- `pattern`
+- `format` for prompt output only
+- `minimum`
+- `maximum`
+
+## Product Roadmap
+
+- Zod adapter: `briefFromZod(schema)`
+- Standard Schema adapter
+- OpenAI, Anthropic, and Vercel AI SDK helpers
+- Token-budgeted schema compression
+- Browser bundle size CI
+- JSON repair suggestions with deterministic patches
+
+## Development
+
+```sh
+npm test
+npm run check
+```
+
+## License
+
+MIT

package/examples/basic.js

@@ -0,0 +1,35 @@
+import { brief, parseStructured, repairPrompt } from "schema-brief";
+
+const schema = {
+  title: "ReleaseNote",
+  type: "object",
+  required: ["summary", "risk", "actions"],
+  additionalProperties: false,
+  properties: {
+    summary: {
+      type: "string",
+      maxLength: 160,
+      description: "One sentence summary for an engineering changelog"
+    },
+    risk: {
+      enum: ["low", "medium", "high"]
+    },
+    actions: {
+      type: "array",
+      minItems: 1,
+      items: { type: "string" }
+    }
+  }
+};
+
+const prompt = brief(schema);
+console.log(prompt);
+
+const modelOutput = `{"summary":"Adds OAuth callback validation.","risk":"low","actions":["Deploy API","Watch auth errors"]}`;
+const parsed = parseStructured(modelOutput, schema);
+
+if (!parsed.ok) {
+  console.log(repairPrompt(schema, parsed.issues));
+} else {
+  console.log(parsed.value);
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "schema-brief",
+  "version": "0.1.0",
+  "description": "Compact JSON Schema prompts and validate structured LLM outputs with zero dependencies.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "check": "node --check src/index.js",
+    "prepublishOnly": "npm test && npm run check"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "json-schema",
+    "structured-output",
+    "typescript",
+    "validation",
+    "prompt"
+  ],
+  "author": "",
+  "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kwakhyun/schema-brief.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kwakhyun/schema-brief/issues"
+  },
+  "homepage": "https://github.com/kwakhyun/schema-brief#readme"
+}

package/src/index.d.ts

@@ -0,0 +1,56 @@
+export type JsonTypeName =
+  | "string"
+  | "number"
+  | "integer"
+  | "boolean"
+  | "null"
+  | "array"
+  | "object";
+
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
+
+export interface JsonSchema {
+  type?: JsonTypeName | JsonTypeName[];
+  title?: string;
+  description?: string;
+  enum?: readonly JsonValue[];
+  const?: JsonValue;
+  properties?: Record<string, JsonSchema>;
+  required?: readonly string[];
+  additionalProperties?: boolean | JsonSchema;
+  items?: JsonSchema | readonly JsonSchema[];
+  minItems?: number;
+  maxItems?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: string;
+  minimum?: number;
+  maximum?: number;
+}
+
+export interface BriefOptions {
+  title?: string;
+  includeDescriptions?: boolean;
+  examples?: readonly JsonValue[];
+  maxDepth?: number;
+}
+
+export interface ValidationIssue {
+  path: string;
+  code: string;
+  message: string;
+}
+
+export type ValidationResult<T = unknown> =
+  | { ok: true; value: T }
+  | { ok: false; issues: ValidationIssue[] };
+
+export type ParseResult<T = unknown> = ValidationResult<T>;
+
+export function brief(schema: JsonSchema, options?: BriefOptions): string;
+export function extractJson(text: string): unknown;
+export function validate<T = unknown>(schema: JsonSchema, value: unknown): ValidationResult<T>;
+export function parseStructured<T = unknown>(text: string, schema: JsonSchema): ParseResult<T>;
+export function repairPrompt(schema: JsonSchema, issues: readonly ValidationIssue[]): string;

package/src/index.js

@@ -0,0 +1,419 @@
+const DEFAULT_MAX_DEPTH = 8;
+
+/**
+ * Compile a JSON Schema subset into a compact, model-readable contract.
+ *
+ * @param {import("./index.d.ts").JsonSchema} schema
+ * @param {import("./index.d.ts").BriefOptions} [options]
+ * @returns {string}
+ */
+export function brief(schema, options = {}) {
+  const lines = [];
+  const title = typeof options.title === "string" ? options.title : schema.title;
+  const lead = title ? `Return JSON for ${title}.` : "Return JSON that matches this schema.";
+
+  lines.push(lead);
+  lines.push("No markdown, comments, or extra text.");
+  lines.push(`Shape: ${describeSchema(schema, { depth: 0, maxDepth: options.maxDepth ?? DEFAULT_MAX_DEPTH })}`);
+
+  if (options.includeDescriptions !== false) {
+    const descriptions = collectDescriptions(schema);
+    if (descriptions.length > 0) {
+      lines.push("Field notes:");
+      for (const note of descriptions) {
+        lines.push(`- ${note.path}: ${note.description}`);
+      }
+    }
+  }
+
+  if (Array.isArray(options.examples) && options.examples.length > 0) {
+    lines.push("Examples:");
+    for (const example of options.examples) {
+      lines.push(stableStringify(example));
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Extract the first complete JSON value from text, including fenced markdown.
+ *
+ * @param {string} text
+ * @returns {unknown}
+ */
+export function extractJson(text) {
+  if (typeof text !== "string") {
+    throw new TypeError("extractJson expected a string");
+  }
+
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  const source = fenced ? fenced[1].trim() : text.trim();
+
+  try {
+    return JSON.parse(source);
+  } catch {
+    const slice = firstJsonSlice(source);
+    if (!slice) {
+      throw new SyntaxError("No JSON object or array found in text");
+    }
+    return JSON.parse(slice);
+  }
+}
+
+/**
+ * Validate a value against the supported JSON Schema subset.
+ *
+ * @param {import("./index.d.ts").JsonSchema} schema
+ * @param {unknown} value
+ * @returns {import("./index.d.ts").ValidationResult}
+ */
+export function validate(schema, value) {
+  const issues = [];
+  visit(schema, value, "$", issues, 0);
+  return issues.length === 0 ? { ok: true, value } : { ok: false, issues };
+}
+
+/**
+ * Extract and validate structured model output in one call.
+ *
+ * @param {string} text
+ * @param {import("./index.d.ts").JsonSchema} schema
+ * @returns {import("./index.d.ts").ParseResult}
+ */
+export function parseStructured(text, schema) {
+  try {
+    const value = extractJson(text);
+    const result = validate(schema, value);
+    return result.ok ? { ok: true, value } : result;
+  } catch (error) {
+    return {
+      ok: false,
+      issues: [
+        {
+          path: "$",
+          code: "invalid_json",
+          message: error instanceof Error ? error.message : "Invalid JSON"
+        }
+      ]
+    };
+  }
+}
+
+/**
+ * Create a concise repair prompt from validation issues.
+ *
+ * @param {import("./index.d.ts").JsonSchema} schema
+ * @param {readonly import("./index.d.ts").ValidationIssue[]} issues
+ * @returns {string}
+ */
+export function repairPrompt(schema, issues) {
+  const bulletList = issues.map((issue) => `- ${issue.path}: ${issue.message}`).join("\n");
+  return [
+    "Fix the JSON so it matches the schema.",
+    "Return only the corrected JSON.",
+    brief(schema, { includeDescriptions: true }),
+    "Validation errors:",
+    bulletList
+  ].join("\n");
+}
+
+function describeSchema(schema, context) {
+  if (context.depth > context.maxDepth) {
+    return "...";
+  }
+
+  if ("const" in schema) {
+    return JSON.stringify(schema.const);
+  }
+
+  if (Array.isArray(schema.enum)) {
+    return schema.enum.map((item) => JSON.stringify(item)).join(" | ");
+  }
+
+  const type = normalizeType(schema);
+
+  if (Array.isArray(type)) {
+    return type.join(" | ");
+  }
+
+  if (type === "object" || schema.properties) {
+    const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+    const props = Object.entries(schema.properties ?? {}).map(([key, child]) => {
+      const suffix = required.has(key) ? "" : "?";
+      return `${key}${suffix}: ${describeSchema(child, nextContext(context))}`;
+    });
+
+    if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+      props.push(`[key: string]: ${describeSchema(schema.additionalProperties, nextContext(context))}`);
+    } else if (schema.additionalProperties === true) {
+      props.push("[key: string]: unknown");
+    }
+
+    return `{ ${props.join("; ")} }`;
+  }
+
+  if (type === "array" || schema.items) {
+    const item = schema.items && !Array.isArray(schema.items)
+      ? describeSchema(schema.items, nextContext(context))
+      : "unknown";
+    const range = formatRange(schema.minItems, schema.maxItems, "items");
+    return `Array<${item}>${range}`;
+  }
+
+  if (type === "string") {
+    const parts = ["string"];
+    if (schema.format) parts.push(`format:${schema.format}`);
+    if (schema.pattern) parts.push(`/${schema.pattern}/`);
+    const range = formatRange(schema.minLength, schema.maxLength, "chars");
+    return `${parts.join(" ")}${range}`;
+  }
+
+  if (type === "number" || type === "integer") {
+    const range = formatRange(schema.minimum, schema.maximum, "");
+    return `${type}${range}`;
+  }
+
+  return type ?? "unknown";
+}
+
+function collectDescriptions(schema, path = "$", notes = []) {
+  if (typeof schema.description === "string" && schema.description.trim()) {
+    notes.push({ path, description: schema.description.trim() });
+  }
+
+  if (schema.properties) {
+    for (const [key, child] of Object.entries(schema.properties)) {
+      collectDescriptions(child, `${path}.${key}`, notes);
+    }
+  }
+
+  if (schema.items && !Array.isArray(schema.items)) {
+    collectDescriptions(schema.items, `${path}[]`, notes);
+  }
+
+  if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+    collectDescriptions(schema.additionalProperties, `${path}.*`, notes);
+  }
+
+  return notes;
+}
+
+function visit(schema, value, path, issues, depth) {
+  if (depth > DEFAULT_MAX_DEPTH * 4) {
+    issues.push(issue(path, "max_depth", "Value is too deeply nested"));
+    return;
+  }
+
+  if ("const" in schema && !sameJson(schema.const, value)) {
+    issues.push(issue(path, "const", `Expected ${stableStringify(schema.const)}`));
+    return;
+  }
+
+  if (Array.isArray(schema.enum) && !schema.enum.some((item) => sameJson(item, value))) {
+    issues.push(issue(path, "enum", `Expected one of ${schema.enum.map(stableStringify).join(", ")}`));
+    return;
+  }
+
+  const expected = normalizeType(schema);
+  if (expected && !matchesType(expected, value)) {
+    issues.push(issue(path, "type", `Expected ${Array.isArray(expected) ? expected.join(" or ") : expected}`));
+    return;
+  }
+
+  const type = Array.isArray(expected) ? inferType(value) : expected ?? inferType(value);
+
+  if (type === "object" && value !== null && !Array.isArray(value) && typeof value === "object") {
+    validateObject(schema, value, path, issues, depth);
+  }
+
+  if (type === "array" && Array.isArray(value)) {
+    validateArray(schema, value, path, issues, depth);
+  }
+
+  if (type === "string" && typeof value === "string") {
+    validateString(schema, value, path, issues);
+  }
+
+  if ((type === "number" || type === "integer") && typeof value === "number") {
+    validateNumber(schema, value, path, issues);
+  }
+}
+
+function validateObject(schema, value, path, issues, depth) {
+  const props = schema.properties ?? {};
+  const required = Array.isArray(schema.required) ? schema.required : [];
+
+  for (const key of required) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) {
+      issues.push(issue(`${path}.${key}`, "required", "Required property is missing"));
+    }
+  }
+
+  for (const [key, childValue] of Object.entries(value)) {
+    if (props[key]) {
+      visit(props[key], childValue, `${path}.${key}`, issues, depth + 1);
+      continue;
+    }
+
+    if (schema.additionalProperties === false) {
+      issues.push(issue(`${path}.${key}`, "additional_property", "Additional property is not allowed"));
+    } else if (schema.additionalProperties && typeof schema.additionalProperties === "object") {
+      visit(schema.additionalProperties, childValue, `${path}.${key}`, issues, depth + 1);
+    }
+  }
+}
+
+function validateArray(schema, value, path, issues, depth) {
+  if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+    issues.push(issue(path, "min_items", `Expected at least ${schema.minItems} items`));
+  }
+
+  if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+    issues.push(issue(path, "max_items", `Expected at most ${schema.maxItems} items`));
+  }
+
+  if (schema.items && !Array.isArray(schema.items)) {
+    value.forEach((itemValue, index) => {
+      visit(schema.items, itemValue, `${path}[${index}]`, issues, depth + 1);
+    });
+  }
+}
+
+function validateString(schema, value, path, issues) {
+  if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+    issues.push(issue(path, "min_length", `Expected at least ${schema.minLength} characters`));
+  }
+
+  if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+    issues.push(issue(path, "max_length", `Expected at most ${schema.maxLength} characters`));
+  }
+
+  if (typeof schema.pattern === "string") {
+    const pattern = new RegExp(schema.pattern);
+    if (!pattern.test(value)) {
+      issues.push(issue(path, "pattern", `Expected string to match /${schema.pattern}/`));
+    }
+  }
+}
+
+function validateNumber(schema, value, path, issues) {
+  if (!Number.isFinite(value)) {
+    issues.push(issue(path, "finite", "Expected a finite number"));
+  }
+
+  if (schema.type === "integer" && !Number.isInteger(value)) {
+    issues.push(issue(path, "integer", "Expected an integer"));
+  }
+
+  if (typeof schema.minimum === "number" && value < schema.minimum) {
+    issues.push(issue(path, "minimum", `Expected value >= ${schema.minimum}`));
+  }
+
+  if (typeof schema.maximum === "number" && value > schema.maximum) {
+    issues.push(issue(path, "maximum", `Expected value <= ${schema.maximum}`));
+  }
+}
+
+function normalizeType(schema) {
+  if (schema.type) return schema.type;
+  if (schema.properties) return "object";
+  if (schema.items) return "array";
+  if (typeof schema.const === "string") return "string";
+  if (typeof schema.const === "number") return Number.isInteger(schema.const) ? "integer" : "number";
+  if (typeof schema.const === "boolean") return "boolean";
+  if (schema.const === null) return "null";
+  return undefined;
+}
+
+function matchesType(expected, value) {
+  const actual = inferType(value);
+  if (Array.isArray(expected)) {
+    return expected.some((item) => matchesType(item, value));
+  }
+  return actual === expected || (expected === "number" && actual === "integer");
+}
+
+function inferType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  return typeof value;
+}
+
+function issue(path, code, message) {
+  return { path, code, message };
+}
+
+function nextContext(context) {
+  return { depth: context.depth + 1, maxDepth: context.maxDepth };
+}
+
+function formatRange(min, max, unit) {
+  const label = unit ? ` ${unit}` : "";
+  if (typeof min === "number" && typeof max === "number") return ` (${min}-${max}${label})`;
+  if (typeof min === "number") return ` (>=${min}${label})`;
+  if (typeof max === "number") return ` (<=${max}${label})`;
+  return "";
+}
+
+function sameJson(a, b) {
+  return stableStringify(a) === stableStringify(b);
+}
+
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(",")}]`;
+  }
+
+  const entries = Object.entries(value).sort(([a], [b]) => a.localeCompare(b));
+  return `{${entries.map(([key, child]) => `${JSON.stringify(key)}:${stableStringify(child)}`).join(",")}}`;
+}
+
+function firstJsonSlice(source) {
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    if (char !== "{" && char !== "[") continue;
+
+    const close = char === "{" ? "}" : "]";
+    const stack = [close];
+    let inString = false;
+    let escaped = false;
+
+    for (let cursor = index + 1; cursor < source.length; cursor += 1) {
+      const current = source[cursor];
+
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+
+      if (current === "\\") {
+        escaped = inString;
+        continue;
+      }
+
+      if (current === "\"") {
+        inString = !inString;
+        continue;
+      }
+
+      if (inString) continue;
+
+      if (current === "{" || current === "[") {
+        stack.push(current === "{" ? "}" : "]");
+      } else if (current === "}" || current === "]") {
+        if (current !== stack.pop()) break;
+        if (stack.length === 0) {
+          return source.slice(index, cursor + 1);
+        }
+      }
+    }
+  }
+
+  return "";
+}