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

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.

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.

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)