# department-of-veterans-affairs/vets-json-schema architecture

> Architecture diagram of the GitHub repository department-of-veterans-affairs/vets-json-schema, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/department-of-veterans-affairs/vets-json-schema
- Repository: https://github.com/department-of-veterans-affairs/vets-json-schema

## Overview

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: [`src/generate-schemas.js`](https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/src/generate-schemas.js) (Schema build), [`src/schemas`](https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/src/schemas) (Form schemas), [`.github/workflows`](https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/.github/workflows) (CI workflows), [`test/schemas`](https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/test/schemas) (Schema tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Authoring source"]
  node_schemas["Form schemas<br/>schema modules"]
  node_common["Shared defs<br/>shared schema utils"]
  node_examples["Source examples<br/>example payloads"]
  node_schema_gen["Schema build<br/>generator"]
  node_watch["Watch mode<br/>rebuild loop<br/>[watch.js]"]
  node_start["Start script<br/>build runner<br/>[start.js]"]
end

subgraph group_published["Published output"]
  node_dist_schemas["Dist schemas<br/>published schemas"]
  node_dist_examples["Dist examples<br/>published examples"]
  node_dist_meta["Metadata files<br/>published metadata"]
end

subgraph group_quality["Validation and CI"]
  node_schema_tests["Schema tests<br/>contract tests"]
  node_common_tests["Shared tests<br/>test harness"]
  node_test_support["Test support<br/>test helpers"]
  node_ci["CI workflows<br/>automation<br/>[workflows]"]
end

subgraph group_integration["Package interfaces"]
  node_ruby_gem["Ruby gem<br/>cross-language package"]
  node_gemspec["Gem spec<br/>package manifest"]
  node_node_pkg["Node package<br/>package manifest<br/>[package.json]"]
  node_readme["Usage docs<br/>[README.md]"]
  node_vets_website(("vets-website<br/>frontend consumer"))
  node_vets_api(("vets-api<br/>backend consumer"))
end

node_common -->|"shared definitions"| node_schemas
node_examples -->|"validate against"| node_schemas
node_schema_gen -->|"emits"| node_dist_schemas
node_schema_gen -->|"emits"| node_dist_examples
node_schema_gen -->|"emits"| node_dist_meta
node_schemas -->|"inputs"| node_schema_gen
node_examples -->|"inputs"| node_schema_gen
node_watch -.->|"rebuilds"| node_schema_gen
node_start -->|"runs"| node_schema_gen
node_schema_tests -->|"covers"| node_schemas
node_schema_tests -->|"covers"| node_examples
node_common_tests -->|"covers"| node_common
node_common_tests -->|"covers"| node_schemas
node_test_support -->|"supports"| node_schema_tests
node_test_support -->|"supports"| node_common_tests
node_ci -->|"runs"| node_schema_tests
node_ci -->|"runs"| node_common_tests
node_ci -->|"verifies"| node_schema_gen
node_node_pkg -->|"scripts"| node_schema_gen
node_node_pkg -->|"configures"| node_ci
node_gemspec -->|"packages"| node_ruby_gem
node_ruby_gem -->|"bundles"| node_dist_schemas
node_readme -.->|"guides"| node_vets_website
node_readme -.->|"guides"| node_vets_api
node_vets_website -->|"consumes"| node_dist_schemas
node_vets_api -->|"consumes"| node_ruby_gem

click node_schemas "https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/src/schemas"
click node_common "https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/src/common"
click node_examples "https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/src/examples"
click node_schema_gen "https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/src/generate-schemas.js"
click node_watch "https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/src/watch.js"
click node_start "https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/src/start.js"
click node_dist_schemas "https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/dist"
click node_dist_examples "https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/dist"
click node_dist_meta "https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/dist"
click node_ruby_gem "https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/lib/vets_json_schema.rb"
click node_gemspec "https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/vets_json_schema.gemspec"
click node_node_pkg "https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/package.json"
click node_readme "https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/README.md"
click node_schema_tests "https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/test/schemas"
click node_common_tests "https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/test/common"
click node_test_support "https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/test/support"
click node_ci "https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/.github/workflows"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_schemas,node_common,node_examples,node_schema_gen,node_watch,node_start toneBlue
class node_dist_schemas,node_dist_examples,node_dist_meta toneAmber
class node_schema_tests,node_common_tests,node_test_support,node_ci toneMint
class node_ruby_gem,node_gemspec,node_node_pkg,node_readme,node_vets_website,node_vets_api toneRose
```

## Components

### Authoring source

Schema definitions and reusable source modules

- [Form schemas](https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/src/schemas): schema modules · Per-form and per-endpoint JSON Schema sources · `src/schemas`
- [Shared defs](https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/src/common): shared schema utils · Reusable constants, helpers, definitions, and transforms · `src/common`
- [Source examples](https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/src/examples): example payloads · Validated example payloads that mirror schema contracts · `src/examples`
- [Schema build](https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/src/generate-schemas.js): generator · Build entry point that compiles source schemas into distributable artifacts · `src/generate-schemas.js`
- [Watch mode](https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/src/watch.js): rebuild loop · Development flow for regenerating artifacts on source changes · `src/watch.js`
- [Start script](https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/src/start.js): build runner · Runtime entry point for generating and publishing outputs · `src/start.js`

### Published output

Generated artifacts consumed by downstream systems

- [Dist schemas](https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/dist): published schemas · Generated JSON Schema files consumed by downstream projects · `dist`
- [Dist examples](https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/dist): published examples · Generated example payloads alongside the published schemas · `dist`
- [Metadata files](https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/dist): published metadata · 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](https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/test/schemas): contract tests · Per-form specs that validate schemas and examples · `test/schemas`
- [Shared tests](https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/test/common): test harness · Repository-wide checks for all schemas, examples, and definitions · `test/common`
- [Test support](https://github.com/department-of-veterans-affairs/vets-json-schema/tree/master/test/support): test helpers · Reusable fixtures and validation helpers for contract testing · `test/support`
- [CI workflows](https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/.github/workflows): automation · 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](https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/lib/vets_json_schema.rb): cross-language package · Ruby entry point exposing the generated schema bundle · `lib/vets_json_schema.rb`
- [Gem spec](https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/vets_json_schema.gemspec): package manifest · Ruby package metadata for bundling the generated artifacts · `vets_json_schema.gemspec`
- [Node package](https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/package.json): package manifest · JavaScript package metadata and scripts for generation and validation · `package.json`
- [Usage docs](https://github.com/department-of-veterans-affairs/vets-json-schema/blob/master/README.md): docs · Consumer guidance for updating and using the package · `README.md`
- **vets-website**: frontend consumer · Downstream consumer of the published JSON schemas
- **vets-api**: backend consumer · Downstream consumer of the Ruby gem and published contracts

## Connections

- 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
