Merge pull request #5 from codeforamerica/application-schema-restructure

Application schema restructure

Author: mryhmln

README.md

@@ -37,10 +37,12 @@ Visit `http://localhost:3000` for interactive API docs.
 | `npm run validate` | Validate base specs |
 | `npm run validate:state` | Validate specs for current STATE |
 | `npm run validate:all-states` | Validate all states |
-| `npm run clients:generate` | Generate TypeScript clients |
+| `npm run clients:generate` | Generate Zodios TypeScript clients |
+| `npm run clients:validate` | Type-check generated clients |
 | `npm run postman:generate` | Generate Postman collection |
 | `npm run mock:reset` | Reset database to example data |
 | `npm test` | Run unit tests |
+| `npm run test:integration` | Run integration tests (includes Postman/newman) |
 
 [Full command reference →](./docs/reference/commands.md)
 

docs/architecture-decisions/multi-state-overlays.md

@@ -1,8 +1,8 @@
 # ADR: Multi-State Support Using OpenAPI Overlays
 
-**Status:** Proposed
+**Status:** Accepted
 
-**Date:** 2025-12-18
+**Date:** 2026-01-06
 
 **Deciders:** Development Team
 
@@ -41,7 +41,7 @@ We chose **OpenAPI Overlay Specification (1.0.0)** with a configuration-driven s
 ### How It Works
 
 1. **Base schemas** in `openapi/` define the universal structure
-2. **Overlay files** in `openapi/overlays/{state}.overlay.yaml` declare state-specific modifications
+2. **Overlay files** in `openapi/overlays/{state}/modifications.yaml` declare state-specific modifications
 3. **Resolve script** merges base + overlay → `openapi/resolved/` at build time
 4. **All tooling** operates on resolved specs, unaware of the overlay system
 
@@ -64,8 +64,13 @@ openapi/
 │   ├── person.yaml           # Base schema
 │   └── application.yaml      # Base schema
 ├── overlays/
-│   ├── california.overlay.yaml
-│   └── colorado.overlay.yaml
+│   ├── california/
+│   │   ├── modifications.yaml    # Overlay actions
+│   │   └── replacements/         # Complete schema replacements
+│   │       └── expenses.yaml
+│   └── colorado/
+│       ├── modifications.yaml
+│       └── replacements/
 └── resolved/                 # .gitignored, generated at build time
     ├── persons.yaml
     └── components/
@@ -75,6 +80,7 @@ openapi/
 ### Overlay File Format
 
 ```yaml
+# overlays/california/modifications.yaml
 overlay: 1.0.0
 info:
   title: California State Overlay
@@ -106,20 +112,29 @@ actions:
   - target: $.Person.properties.federalProgramId
     description: Use California-specific name
     rename: calworksId
+
+  # Replace entire schema with state-specific structure (custom extension)
+  - target: $.PersonExpenses
+    description: California expense tracking structure
+    replace:
+      $ref: "./replacements/expenses.yaml#/CaliforniaExpenses"
 ```
 
 ### Custom Extensions
 
-We extend the OpenAPI Overlay spec with a `rename` action for renaming properties:
+We extend the OpenAPI Overlay spec with custom actions:
 
 | Action | Standard | Description |
 |--------|----------|-------------|
 | `update` | Yes | Merge/replace values at target path |
 | `remove` | Yes | Delete value at target path |
 | `rename` | **No** (custom) | Rename property, preserving full definition |
+| `replace` | **No** (custom) | Complete replacement of target (no merging) |
 
 The `rename` action copies the entire property definition to a new key and removes the old key. This is useful when states use different terminology for the same concept without having to duplicate the property definition.
 
+The `replace` action completely replaces the target value (unlike `update` which merges objects). It supports `$ref` to load replacement schemas from separate files in the `replacements/` directory. This is useful when a state needs a fundamentally different structure that can't be achieved through property updates.
+
 ---
 
 ## Options Considered
@@ -260,12 +275,12 @@ openapi/
 
 | File | Change |
 |------|--------|
-| `src/overlay/overlay-resolver.js` | Core overlay resolution logic with custom `rename` action support |
+| `src/overlay/overlay-resolver.js` | Core overlay resolution logic with `rename` and `replace` action support |
 | `scripts/resolve-overlay.js` | CLI script to apply overlays with target validation |
 | `scripts/validate-state.js` | New script to resolve and validate state specs |
 | `scripts/validate-patterns.js` | Updated to support `--dir` argument |
