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
| Thing | How |
|---|---|
| Integers, floats, booleans, strings | Native Python types |
| ISO 8601 dates / datetimes | Regex match (2024-01-15, 2024-01-15T10:30:00Z) |
| Numeric strings, boolean strings | Pattern matching on string values |
| Nullable fields | Counts null, missing keys, and empty strings |
| Mixed types | Flags when a field contains more than one type |
| Nested JSON | Flattens to dot-notation (user.address.city) |
| JSON arrays | Handles root arrays, wrapped arrays (data, results, items) |
| NDJSON / JSON Lines | Auto-detected line-by-line |
| CSV dialect | Auto-sniffed (comma, tab, pipe, etc.) |
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file sniff_schema-0.1.3.tar.gz.
File metadata
- Download URL: sniff_schema-0.1.3.tar.gz
- Upload date:
- Size: 99.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f8fd070e797650a456ccf430da31a4718583f5b3094f1e79df9d4859617bac3f
|
|
| MD5 |
166f48c6dadb6c5fd2a493d583c4d0ce
|
|
| BLAKE2b-256 |
b6bd0a540e9dc7bef9b090988d3350094be97c670e530431032c233f1a9a4ac3
|
Provenance
The following attestation bundles were made for sniff_schema-0.1.3.tar.gz:
Publisher:
publish.yml on gitwingo/sniff-schema
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
sniff_schema-0.1.3.tar.gz -
Subject digest:
f8fd070e797650a456ccf430da31a4718583f5b3094f1e79df9d4859617bac3f - Sigstore transparency entry: 1432181333
- Sigstore integration time:
-
Permalink:
gitwingo/sniff-schema@ce826cbe48ae67485cd9e12ee171e97cd5ca0811 -
Branch / Tag:
refs/tags/v0.1.3 - Owner: https://github.com/gitwingo
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@ce826cbe48ae67485cd9e12ee171e97cd5ca0811 -
Trigger Event:
release
-
Statement type:
File details
Details for the file sniff_schema-0.1.3-py3-none-any.whl.
File metadata
- Download URL: sniff_schema-0.1.3-py3-none-any.whl
- Upload date:
- Size: 8.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
193b3a9accf302bb6f90145a0f34a247e8953639c100d59087deb7f4cdf3fba5
|
|
| MD5 |
87f20fbb2a9218ba4bdc972ffe028605
|
|
| BLAKE2b-256 |
a91ed33adb7b2df63020abd53066f55e753e6a5804259b97f02844608ef45b06
|
Provenance
The following attestation bundles were made for sniff_schema-0.1.3-py3-none-any.whl:
Publisher:
publish.yml on gitwingo/sniff-schema
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
sniff_schema-0.1.3-py3-none-any.whl -
Subject digest:
193b3a9accf302bb6f90145a0f34a247e8953639c100d59087deb7f4cdf3fba5 - Sigstore transparency entry: 1432181655
- Sigstore integration time:
-
Permalink:
gitwingo/sniff-schema@ce826cbe48ae67485cd9e12ee171e97cd5ca0811 -
Branch / Tag:
refs/tags/v0.1.3 - Owner: https://github.com/gitwingo
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@ce826cbe48ae67485cd9e12ee171e97cd5ca0811 -
Trigger Event:
release
-
Statement type:
