Problem
The reference CLI (appfeed) uses ajv with the canonical
spec/apps.schema.json. The browser reader (site/validator.js) is
a hand-rolled validator that re-encodes the same constraints in JS.
These two implementations can drift. The hard contract today (version
required, apps[] required, per-app name + url required) is
covered in both, but every future schema change risks subtle
divergence: a field accepted by the CLI but rejected by the reader,
or vice versa.
This is a P1 because the spec's promise — "any validator should agree
on what's valid" — is the credibility anchor of the standard.
Acceptance criteria
- A single source of truth drives both validators, OR
- Both validators run against a shared corpus of fixtures (valid +
invalid) in CI and any disagreement fails the build.
Options
- Replace hand-rolled with ajv-bundled-for-browser. Ship a built
ajv bundle to site/. Adds ~50KB but eliminates drift by
construction.
- Shared fixture suite. Keep both implementations but add a
test/fixtures/parity/ corpus and a CI job that runs each fixture
through both validators and asserts identical
{ ok, errorPaths[] }.
- Codegen the JS validator. Generate
validator.js from the
schema at build time (e.g. ajv-standalone). Bigger investment.
Recommended: start with (2), revisit (1) when the schema gets richer.
Notes
Surfaced by 5 of 11 reviewers in the v0.1 code review. Tracking issue
linked from appfeed/README.md and site/validator.js once a
direction is picked.
Problem
The reference CLI (
appfeed) uses ajv with the canonicalspec/apps.schema.json. The browser reader (site/validator.js) isa hand-rolled validator that re-encodes the same constraints in JS.
These two implementations can drift. The hard contract today (
versionrequired,
apps[]required, per-appname+urlrequired) iscovered in both, but every future schema change risks subtle
divergence: a field accepted by the CLI but rejected by the reader,
or vice versa.
This is a P1 because the spec's promise — "any validator should agree
on what's valid" — is the credibility anchor of the standard.
Acceptance criteria
invalid) in CI and any disagreement fails the build.
Options
ajv bundle to
site/. Adds ~50KB but eliminates drift byconstruction.
test/fixtures/parity/corpus and a CI job that runs each fixturethrough both validators and asserts identical
{ ok, errorPaths[] }.validator.jsfrom theschema at build time (e.g. ajv-standalone). Bigger investment.
Recommended: start with (2), revisit (1) when the schema gets richer.
Notes
Surfaced by 5 of 11 reviewers in the v0.1 code review. Tracking issue
linked from
appfeed/README.mdandsite/validator.jsonce adirection is picked.