| name | schema-from-samples |
| description | Given multiple samples of the same document type (e.g. five different invoices), infer a unified JSON schema covering every variable field across all samples. Use when the user wants to design a robust template that handles real-world variation rather than a single example. |
schema-from-samples
Single-sample ingestion can miss optional fields, edge-case formats, and variation that only appears in some documents. This skill takes multiple samples of the same document type and produces a union schema that covers all of them.
When to use
Auto-trigger when the user:
- Provides several sample documents of the same kind ("here are last quarter's invoices").
- Asks to "infer a schema", "design a template that handles all our variations", or similar.
- Has already run
ingest-document-sample once and wants to harden the schema with more samples.
Inputs
- Sample directory or file list — at least 2, ideally 5+.
- Document type — what they are (invoice, statement, etc.).
- Existing schema (optional) — if they already have one, refine it rather than starting fresh.
Approach
- Parse each sample — same approach as
ingest-document-sample (PDF/image/DOCX read).
- Extract field set per sample — for each sample, list the fields present, their types, and whether they're scalar/array/object.
- Union the field sets — every field that appears in any sample becomes part of the schema.
- Mark required vs optional — required only if it appears in all samples; otherwise optional.
- Detect type variation — if
discount is a number in some and a string in others, flag it. The user must decide which is canonical.
- Detect format variation — date formats (
2026-04-27 vs 27/04/26), currency formatting, decimal separators. Normalise to a single canonical representation in the schema and document the variations seen.
- Detect repeating-row variation — the maximum and minimum row counts seen, and any rows with extra fields.
Output
<output-dir>/
├── schema.json # unified JSON Schema
├── field-coverage.md # which samples had which fields, type variations seen
└── normalisation-notes.md # date/currency/format decisions and recommendations
Hand-off
After producing the unified schema, suggest the user run ingest-document-sample (or new-typst-template) against the canonical sample using this schema as the contract — that gives them a template that handles real-world variation.
Storage rules
User-owned outputs go to a user-chosen path. Plugin may cache the analysis under $CLAUDE_USER_DATA_ROOT/cache/schema-analysis/ (resolve via ${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/programmatic-doc-generation/).
