Web-based schema viewer, editor, and submission/review workflow

[stevevanhooser]

Goal

Provide a browser-based tool that lets contributors view, edit, and submit new DID/NDI document schema types without needing to know git or GitHub. Reviewers handle submissions through normal GitHub PRs.

Scope: target schema version

Build the viewer/editor against schemas/V_delta/ (see schemas/V_delta_SPEC.md). V_delta is the sandbox that will be copied -- closely, we hope -- to V1 once it is cut. Targeting V_delta now means the tool is useful immediately and will migrate to V1 with minimal changes (rename a directory, point the config at it).

V_alpha, V_beta, and V_gamma are out of scope -- the tool does not need to read, render, or edit them.

High-level design

• Hosting: static site on GitHub Pages, served from this repo.
• Editor UI: form auto-generated from the V_delta meta-schema (schemas/V_delta/stable/did_schema_meta.json) via a JSON Schema form library (e.g. @rjsf/core), with a few custom widgets for schema-specific fields.
• Viewer: two-pane layout described below.
• Validation: ajv in the browser against the V_delta meta-schema, so users see errors before submission.
• Auth: GitHub device flow against a GitHub App registered for this repo. No server / no AWS needed -- the client ID is public, the user sees a code and pastes it at github.com/login/device.
• Submission: the editor POSTs an issue containing the full JSON (and a human-readable summary) using a structured issue template.
• Review -> merge: a GitHub Action picks up labeled/approved issues, opens a PR that drops the JSON into the correct schemas/V_delta/<tier>/<class_name>.json location, and links the issue. Reviewers approve the PR as normal.

Viewer UX

Two-pane layout:

Left pane -- superclass tree

• base is at the top as the root.
• Each node has a triangle/caret toggle to expand its subclasses.
• A class with multiple superclasses appears under each of its superclasses (intentional duplication so the user can navigate from any parent).
• Tree is built by walking schemas/V_delta/index.json and reading each schema's superclasses array.
• An "Add new schema" button lives in the left pane (Step 5 wires it to the editor; Step 2 can stub it).

Right pane -- selected schema detail

• Shown when the user clicks a node.
• Header: class_name, class_version, maturity_level, tier, superclasses (as links).
• Fields table: one row per field with name, type, default_value, blank_value, the mustBe* flags, queryable, ontology, documentation, and constraints (rendered readably -- enums as chips, nested constraints expandable).
• depends_on and file sections rendered similarly.
• Raw JSON available behind a "View raw" toggle.

Plan steps (one PR per step)

Each step is intended to be small enough to review in isolation and to leave main in a working state. The path schemas/V_delta/ is referenced via a single config constant so the eventual rename to schemas/V1/ is a one-line change.

Step 1 -- Repo scaffolding for the web app

• Add a web/ directory with a minimal Vite + TypeScript + React skeleton.
• Wire up npm run build to emit a static bundle into web/dist/.
• Add a GitHub Actions workflow that builds the site and deploys to GitHub Pages on push to main.
• No app functionality yet -- just "hello world" served from Pages.

Step 2 -- Schema viewer (read-only)

• Implement the two-pane Viewer UX described above.
• Source of truth for the tree is schemas/V_delta/index.json plus the individual schemas/V_delta/<tier>/<class_name>.json files, fetched at runtime via the GitHub raw-content URLs (or relative paths if the schemas are also bundled with the Pages site).
• No editing, no auth.

Step 3 -- Generated edit form + client-side validation

• Load the V_delta meta-schema and feed it to @rjsf/core (or equivalent) to auto-generate a form.
• Add custom widgets where the auto-generated form is awkward (field-type dropdown limited to supported types, superclass picker that lists existing V_delta class_names, snake_case helper).
• Validate with ajv against the V_delta meta-schema on every change; show errors inline.
• "Download JSON" button -- still no GitHub interaction.

Step 4 -- GitHub App + device-flow login

• Register a GitHub App scoped to this repo with issues: write permission; record the public client ID in the web app config.
• Implement the device-flow login: button -> show user code -> poll for token -> store token in sessionStorage.
• Add a "Signed in as @user" header and a sign-out button.
• No submission yet -- just prove auth works end-to-end.

Step 5 -- Issue submission from the editor

• Define a structured issue template (markdown body with a fenced json block containing the schema, plus a rendered summary above it, plus metadata footer with proposed tier and class_name).
• Wire up the left-pane "Add new schema" button to the editor.
• "Submit for review" button: validates, then POSTs to /repos/.../issues with a schema-submission label.
• After submission, show the issue URL and a "View on GitHub" link.
• Document the contributor workflow in web/README.md.

Step 6 -- Automated PR from approved submissions

• Add a GitHub Action triggered when a maintainer applies an approved label (or comments /approve) to a schema-submission issue.
• The action parses the JSON out of the issue body, writes it to the correct path under schemas/V_delta/<tier>/, opens a PR titled "Add schema: <class_name>", and links the issue.
• Existing test suite runs on the PR; reviewers merge as usual.

Step 7 -- Edit-existing-schema flow (stretch)

• Add an "Edit this schema" button on the right-pane detail view that pre-fills the form.
• Submission becomes an issue proposing changes; the auto-PR action updates the existing file instead of creating a new one.
• Bump class_version automatically with a prompt for MAJOR/MINOR/PATCH.

Future -- V1 migration

• When V1 is cut from V_delta, update the single config constant pointing the web app at schemas/V1/ and verify the build. No code changes expected beyond that and any spec-driven custom-widget tweaks.

Open questions

• Form library choice: @rjsf/core vs. json-editor vs. hand-rolled. rjsf is the default but the V_delta meta-schema may need light cleanup for it to render nicely.
• Schema fetch: bundle the V_delta JSON files with the Pages site at build time (fast, no GitHub API calls, but the site is one commit behind), or fetch them live from the GitHub raw URLs (always current, costs API calls)? Probably bundle.
• Auth UX: device flow is the lowest-burden, but we could also accept a personal access token paste as a fallback for power users.

Non-goals

• Supporting V_alpha, V_beta, or V_gamma in the viewer/editor.
• Offline / PWA support -- adding a schema is a connected activity.
• Editing the meta-schema itself through the UI.
• Authoring DID documents (instances of schemas) -- this tool is for schema definitions only.