JSON Schemas

JSON Schemas form Layer 2 of ModernizeSpec. They validate the file convention (Layer 1) and enable tooling, compliance checking, and editor support.

Schema Overview

Each core ModernizeSpec file has a corresponding JSON Schema:

File	Schema	Purpose
manifest.json	manifest.schema.json	Validates project metadata and file inventory
domains.json	domains.schema.json	Validates bounded contexts, entities, and context map
complexity.json	complexity.schema.json	Validates extraction tiers and hotspot data
extraction-plan.json	extraction-plan.schema.json	Validates phased extraction sequence
parity-tests.json	parity-tests.schema.json	Validates test suite inventory and acceptance thresholds
migration-state.json	migration-state.schema.json	Validates progress tracking and velocity data

Using Schemas

In Your Editor

Add a $schema reference at the top of your ModernizeSpec files to get autocomplete and validation in VS Code, JetBrains, and other JSON Schema-aware editors:

{
  "$schema": "https://modernizespec.dev/schemas/manifest.schema.json",
  "modernizespec": "0.1.0",
  "project": "MyProject"
}

With the CLI

The validate command checks all files against their schemas:

npx modernizespec validate

This reports typed validation errors — missing required fields, incorrect types, values outside allowed ranges.

With the SDK

import { ModernizeSpec } from "@modernizespec/sdk";

const spec = await ModernizeSpec.load("/path/to/project");
const errors = spec.validate();

if (errors.length > 0) {
  console.error("Validation errors:", errors);
}

In CI/CD

Add schema validation to your CI pipeline to ensure spec files stay valid as the project evolves:

# GitHub Actions example
- name: Validate ModernizeSpec
  run: npx modernizespec validate --strict

Schema Design Principles

Strict but Extensible

Required fields are minimal — enough to be useful without being burdensome. Optional fields provide depth for projects that need it. Unknown properties are allowed at the top level to support future extensions.

Self-Documenting

Every field includes a description in the schema, so editor tooltips explain what each property means without needing to check the documentation.

Versioned

Schemas are versioned alongside the specification. The modernizespec field in manifest.json declares which version of the spec the files conform to.

Schema Packages

Schemas are available through multiple channels:

npm Package

@modernizespec/schemas — importable JSON Schema files for Node.js projects

CDN

Hosted at https://modernizespec.dev/schemas/ — use $schema URLs directly

GitHub

Raw schema files in the specification repository

Next Steps

• manifest.json — Entry point schema details
• domains.json — Bounded context schema details
• Schema Validator — Interactive schema validation tool