-| `openapi/overlays/california.overlay.yaml` | California state overlay |
-| `openapi/overlays/colorado.overlay.yaml` | Colorado state overlay |
+| `openapi/overlays/{state}/modifications.yaml` | State-specific overlay actions |
+| `openapi/overlays/{state}/replacements/` | State-specific schema replacements |
 | `openapi/resolved/` | Generated directory (.gitignored) |
 | `package.json` | Added overlay and state validation scripts |
 | `.gitignore` | Added `openapi/resolved/` |

docs/guides/state-overlays.md

@@ -5,7 +5,7 @@ State overlays allow you to customize API specifications for different states wi
 ## How It Works
 
 1. **Base schemas** in `openapi/` define the universal structure
-2. **Overlay files** in `openapi/overlays/{state}.overlay.yaml` declare modifications
+2. **Overlay files** in `openapi/overlays/{state}/modifications.yaml` declare modifications
 3. **Resolve script** merges base + overlay into `openapi/resolved/`
 4. **All tooling** operates on resolved specs
 
@@ -33,7 +33,7 @@ npm run overlay:resolve
 Overlays use the [OpenAPI Overlay Specification 1.0.0](https://github.com/OAI/Overlay-Specification):
 
 ```yaml
-# openapi/overlays/california.overlay.yaml
+# openapi/overlays/california/modifications.yaml
 overlay: 1.0.0
 info:
   title: California State Overlay
@@ -133,11 +133,12 @@ Targets use JSONPath-like syntax:
 
 ## Creating a New State Overlay
 
-### 1. Create the Overlay File
+### 1. Create the Overlay Directory and File
 
 ```bash
-# Copy an existing overlay as a template
-cp openapi/overlays/california.overlay.yaml openapi/overlays/newstate.overlay.yaml
+# Create state directory and copy an existing overlay as a template
+mkdir openapi/overlays/newstate
+cp openapi/overlays/california/modifications.yaml openapi/overlays/newstate/modifications.yaml
 ```
 
 ### 2. Update the Metadata

docs/reference/commands.md

@@ -10,11 +10,13 @@ All available npm scripts in the Safety Net OpenAPI toolkit.
 | `npm run validate` | Validate base specs |
 | `npm run validate:state` | Validate specs for current STATE |
 | `npm run validate:all-states` | Validate all states |
-| `npm run clients:generate` | Generate TypeScript clients |
+| `npm run clients:generate` | Generate Zodios TypeScript clients |
+| `npm run clients:validate` | Type-check generated clients |
 | `npm run postman:generate` | Generate Postman collection |
 | `npm run mock:start` | Start mock server only |
 | `npm run mock:reset` | Reset database to example data |
 | `npm test` | Run unit tests |
+| `npm run test:integration` | Run integration tests (includes Postman/newman) |
 
 ## Validation Commands
 
@@ -117,20 +119,30 @@ Creates:
 Generates TypeScript/Zodios clients from specs.
 
 ```bash
-STATE=california npm run clients:generate
+npm run clients:generate
 ```
 
-Output: `generated/clients/zodios/*.ts`
+Output: `packages/clients/generated/clients/zodios/*.ts`
+
+### `npm run clients:validate`
+
+Type-checks the generated Zodios clients using TypeScript.
+
+```bash
+npm run clients:validate
+```
+
+Runs `tsc --noEmit` to verify all generated clients compile without errors.
 
 ### `npm run postman:generate`
 
 Generates a Postman collection from specs.
 
 ```bash
-STATE=california npm run postman:generate
+npm run postman:generate
 ```
 
-Output: `generated/postman-collection.json`
+Output: `packages/clients/generated/postman-collection.json`
 
 ## Server Commands
 
@@ -205,12 +217,17 @@ Alias for `npm test`.
 
 ### `npm run test:integration`
 
-Runs integration tests (requires mock server).
+Runs integration tests against the mock server. Automatically starts the server if not running.
 
 ```bash
 npm run test:integration
 ```
 
+Includes:
+- CRUD operation tests for all discovered APIs
+- Cross-API accessibility tests
+- Postman collection execution via Newman
+
 ### `npm run test:all`
 
 Runs both unit and integration tests.
@@ -239,9 +256,9 @@ npm run validate && npm run validate:all-states
 # Reset and start
 npm run mock:reset && npm start
 
-# Generate all artifacts
-npm run clients:generate && npm run postman:generate
+# Generate and validate all artifacts
+npm run clients:generate && npm run clients:validate && npm run postman:generate
 
-# Validate and test
-npm run validate:state && npm test
+# Full test suite
+npm run validate && npm test && npm run test:integration
 ```

docs/reference/project-structure.md

@@ -25,8 +25,10 @@ safety-net-openapi/
 │   │   │   ├── patterns/           # API design patterns
 │   │   │   │   └── api-patterns.yaml
 │   │   │   ├── overlays/           # State-specific variations
-│   │   │   │   ├── california.overlay.yaml
-│   │   │   │   └── colorado.overlay.yaml
+│   │   │   │   ├── california/
+│   │   │   │   │   └── modifications.yaml
+│   │   │   │   └── colorado/
+│   │   │   │       └── modifications.yaml
 │   │   │   └── resolved/           # Generated state specs (gitignored)
 │   │   ├── src/
 │   │   │   ├── overlay/            # Overlay resolution logic
@@ -95,7 +97,7 @@ npm install -w @safety-net/schemas -w @safety-net/mock-server
 | API specs | kebab-case | `case-workers.yaml` |
 | Component schemas | kebab-case | `case-worker.yaml` |
 | Example files | kebab-case | `case-workers.yaml` |
-| Overlay files | kebab-case + `.overlay` | `california.overlay.yaml` |
+| Overlay files | `{state}/modifications.yaml` | `california/modifications.yaml` |
 | Scripts | kebab-case | `generate-clients.js` |
 | Tests | kebab-case + `.test` | `overlay-resolver.test.js` |
 
@@ -127,7 +129,7 @@ npm install -w @safety-net/schemas -w @safety-net/mock-server
 | `packages/schemas/openapi/*.yaml` | Main API specifications |
 | `packages/schemas/openapi/components/*.yaml` | Reusable schemas |
 | `packages/schemas/openapi/examples/*.yaml` | Example data |
-| `packages/schemas/openapi/overlays/*.overlay.yaml` | State variations |
+| `packages/schemas/openapi/overlays/*/modifications.yaml` | State variations |
 
 ### Generated (Gitignored)
 
@@ -154,7 +156,7 @@ npm run api:new -- --name "benefits" --resource "Benefit"
 
 ## Adding State Overlays
 
-1. Create overlay: `packages/schemas/openapi/overlays/{state}.overlay.yaml`
+1. Create overlay directory and file: `packages/schemas/openapi/overlays/{state}/modifications.yaml`
 2. Define actions for state-specific changes
 3. Validate: `STATE={state} npm run validate:state`
 

package.json

@@ -21,6 +21,7 @@
     "overlay:resolve": "npm run overlay:resolve -w @safety-net/schemas",
     "overlay:list": "npm run overlay:list -w @safety-net/schemas",
     "clients:generate": "npm run generate -w @safety-net/clients",
+    "clients:validate": "npm run validate -w @safety-net/clients",
     "postman:generate": "npm run postman -w @safety-net/clients",
     "mock:start": "npm start -w @safety-net/mock-server",
     "mock:setup": "npm run setup -w @safety-net/mock-server",

packages/clients/package.json

@@ -5,14 +5,18 @@
   "type": "module",
   "scripts": {
     "generate": "node scripts/generate-zodios.js",
-    "postman": "node scripts/generate-postman.js"
+    "postman": "node scripts/generate-postman.js",
+    "validate": "tsc --noEmit -p tsconfig.validate.json"
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^11.7.2",
     "@safety-net/schemas": "*",
-    "js-yaml": "^4.1.0"
+    "@zodios/core": "^10.9.6",
+    "js-yaml": "^4.1.0",
+    "zod": "^3.23.8"
   },
   "devDependencies": {
-    "openapi-zod-client": "^1.18.2"
+    "openapi-zod-client": "^1.18.2",
+    "typescript": "^5.3.3"
   }
 }

packages/clients/scripts/generate-zodios.js

@@ -10,6 +10,7 @@ import { validateSpec } from '@safety-net/schemas/validation';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const workspaceRoot = join(__dirname, '..');
+const schemasRoot = join(__dirname, '..', '..', 'schemas');
 
 /**
  * Executes a command and returns a promise
@@ -128,8 +129,8 @@ async function generateClient(specPath) {
  * Main function to generate all clients
  */
 async function main() {
-  const openAPIDir = join(workspaceRoot, 'openapi');
-  
+  const openAPIDir = join(schemasRoot, 'openapi');
+
   console.log('🚀 Starting Zodios API client generation...');
   console.log(`📂 Searching for OpenAPI specs in: ${openAPIDir}\n`);
 

packages/clients/tsconfig.validate.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": [
+    "generated/clients/zodios/**/*.ts"
+  ]
+}

packages/mock-server/package.json

@@ -20,5 +20,8 @@
     "express": "^5.1.0",
     "js-yaml": "^4.1.0",
     "swagger-ui-express": "^5.0.1"
+  },
+  "devDependencies": {
+    "newman": "^6.2.1"
   }
 }