@devfellowship/ux-paths-spec

The DFL UX Paths data contract, on its own: the v1 JSON Schema, TypeScript types generated from it, and a validate() with zero runtime dependencies and zero network I/O.

pnpm add @devfellowship/ux-paths-spec

import { validate, assertValid, SCHEMA_V1 } from "@devfellowship/ux-paths-spec";
import type { UxPathsDoc } from "@devfellowship/ux-paths-spec";

const result = validate(JSON.parse(text));
if (!result.valid) {
  for (const error of result.errors) console.error(error.formatted);
  //  screens[0].id: must be string (expected type: string)
  process.exit(1);
}
result.doc.screens; // typed as UxPathsDoc

// Or the throwing form, which narrows in place.
assertValid(doc, "itera-player.flows.json");

Why this is a separate package

Its consumers are a CI validator, a capture job and an AI explorer. None of them should need React to find out whether a flows.json is well-formed, and one of them runs in a browser. The schema is a data contract, so it ships as data — not folded into a component library.

It also ends a vendored copy kept in step by a promise. dfl-components-cli carries its own copy of v1.schema.json with a comment asking a human to "mirror it in the same round". A promise fails quietly: the copy goes stale, the validator keeps exiting 0, and a document nobody should have accepted sails through. Here, every artifact that restates the schema is generated from it, and CI fails if any of them stops matching.

What it exports

The raw schema also ships in the tarball, for consumers that are not TypeScript:

import schema from "@devfellowship/ux-paths-spec/schema/v1.json" with { type: "json" };

The $id is a name, not an address

SCHEMA_ID is https://raw.githubusercontent.com/devfellowship/dfl-ux-paths/main/schema/v1.json.

dfl-ux-paths is a private repo, so that URL 404s for anyone outside the org — and GitHub reports a private path as not found, never forbidden, so the failure disguises itself as a broken link. The $id identifies the schema. It is never fetched. This package exists in large part so that nothing has to try.

Zero runtime dependencies is a tested property

dependencies is absent from package.json, and src/__tests__/package-contract.test.ts fails the build if one appears, if shipped source imports anything non-relative, or if it references fetch / node:fs / any other host API.

tsconfig.build.json drops @types/node from the shipped compile, so a node: import is a compile error rather than a convention someone remembers.

So how does it validate without Ajv?

It interprets the schema at runtime. validate() reads SCHEMA_V1 and walks the document against it — the schema is the input, never a thing transcribed into TypeScript. Add a field upstream and this validator enforces it with no edit here. A hand-written validator would have re-created the exact drift this package exists to end.

Two guards keep that honest:

• Ajv parity. Ajv is the reference implementation and stays a devDependency. src/__tests__/ajv-parity.test.ts runs both engines over every committed flows document plus ~30 single-rule mutations, and fails on any disagreement.
• Unknown keywords are a hard stop. The interpreter implements a fixed keyword set. If a future schema uses one it does not know, assertSchemaSupported() throws naming the keyword, rather than skipping it and quietly accepting documents it should refuse. A v1.4 needing maxLength fails here loudly, in the round it lands.

Versioning

major.minor tracks the highest schema_version the package admits — 1.3.x ships schema v1.3. A schema v1.4 makes it 1.4.0. A fix in validate() is a patch bump. A test asserts the version and the schema agree.

Changing the schema

schema/v1.json at the repo root is the single source of truth. Edit it, then:

pnpm --filter @devfellowship/ux-paths-spec run generate

That rewrites spec/schema/v1.json (byte copy), spec/src/schema.generated.ts and spec/src/types.generated.ts. Never edit those three by hand. CI runs generate --check and fails, naming the stale files, if you forget.

Not in the schema yet (a v1.4 conversation)

The viewer app reads three fields the schema has never defined: requirements[], screen.fidelity and screen.archetype (plus screen.page_class). The schema sets additionalProperties: false at the top level and on $defs/screen, so a document carrying any of them is refused — this is a real gap, not a tolerated extra. Three committed viewer fixtures fail validation for exactly this reason, and ajv-parity.test.ts pins that fact with both engines so it stays visible until v1.4 closes it.

License

MIT.