Rendered from specs/F03-validation.md — edit it there, not here.

estimate8 ptsL16–32 hCore ajv validation with AST-exact instance location across JSON/YAML — sized by its band. Advisory only — estimated by the project's AI coding agent (Claude Code) on 2026-07-20 from the implementation (1813 LOC across 4 files); not part of the maturity score. Rubric: S13.

value27.5 valueCriticalRICE 3.44ZEROCONF reach 5 (over 80% of users) · impact 5 (a reason to install) · confidence 1.0 (stated purpose) Co-headline capability and the one that runs passively on every open file — the extension earns its keep here without the user asking. 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.

F03 — JSON / YAML Validation

Overview

The extension validates JSON and YAML data files against a JSON Schema using AJV. Errors are reported as VS Code diagnostics in the Problems panel.

User Stories

• As a developer, I want to validate a data file against its schema so I can catch errors without running the application.
• As a CI engineer, I want validation errors surfaced as Problems so they are visible in VS Code's native UX.

Functional Requirements

Schema Resolution

• F03-FR-01 When the active file has an inline $schema field the extension MUST use that URL/path as the schema without requiring an explicit binding.
• F03-FR-02 When no inline $schema is present the extension MUST look up the bound schema via the workspace's json.schemas / yaml.schemas settings.
• F03-FR-03 Remote schema URLs MUST be fetched using stored authentication credentials when available (see F07).
• F03-FR-16 When the file has neither an inline $schema (F03-FR-01) nor a settings binding (F03-FR-02) but VS Code resolves a schema for it natively (an installed extension's contributes.jsonValidation, or a SchemaStore/user catalog entry — the same auto state the status bar shows per F04-FR-15), the validator MUST use that natively-resolved schema URL rather than report "No schema bound". The file is already schema-backed, so validation MUST recognise the auto binding and validate against it.
• F03-FR-17 Validation MAY be re-run automatically when a bound data file is saved, governed by jsonschema.validation.onSave (default off; bound re-validates a file that already has a resolved binding, always also re-validates one whose binding resolves natively per F03-FR-16). Automatic runs MUST be silent — diagnostics only, no notification — and MUST NOT fetch a remote schema that is not already cached (F08), so saving never blocks on the network. This closes the gap for YAML, TOML, JSONL and authenticated schemas, which VS Code's own language servers do not validate live.

Validation Execution

• F03-FR-04 The command jsonschema.validateFile MUST run AJV against the resolved schema and the current file's content.
• F03-FR-05 Validation MUST support JSON, JSONC, JSONL, YAML, and YML file formats.
• F03-FR-06 JSONC files MUST have comments stripped before parsing.
• F03-FR-07 JSONL files MUST be validated as an array of records (one per line).
• F03-FR-14 A resolved schema document MUST be parsed according to its own source format, not assumed to be JSON: when the schema path/URL ends in .yaml/.yml it MUST be parsed as YAML (a remote copy is parsed by the original URL's extension, per F13-FR-06). This keeps the validator consistent with the other schema consumers (SchemaRefProvider, SchemaBundleCommand), which already resolve a schema document via languageForSchemaSource + parseSchemaText; loading a YAML-format schema MUST NOT fail with a JSON parse error.
• F03-FR-15 The validator MUST select the AJV dialect matching the schema's declared $schema: a $schema naming JSON Schema 2020-12 MUST use Ajv2020, one naming 2019-09 MUST use Ajv2019, and any other value (draft-07/06/04) or an absent $schema MUST use the default draft-07 Ajv. This ensures draft-specific keywords — 2020-12's prefixItems and $dynamicRef/$dynamicAnchor, and 2019-09/2020-12's unevaluatedProperties /unevaluatedItems — are enforced rather than silently ignored under a single draft-07 dialect (strict: false otherwise drops unknown keywords without error). Draft selection MUST be a pure, unit-testable function of the schema's $schema string. (This applies to on-demand jsonschema.validateFile; F16's sample-data self-check deliberately strips $schema and stays on the default dialect — see F16.)

Diagnostics

• F03-FR-08 Each AJV validation error MUST be mapped to a VS Code Diagnostic with the correct range (line and column), message, and source set to "JSON Schema".
• F03-FR-09 All diagnostics MUST be published to a dedicated DiagnosticCollection and cleared on the next validation run for the same file.
• F03-FR-10 When validation passes with no errors the Problems panel MUST show zero diagnostics for the file and the extension MUST show a success notification.

Error Handling

• F03-FR-11 If the schema cannot be resolved (file not found, HTTP error, auth required) the extension MUST show an error message identifying the cause.
• F03-FR-12 If the auth flow returns 401/403 the error message MUST offer a Configure Auth button that opens jsonschema.configureSchemaAuth.

Toolbar

• F03-FR-13 The Validate toolbar icon MUST appear only when jsonschema.isJsonSchema is false (i.e. for data files, not schema files).

Acceptance Criteria

1. Opening person-invalid.json (a file that violates its schema) and running Validate This File produces one or more diagnostics in the Problems panel.
2. Opening person-valid.json and validating produces zero diagnostics and a success notification.
3. Validation works without an explicit binding when $schema is present inline.

History

• 2026-09-02 — Added F03-FR-17: opt-in re-validation on save (jsonschema.validation.onSave, default off). Automatic runs are silent and never fetch an uncached remote schema, so saving is never blocked on the network. This closes the live-validation gap for YAML, TOML, JSONL and authenticated schemas, which VS Code's own language servers leave open.

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
F03-FR-01	implemented	src/ValidationManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F03-FR-02	implemented	src/ValidationManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F03-FR-03	implemented	src/ValidationManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F03-FR-04	implemented	src/ValidationManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F03-FR-05	implemented	src/ValidationManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F03-FR-06	implemented	src/ValidationManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F03-FR-07	implemented	src/ValidationManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F03-FR-08	implemented	src/ValidationManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F03-FR-09	implemented	src/ValidationManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F03-FR-10	implemented	src/ValidationManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F03-FR-11	implemented	src/ValidationManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F03-FR-12	implemented	src/ValidationManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F03-FR-13	implemented	src/ValidationManager.ts	unit-tested via the vscode mock (2026-07 coverage expansion)
F03-FR-14	implemented	src/ValidationManager.ts	loadSchema parses a schema document by its source format (parseSchema -> languageForSchemaSource + parseSchemaText); unit-tested for YAML-format schema load and a non-parsing schema, and exercised end-to-end by the S08 YAML settings-scope suite
F03-FR-15	implemented	src/ajvFactory.ts, src/ValidationManager.ts	createAjv selects Ajv2020/Ajv2019/draft-07 Ajv by the schema's $schema; pure draftOf() and createAjv() unit-tested plus an end-to-end validateFile test proving a 2020-12 prefixItems keyword is enforced. sampleDataGenerator deliberately stays on the default dialect (strips $schema for a self-check, see F16)
F03-FR-16	implemented	src/ValidationManager.ts, src/SchemaBindingManager.ts, src/extension.ts	validateCurrentFile falls back to bindingManager.detectNativeSchema(doc).url (F04-FR-15) when there is no inline/settings binding, so auto-bound files validate instead of reporting 'no schema bound' (unit-tested)
F03-FR-17	manual	src/extension.ts, src/ValidationManager.ts, package.json	save-triggered silent validation; the silent option and the setting are unit-tested

Documented in

Documentation sections tagged spec:F03 (or one of its requirement ids) — 354 of ~639 expected words (55%). The expectation comes from this spec's evaluated complexity of 16 (17 documentable requirements — 17 FR — weighted by kind and by each definition's length).

• CheckREADME.md · 100 words
• JSON Schema: Bind Schema…/guide/commands · 121 words
• TOML Schema IntelliSense/guide/configuration · 100 words
• Introduction/guide/ · 33 words

Changes over time

• 56cbbde2026-09-02feat(specs): schema tests, refactorings, outline, agent tools & AI authoring
• 13edbff2026-07-16fix(binding): recognise auto bindings and refine schema affordances
• a9f3dc82026-07-10fix(validation): select AJV dialect by the schema's declared draft (F03-FR-15)
• df250472026-07-07fix(S08): green the integration suite — real bugs the first CI run surfaced
• ac906af2026-06-23docs(specs): add software requirements specification