feat(schemas): STRUCT-001 - JSON Schema Definition for v2 project format

Add 8 JSON schemas, SchemaValidator with Ajv v8, TS interfaces, and 33 tests. All smoke tests passing. Critical path for STRUCT-002 (Export Engine).
2026-03-08 01:53:30 +01:00 · 2026-02-18 23:45:51 +05:30
parent 83278b4370
commit f8d59cce0b
15 changed files with 2195 additions and 13 deletions
--- a/dev-docs/tasks/phase-10-ai-powered-development/PROGRESS-dishant.md
+++ b/dev-docs/tasks/phase-10-ai-powered-development/PROGRESS-dishant.md
@@ -1,19 +1,92 @@
-# Phase 10 Progress — Dishant
-**Branch:** cline-dev-dishant
+# Phase 10A — AI-Powered Development: Dishant's Progress
+
+**Developer:** Dishant  
+**Branch:** `cline-dev-dishant`  
 **Last Updated:** 2026-02-18

-## Completed This Sprint
+---

-| Task | Name | Completed | Notes |
-|------|------|-----------|-------|
-| — | — | — | — |
+## Task Status

-## In Progress
+| Task ID    | Title                        | Status      | Notes                                      |
+|------------|------------------------------|-------------|--------------------------------------------|
+| STRUCT-001 | JSON Schema Definition       | ✅ Complete | 8 schemas + validator + tests (33/33 pass) |
+| STRUCT-002 | Export Engine Core           | 🔜 Next     | Depends on STRUCT-001                      |

-| Task | Name | Started | Blocker |
-|------|------|---------|---------|
-| — | — | — | Starting after CF11-006/007 |
+---

-## Decisions & Learnings
+## STRUCT-001 — JSON Schema Definition ✅

- [2026-02-18] Sprint 1 started. Phase 10 work begins after CF11-006 and CF11-007 are complete. Starting point will be STRUCT-001 (JSON Schema Definition) — the critical path entry point for all AI features.
+**Completed:** 2026-02-18  
+**Scope:** Define JSON schemas for the v2 multi-file project format
+
+### What was built
+
+All files live under `packages/noodl-editor/src/editor/src/schemas/`:
+
+#### Schema files (8 total)
+
+| File | Schema ID | Describes |
+|------|-----------|-----------|
+| `project-v2.schema.json` | `https://opennoodl.dev/schemas/project-v2.json` | Root project metadata (`nodegx.project.json`) |
+| `component.schema.json` | `https://opennoodl.dev/schemas/component-v2.json` | Component metadata (`component.json`) |
+| `nodes.schema.json` | `https://opennoodl.dev/schemas/nodes-v2.json` | Node graph definitions (`nodes.json`) |
+| `connections.schema.json` | `https://opennoodl.dev/schemas/connections-v2.json` | Connection/wire definitions (`connections.json`) |
+| `registry.schema.json` | `https://opennoodl.dev/schemas/registry-v2.json` | Component index (`_registry.json`) |
+| `routes.schema.json` | `https://opennoodl.dev/schemas/routes-v2.json` | URL route definitions (`nodegx.routes.json`) |
+| `styles.schema.json` | `https://opennoodl.dev/schemas/styles-v2.json` | Global styles + variants (`nodegx.styles.json`) |
+| `model.schema.json` | `https://opennoodl.dev/schemas/model-v2.json` | Backend data model definitions (`models/<Name>.json`) |
+
+#### Validator (`validator.ts`)
+
+- `SchemaValidator` singleton class — compiles all 8 schemas once, reuses validators
+- `SCHEMA_IDS` const — typed schema ID map
+- `validateSchema()` convenience function
+- `validateOrThrow()` — throws with context on failure
+- Per-schema convenience methods: `validateProject()`, `validateComponent()`, etc.
+- `formatValidationErrors()` — human-readable error formatting
+- Ajv v8 with `ajv-formats` for `date-time` format validation
+- `allErrors: true` — collects all errors, not just first
+
+#### Index (`index.ts`)
+
+- Re-exports all schemas, validator, and TypeScript interfaces
+- Full TS interfaces for all 8 file types: `ProjectV2File`, `ComponentV2File`, `NodesV2File`, `ConnectionsV2File`, `RegistryV2File`, `RoutesV2File`, `StylesV2File`, `ModelV2File`
+
+#### Tests (`tests/schemas/schema-validator.test.ts`)
+
+- 33 test cases covering all 8 schemas
+- Valid minimal fixtures, full fixtures with all optional fields
+- Invalid cases: missing required fields, wrong enum values, invalid formats
+- Edge cases: legacy component refs (`/#Header`), complex port type objects, deeply nested metadata
+- Registered in `tests/index.ts` → `tests/schemas/index.ts`
+
+### Dependencies added
+
+```json
+"ajv": "^8.x",
+"ajv-formats": "^2.x"
+```
+
+Added to `packages/noodl-editor/package.json` dependencies.
+
+### Key design decisions
+
+1. **`additionalProperties: true` on nodes/connections** — node parameters and connection metadata are open-ended by design; the schema validates structure, not content
+2. **Port type is `oneOf [string, object]`** — Noodl uses both `"string"` and `{ name: "stringlist", ... }` type formats
+3. **`strict: false` on Ajv** — schemas use `description` in `definitions` which Ajv strict mode rejects
+4. **`require()` for `ajv-formats`** — avoids TS type conflict between root-level `ajv-formats` (which bundles its own Ajv) and the package-local Ajv v8
+
+### Verification
+
+```
+33/33 smoke tests passed (node smoke-test-schemas.js)
+0 TypeScript errors
+```
+
+---
+
+## Next: STRUCT-002 — Export Engine Core
+
+**Unblocked by:** STRUCT-001 ✅  
+**Goal:** Build the engine that converts the legacy `project.json` format into the v2 multi-file directory structure, using the schemas defined in STRUCT-001 for validation.