Rendered from specs/F06-inference.md — edit it there, not here.

estimate8 ptsL16–32 hSchema inference with refinement passes — sized by its band. Advisory only — estimated by the project's AI coding agent (Claude Code) on 2026-07-20 from the implementation (2057 LOC across 3 files); not part of the maturity score. Rubric: S13.

value10.6 valueModerateRICE 1.32UNIQUE reach 3 (20–50% of users) · impact 4 (removes a manual workflow) · confidence 0.8 (domain-reasoned) Bootstrapping a schema from existing data removes an entire manual authoring session; used occasionally but decisively when it is. Advisory only — a judgement about worth, not a measurement, estimated by the project's AI coding agent (Claude Code) on 2026-07-25; not part of the maturity score. RICE divides this score by the S13 effort estimate (8 pts). Rubric: S16.

F06 — Schema Inference from Data Files

Overview

The extension can generate a draft JSON Schema from an existing JSON, JSONC, JSONL, or YAML data file using the genson-js library.

User Stories

• As a developer starting from existing data, I want to generate a schema automatically rather than writing it from scratch.
• As a team lead adopting schema-first workflows, I want a starting schema I can refine and commit alongside the data.

Functional Requirements

Command

• F06-FR-01 The command jsonschema.inferSchema MUST be available in the Command Palette.
• F06-FR-02 The Generate Schema toolbar icon (wand) MUST appear whenever jsonschema.isJsonSchema is false (data files, not schema files), regardless of whether the file already has a schema bound (inline $schema, a settings binding, or a natively-resolved schema per F04-FR-15). An earlier revision also hid the icon whenever any of those was present, on the theory that generating a schema from a file that already has one is pointless; in practice there is no reliable way to draw that line — an existing binding (of any kind, including a natively-resolved one like a Helm chart's values.schema.json) is not proof the user never wants to (re)generate a starting point from the file's current data — so the icon is never hidden on that basis.

Parsing

• F06-FR-03 JSON files MUST be parsed with JSON.parse.
• F06-FR-04 JSONC files MUST have comments stripped before parsing.
• F06-FR-05 JSONL files MUST be parsed as an array (one JSON object per line).
• F06-FR-06 YAML / YML files MUST be parsed with the yaml package.
• F06-FR-07 A parse error MUST show an error notification with the error message and MUST NOT proceed.

Generation

• F06-FR-08 The inferred schema MUST be produced by genson-js's createSchema function.
• F06-FR-09 The generated schema MUST include "$schema": "http://json-schema.org/draft-07/schema#".
• F06-FR-10 The generated schema MUST be pretty-printed (2-space indentation).

Output

• F06-FR-11 The generated schema MUST be opened in a new untitled document with languageId: "json" in ViewColumn.Beside.
• F06-FR-12 A notification MUST inform the user to save and bind the schema to use it for validation.

Semantic enrichment

• F06-FR-13 After structural inference, the generator MUST run a deterministic enrichment pass over the observed values, adding a format to a string property when every observed value at that path matches one well-known format (email, uri, date-time, date, uuid, ipv4), and never when even one value does not. Structural inference alone says type: string for an e-mail address; the format is what makes the inferred schema catch a malformed one.
• F06-FR-14 The pass MUST add an enum to a string property when the path has been observed enough times (at least 4) to make a closed set plausible, the distinct values are few (at most 5), and they repeat (distinct ÷ observed ≤ 0.5). It MUST NOT infer an enum from a single document, where every value is trivially unique — that would freeze first-seen data into a contract.
• F06-FR-15 Enrichment MUST be additive and pure: it MUST NOT remove, rename or retype anything the structural pass produced, MUST produce identical output for identical input, and MUST be skippable (--plain in the CLI). The optional model-assisted pass (F32-FR-10) builds on this deterministic one, never replaces it.

Acceptance Criteria

1. Running Generate Schema from This File on person-valid.json opens a new editor tab containing valid JSON with a $schema field and at least the top-level property types inferred from the data.
2. Running the command on a malformed JSON file shows an error notification.

History

• 2026-09-02 — Added F06-FR-13/14/15: a deterministic enrichment pass after structural inference — format when every observed value matches, enum when a path repeats a small closed set across enough observations. Additive, pure and skippable; the model-assisted pass in F32 builds on it rather than replacing it.

Requirement traceability

Status of each requirement in specs/traceability.json. Test coverage is auto-discovered from [ID] tags in test titles and is not listed here.

Requirement	Status	Implementation	Note
F06-FR-01	implemented	package.json	inferSchema in commandPalette
F06-FR-02	implemented	package.json, src/SchemaBindingManager.ts	inferSchema editor/title icon, gated only on !isJsonSchema; never hidden for an existing binding
F06-FR-03	implemented	src/extension.ts	inferSchema: JSON.parse path (unit-tested)
F06-FR-04	implemented	src/extension.ts	inferSchema: JSONC strip (unit-tested)
F06-FR-05	implemented	src/extension.ts	inferSchema: JSONL array (unit-tested)
F06-FR-06	implemented	src/extension.ts	inferSchema: YAML parse (unit-tested)
F06-FR-07	implemented	src/extension.ts	inferSchema: parse-error notification (unit-tested)
F06-FR-08	implemented	src/extension.ts	inferSchema: createSchema (unit-tested)
F06-FR-09	implemented	src/extension.ts	inferSchema: draft-07 $schema (unit-tested)
F06-FR-10	implemented	src/extension.ts	inferSchema: pretty-printed (unit-tested)
F06-FR-11	implemented	src/extension.ts	inferSchema: opens json Beside (unit-tested)
F06-FR-12	implemented	src/extension.ts	inferSchema: bind hint notification (unit-tested)
F06-FR-13	implemented	src/inferenceEnrich.ts, src/extension.ts, src/cli/cli.ts	deterministic format/enum enrichment after genson inference; pure, additive (property-tested), --plain in the CLI
F06-FR-14	implemented	src/inferenceEnrich.ts, src/extension.ts, src/cli/cli.ts	deterministic format/enum enrichment after genson inference; pure, additive (property-tested), --plain in the CLI
F06-FR-15	implemented	src/inferenceEnrich.ts, src/extension.ts, src/cli/cli.ts	deterministic format/enum enrichment after genson inference; pure, additive (property-tested), --plain in the CLI

Documented in

Documentation sections tagged spec:F06 (or one of its requirement ids) — 454 of ~518 expected words (88%). The expectation comes from this spec's evaluated complexity of 12.9 (15 documentable requirements — 15 FR — weighted by kind and by each definition's length).

• JSON Schema PreviewREADME.md · 70 words
• GenerateREADME.md · 78 words
• Quick fixes for validation errors/guide/commands · 130 words
• AI commands/guide/commands · 143 words
• Introduction/guide/ · 33 words

Changes over time

• d152a832026-09-02feat: finish the analysis follow-ups — inference enrichment, MCP distribution, quiet confirmations
• 3a71cdc2026-07-23fix(binding): never hide the Generate Schema wand for an existing binding
• 13edbff2026-07-16fix(binding): recognise auto bindings and refine schema affordances
• ac906af2026-06-23docs(specs): add software requirements specification