schema-from-samples

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

1. Sample directory or file list — at least 2, ideally 5+.
2. Document type — what they are (invoice, statement, etc.).
3. Existing schema (optional) — if they already have one, refine it rather than starting fresh.

Approach

1. Parse each sample — same approach as ingest-document-sample (PDF/image/DOCX read).
2. Extract field set per sample — for each sample, list the fields present, their types, and whether they're scalar/array/object.
3. Union the field sets — every field that appears in any sample becomes part of the schema.
4. Mark required vs optional — required only if it appears in all samples; otherwise optional.
5. Detect type variation — if discount is a number in some and a string in others, flag it. The user must decide which is canonical.
6. 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.
7. 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/).