sniff-schema

Infer schema from any JSON or CSV — instantly output as TypeScript, Pydantic, or Markdown.

You get a JSON file or CSV from an API, a colleague, or a legacy system. No docs. No types. Just raw data. sniff-schema reads it and tells you exactly what's in it — field names, types, nullability, null percentages, and sample values — then outputs a ready-to-use TypeScript interface or Pydantic model.

No LLM. No cloud. No auth. Pure local analysis.

Install

pip install sniff-schema

Or run directly without installing:

pip install httpx "rich>=13" "typer>=0.12"
python sniff_schema.py data.json

Usage

# Rich terminal table (default)
sniff-schema data.json

# TypeScript interface
sniff-schema data.json --format typescript

# Pydantic v2 model
sniff-schema data.json --format pydantic

# Markdown table — save to file
sniff-schema data.json --format markdown --output schema.md

# Pipe directly from curl
curl https://api.example.com/users | sniff-schema - --format typescript

# CSV works too
sniff-schema report.csv --format pydantic

# Large files — sample just 100 rows
sniff-schema big_dataset.csv --sample 100

What it detects

Output formats

--format typescript

interface InferredSchema {
  id: number;
  name: string;
  age?: number | null;
  email?: string | null;
  score?: number | null;
  active: boolean;
  created_at: string;
  country: string;
  notes?: string | null;
}

// Inferred from 5 record(s)

--format pydantic

from pydantic import BaseModel
from typing import Optional


class InferredSchema(BaseModel):
    id: int
    name: str
    age: Optional[int] = None
    email: Optional[str] = None
    score: Optional[float] = None
    active: bool
    created_at: str
    country: str
    notes: Optional[str] = None

# Inferred from 5 record(s)

--format markdown

Outputs a GitHub-flavored Markdown table — paste directly into your wiki, Notion, or PR description.

All options

Arguments:
  SOURCE     Path to JSON/CSV file, or '-' to read from stdin.

Options:
  -f, --format   [table|typescript|pydantic|markdown]  Output format (default: table)
  -s, --sample   Max records to sample (default: 200, max: 100000)
  -o, --output   Write output to a file instead of stdout
  --help         Show this message and exit.

Development

git clone https://github.com/gitwingo/sniff-schema
cd sniff-schema
pip install -e ".[dev]"

Support

If sniff-schema has been useful to you, consider supporting its development:

Connect

• GitHub: @gitwingo
• Reddit: u/gitwingo
• X / Twitter: @gitwingo

License

MIT © gitwingo