jsontoschema

Convert JSON to a simplified, human-readable schema. Types replace values, arrays collapse to one representative item, and optional fields get marked with ?.

Built for LLM prompts, API docs, and anywhere you need to describe JSON structure without the bulk of actual data.

Install

npm install @maisondigital/jsontoschema

Usage

Programmatic

import { convert } from "@maisondigital/jsontoschema";

const schema = convert({
  id: 1,
  name: "Alice",
  tags: ["admin", "user"],
  address: {
    city: "New York",
    zip: "10001",
  },
});

console.log(schema);
// {
//   id: number,
//   name: string,
//   tags: string[],
//   address: {
//     city: string,
//     zip: string
//   }
// }

From a JSON string

import { convertFromString } from "@maisondigital/jsontoschema";

const result = convertFromString('{"id": 1, "name": "Alice"}');

if (result.success) {
  console.log(result.schema);
} else {
  console.error(result.error);
}

With examples

Pass includeExamples: true to show observed values alongside types:

convert({ brand: "bmw", year: 2024 }, { includeExamples: true });
// {
//   brand: "bmw" | string,
//   year: 2024 | number
// }

Array merging

When an array contains objects, fields are merged into one representative item. Fields that don't appear in every item are marked optional:

convert([
  { id: 1, name: "Alice" },
  { id: 2, name: "Bob", role: "admin" },
]);
// [{
//   id: number,
//   name: string,
//   role?: string
// }]

Token estimation

import { estimateTokens } from "@maisondigital/jsontoschema";

estimateTokens(schemaString); // rough count (~4 chars/token)

CLI

# From a file
npx @maisondigital/jsontoschema data.json

# With examples
npx @maisondigital/jsontoschema data.json --examples

# Custom indent
npx @maisondigital/jsontoschema data.json --indent 4

# From stdin
cat data.json | npx @maisondigital/jsontoschema

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | includeExamples | boolean | false | Show observed values alongside types | | indent | number | 2 | Spaces per indentation level |

How it works

• Primitive values become their type: string, number, boolean, null
• Objects keep their keys, values become types
• Arrays of primitives become type[]
• Arrays of objects merge all items into one representative shape
• Fields missing from some array items become optional (key?)
• Mixed types become unions: string | number
• No depth limit, no recursive deduplication

Web tool

Try it in the browser at jsontoschema.com. Client-side only, your JSON never leaves the browser.

License

MIT