How department-of-veterans-affairs/vets-json-schema works
1. What this repository is
- vets-json-schema is a contract library for VA.gov forms and API payloads.
- Its primary artifact is a large set of JSON Schema files plus matching example payloads, consumed by vets-website and vets-api.
2. Source-of-truth layout
- The authoritative definitions live under src/schemas/<form-name>/schema.js.
- The checked-in dist/ directory is the built output that downstream projects actually consume.
- The repo is therefore split into authoring sources and published generated artifacts.
3. Schema-per-form architecture
- Most folders under src/schemas/ represent one form or endpoint contract, such as 21-526EZ, HLR-*, NOD-*, SC-*, 22-*, and others.
- Each schema is isolated by form/version, which keeps contracts stable and allows multiple versions of the same form to coexist.
4. Shared domain utilities
- Common, cross-schema data structures live in src/common/.
- These include reusable constants, definitions, address helpers, VA medical facility data, certification lists, and transformation helpers.
- This is the main internal boundary between generic schema logic and form-specific schema files.
5. Examples as first-class artifacts
- Many schemas have sibling example payloads in src/examples/ and in schema subfolders.
- Examples are not just documentation; they are validated against the schemas in tests and also emitted into dist/.
- Some forms include multiple examples such as simple, overflow, and kitchen_sink, showing expected payload variants and edge cases.
6. Build pipeline
- src/generate-schemas.js and src/start.js are the main entry points for producing the distributable assets.
- The build step compiles source schema modules into JSON files in dist/, including schema JSON, examples, helper definitions, and aggregate metadata files like schemas.js, definitions.json, and constants.json.
- The repo also includes a watch flow for rebuilding on source changes.
7. Generated distribution boundary
- Everything in dist/ is the published interface of the package.
- Downstream systems should treat dist/ as the consumable layer and src/ as implementation/source code.
- This is important for diagrams: the main dependency arrow points from vets-website and vets-api to dist/, not to raw source files.
8. Validation and test architecture
- Tests live under test/, with form-specific specs mirroring the schema structure.
- Shared test helpers under test/support/ validate schemas, examples, and common definitions consistently.
- There are broad “all schemas” and “all examples” tests, plus per-form tests for targeted contract coverage.
9. Language/runtime split
- The repo is primarily a Node/Yarn project for schema generation and validation.
- It also exposes a Ruby gem interface (lib/vets_json_schema.rb and vets_json_schema.gemspec) so Ruby consumers can bundle the generated schemas.
- This makes the package a cross-language contract artifact, not just a JavaScript library.
10. Consumer integration points
- The README explicitly describes how vets-website updates its schema dependency and how vets-api updates the gem dependency.
- That means the repo sits between frontend form validation and backend request validation as a shared source of truth.
11. Automation and quality gates
- GitHub Actions run build/test and security checks.
- Lint/format tooling is present via ESLint, Prettier, Babel, and standard Node version control (.nvmrc, script checks).
- The CI boundary matters because generated artifacts must stay in sync with sources before release.
12. How to read the architecture diagram
- Center: src/schemas plus src/common as the authoritative contract definitions.
- Left side: examples and tests validating those definitions.
- Right side: build pipeline emitting dist/ and gem/package artifacts.
- Downstream: vets-website and vets-api consume the generated schema outputs for form/data validation.
Main entry points: generate-schemas.js Schema build · src/schemas Form schemas · workflows CI workflows · test/schemas Schema tests
Components 19
Authoring source
Schema definitions and reusable source modules
- Form schemas · Per-form and per-endpoint JSON Schema sources
src/schemas - Shared defs · Reusable constants, helpers, definitions, and transforms
src/common - Source examples · Validated example payloads that mirror schema contracts
src/examples - Schema build · Build entry point that compiles source schemas into distributable artifacts
src/generate-schemas.js - Watch mode · Development flow for regenerating artifacts on source changes
src/watch.js - Start script · Runtime entry point for generating and publishing outputs
src/start.js
Published output
Generated artifacts consumed by downstream systems
- Dist schemas · Generated JSON Schema files consumed by downstream projects
dist - Dist examples · Generated example payloads alongside the published schemas
dist - Metadata files · Aggregate outputs such as schemas, definitions, constants, and facility data
dist
Validation and CI
Tests, helpers, and automation that keep contracts and generated output in sync
- Schema tests · Per-form specs that validate schemas and examples
test/schemas - Shared tests · Repository-wide checks for all schemas, examples, and definitions
test/common - Test support · Reusable fixtures and validation helpers for contract testing
test/support - CI workflows · GitHub Actions and repo checks for build, test, and security
.github/workflows
Package interfaces
Node and Ruby entry points used for generation and consumption
- Ruby gem · Ruby entry point exposing the generated schema bundle
lib/vets_json_schema.rb - Gem spec · Ruby package metadata for bundling the generated artifacts
vets_json_schema.gemspec - Node package · JavaScript package metadata and scripts for generation and validation
package.json - Usage docs · Consumer guidance for updating and using the package
README.md - vets-website · Downstream consumer of the published JSON schemas
- vets-api · Downstream consumer of the Ruby gem and published contracts
Connections 26
- Shared defs → Form schemas: shared definitions · Schemas import reusable structures and constants from the common layer
- Source examples → Form schemas: validate against · Example payloads are checked against their matching schemas
- Schema build → Dist schemas: emits · Build process writes the generated schema files into dist
- Schema build → Dist examples: emits · Build process publishes example payloads with the schemas
- Schema build → Metadata files: emits · Build process also generates aggregate metadata artifacts
- Form schemas → Schema build: inputs · Source schema modules are compiled by the generator
- Source examples → Schema build: inputs · Source examples are packaged into the distributable output
- Watch mode → Schema build: rebuilds · Watch mode reruns schema generation on file changes
- Start script → Schema build: runs · Start script invokes the generation pipeline
- Schema tests → Form schemas: covers · Per-form tests exercise the contract definitions
- Schema tests → Source examples: covers · Per-form tests validate example payloads against schemas
- Shared tests → Shared defs: covers · Shared tests verify reusable definitions and helper behavior
- Shared tests → Form schemas: covers · Broad tests validate all schemas consistently
- Test support → Schema tests: supports · Shared helpers provide schema/example validation utilities
- Test support → Shared tests: supports · Common test harness uses the shared fixtures and helpers
- CI workflows → Schema tests: runs · CI executes contract tests as a quality gate
- CI workflows → Shared tests: runs · CI executes repository-wide schema and example checks
- CI workflows → Schema build: verifies · CI ensures generated artifacts stay in sync with source
- Node package → Schema build: scripts · Package scripts drive generation and watch flows
- Node package → CI workflows: configures · Package tooling supports linting, formatting, and validation in automation
- Gem spec → Ruby gem: packages · Gem specification defines the Ruby consumer package
- Ruby gem → Dist schemas: bundles · Ruby interface exposes the generated schema artifacts
- Usage docs → vets-website: guides · Documentation describes how frontend consumers update dependencies
- Usage docs → vets-api: guides · Documentation describes how backend consumers update the gem dependency
- vets-website → Dist schemas: consumes · Frontend systems depend on the published schema outputs
- vets-api → Ruby gem: consumes · Backend systems depend on the Ruby gem interface