JSON Schema Validation Guide for Windows Developers: Contracts, Errors, and Versioned APIs

Overview

JSON syntax validation and JSON Schema validation are related, but they are not the same task. A JSON formatter or beautifier can tell you whether braces, commas, strings, and values form valid JSON. A JSON Schema validator goes further: it checks whether the document has the expected properties, data types, formats, allowed values, and nesting.

For example, this document is valid JSON:

{
  "id": "A-104",
  "active": "yes"
}

It may still fail a schema that requires id to be a string and active to be a Boolean. That distinction matters when an API contract is shared across teams or when a configuration file is consumed by automation.

A practical Windows workflow usually has four layers:

1. Format and parse: confirm that the input is syntactically valid JSON.
2. Validate locally: run the document against its schema in an IDE, browser-based validator, or local command.
3. Validate in automation: add the same check to tests or continuous integration so it is not dependent on a developer remembering a manual step.
4. Review the contract: confirm that the schema itself reflects the intended API or configuration behavior.

Browser-based JSON Schema validators are convenient for a quick inspection, but do not paste credentials, personal data, production payloads, private tokens, or proprietary configuration into an online tool unless your organization permits it. For sensitive data, use a local validator or a sanitized sample.

Checklist by scenario

Scenario 1: Quick validation with an online tool

1. Open a JSON Schema validator that lets you provide both the schema and the JSON instance.
2. Paste the schema into the schema panel and the payload into the instance panel.
3. Check that the tool identifies the schema draft used by the document, or select the matching draft if the tool requires it.
4. Run validation and read the first error together with its property path.
5. Correct the input, then run validation again rather than assuming that one fix resolved every error.
6. Copy the final schema and sample into your project or test fixture instead of treating the browser session as the source of record.

This is useful when reviewing a new contract, explaining a failure to a teammate, or checking a small fixture before committing it. It is not a replacement for an automated test.

Scenario 2: Local validation from Windows

For repeatable work, use a validator installed with the project. A Node.js project can use the Ajv library, subject to the package version and JSON Schema draft it supports. A minimal script can look like this:

const fs = require('node:fs');
const Ajv = require('ajv');

const schema = JSON.parse(fs.readFileSync('schema.json', 'utf8'));
const data = JSON.parse(fs.readFileSync('payload.json', 'utf8'));

const ajv = new Ajv();
const validate = ajv.compile(schema);
const valid = validate(data);

if (!valid) {
  console.error(JSON.stringify(validate.errors, null, 2));
  process.exit(1);
}

console.log('Valid');

Keep the schema, sample payload, validator configuration, and package lock file under version control. If the schema uses newer features or formats, confirm the validator's compatibility before relying on the result. A local script is especially appropriate for private data and for checks that must produce the same result on every Windows workstation and build agent.

Scenario 3: PowerShell inspection before schema validation

PowerShell can quickly confirm that a file is parseable JSON:

$payload = Get-Content .\payload.json -Raw | ConvertFrom-Json
$payload | ConvertTo-Json -Depth 20

This does not replace JSON Schema validation. It is a useful first check that separates malformed JSON from a structurally valid document that violates the contract. If parsing fails, fix the JSON syntax first; otherwise, schema error messages can be misleading or unavailable.

For broader Windows setup guidance, see the Windows Developer Environment Setup Guide and the PowerShell command reference.

Scenario 4: API contract and CI checks

For an API, validate representative request and response fixtures rather than only one hand-written example. Include success responses, missing required properties, wrong data types, empty collections, and boundary values. Make the validation command return a nonzero exit code when a fixture fails so the build can stop before an incompatible contract is released.

Pair schema checks with actual endpoint tests. A response can satisfy a schema while still using the wrong status code, authorization behavior, or business value. The Windows API Testing Toolkit provides related guidance for REST clients, JSON utilities, JWT inspection, and cURL workflows.

What to double-check

When comparing drafts, treat the schema's declared version and the validator's supported version as a pair. Common projects may still contain schemas from Draft-04, Draft-06, Draft-07, 2019-09, or 2020-12, but support is not uniform across editors, browser tools, libraries, and API platforms. Do not change the draft declaration merely to silence an error; first determine whether the schema actually uses draft-specific keywords or behavior.

Common mistakes

• Validating only syntax: A formatter confirms parseability, not compliance with the contract.
• Reading only the summary: Follow the error path, such as /customer/email, and compare the actual value with the relevant schema keyword.
• Assuming every keyword is enforced: Confirm support for formats, references, custom keywords, and the selected draft.
• Making every property required: Overly strict schemas can reject legitimate partial updates and future-compatible responses.
• Allowing everything by default: A schema that permits arbitrary properties may miss misspelled field names.
• Testing only a happy path: Add negative fixtures for missing fields, invalid types, unknown properties, and out-of-range values.
• Editing generated payloads by hand: Keep reproducible fixtures and record the command used to validate them.
• Sharing sensitive payloads online: Replace secrets and identifying values, or use a local validator.

When to revisit

Revisit this checklist whenever an API contract, configuration format, or test fixture changes. It is also worth reviewing before a release, after upgrading the validator or IDE extension, when moving checks between Windows and WSL2, and when a CI runner begins reporting different results from a local machine. The WSL2 development workflow guide can help when the same project uses both Windows and Linux-oriented tooling.

Use this short pre-release sequence:

1. Confirm the schema draft and validator version.
2. Parse the schema and every fixture as JSON.
3. Validate positive and negative examples.
4. Review changes to required fields, types, enums, references, and additional properties.
5. Run the exact validation command used by CI.
6. Document intentional breaking changes and update consumers or fixtures.

Keep this process close to the source files, not in a one-time browser session. Online developer tools are excellent for fast diagnosis; versioned local checks are what make JSON validation dependable over time.