feat: generate flow-template and policy JSON schemas from the API

[dangrondahl]

What

Generate the two static JSON Schema assets from the Kosli API (the source of truth in kosli-dev/server) instead of hand-maintaining them.

Published file	API endpoint
schemas/flow-template/v1.json	GET /api/v2/schemas/flow-template/v1
schemas/policy/v1.json	GET /api/v2/schemas/environment-policy/v1

Why

The committed copies drifted from what the API enforces. Concrete example: the decision attestation type (server#5988) is returned by the API but was missing from the hand-edited schemas/flow-template.json. Regenerating from the API also brings the policy schema up to date (draft 2020-12, $defs).

Changes

• scripts/update_schemas.py — fetches both schemas from the public API endpoints and writes them verbatim (pretty-printed). --check exits non-zero when the committed files drift.
• Versioned path for flow-template — moved to schemas/flow-template/v1.json so the file matches the API's $id (.../schemas/flow-template/v1), mirroring the existing policy layout. Two redirects keep old URLs resolving:
  • /schemas/flow-template/v1 → /schemas/flow-template/v1.json
  • /schemas/flow-template.json → /schemas/flow-template/v1.json
• Docs references updated to /schemas/flow-template/v1.json (6 occurrences across 5 pages).
• .github/workflows/update-schemas.yml — regenerates on a daily schedule (and manual dispatch) and opens a PR when the files drift, matching the update-cli-docs.yml pattern.
• tests/test_update_schemas.py — offline unit tests for the generator (render formatting, write mode, drift detection).
• CLAUDE.md — documents the regeneration command and the don't-hand-edit rule.

Decisions confirmed with maintainer

• Source of truth: hit the public production endpoints (no auth required).
• flow-template $id: move to the versioned path, write verbatim (mirror policy).
• Drift handling: scheduled job opens a PR (not a blocking PR check).

Testing

• python scripts/update_schemas.py --check → ok, exit 0
• pytest tests/ → 22 passed
• mint broken-links → only one pre-existing unrelated broken link (/getting_started/service-accounts in working_with_controls.mdx, which already has a redirect)

Acceptance criteria

• Both files generated from the server API, not hand-edited
• Documented command/script regenerates them
• Scheduled job opens a PR when files drift from the API
• Published URLs continue to resolve unchanged (via redirects)

Closes #293

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
kosli	🟢 Ready	View Preview	Jun 30, 2026, 5:17 AM

[claude]

Claude finished @dangrondahl's task in 1m 43s —— View job

---

PR Review: Generate flow-template and policy JSON schemas from the API

• Read CLAUDE.md and repo conventions
• Read all changed docs/config files
• Review documentation changes
• Post findings

---

Nice, well-structured PR. The script, tests, workflow, redirects, and URL updates all look correct. One content issue to flag:

Improvement

template-reference/flow_template.md — attestation type lists are now out of sync with the generated schema

The generated schemas/flow-template/v1.json now includes decision as a valid attestation type (lines 55–57 of the schema), but the human-authored reference page template-reference/flow_template.md still lists only the old set in two places:

• Line 27 (trail-level attestations): lists generic, jira, junit, pull_request, snyk, sonar, * — missing decision and custom:<type-name>.
• Line 49 (artifact-level attestations): lists generic, jira, junit, pull_request, snyk, sonar, custom:<type-name> — missing decision.

Since the whole point of this PR is to bring the schemas in sync with the API, it would be good to also update the prose reference to match. Suggested fix for both lines:

The attestation type. One of: `generic`, `jira`, `junit`, `pull_request`, `snyk`, `sonar`, `decision`, `*` (matches any type), or `custom:<custom-type-name>` for custom attestation types.

Fix this →

Everything else looks good

• Redirects (config/redirects.json): Both redirects correctly preserve backward compatibility for the old /schemas/flow-template.json URL and the extensionless /schemas/flow-template/v1 path.
• Schema URL updates: All 5 pages with $schema references have been updated from flow-template.json to flow-template/v1.json — no stale references remain.
• CLAUDE.md: New "Schemas" section clearly documents the regeneration workflow and the don't-hand-edit rule.
• scripts/update_schemas.py: Clean, minimal script. --check mode is a nice touch for CI validation.
• tests/test_update_schemas.py: Good offline coverage — write mode, check-passes, and drift-detection are all tested.
• update-schemas.yml: Follows the existing update-cli-docs.yml pattern with peter-evans/create-pull-request. Harden Runner is included.
• No navigation changes needed — no new pages were added, just moved/regenerated static assets.

[dangrondahl]

Claude finished @dangrondahl's task in 1m 43s —— View job

PR Review: Generate flow-template and policy JSON schemas from the API

• Read CLAUDE.md and repo conventions
• Read all changed docs/config files
• Review documentation changes
• Post findings

Nice, well-structured PR. The script, tests, workflow, redirects, and URL updates all look correct. One content issue to flag:

Improvement

template-reference/flow_template.md — attestation type lists are now out of sync with the generated schema

The generated schemas/flow-template/v1.json now includes decision as a valid attestation type (lines 55–57 of the schema), but the human-authored reference page template-reference/flow_template.md still lists only the old set in two places:

• Line 27 (trail-level attestations): lists generic, jira, junit, pull_request, snyk, sonar, * — missing decision and custom:<type-name>.
• Line 49 (artifact-level attestations): lists generic, jira, junit, pull_request, snyk, sonar, custom:<type-name> — missing decision.

Since the whole point of this PR is to bring the schemas in sync with the API, it would be good to also update the prose reference to match. Suggested fix for both lines:

The attestation type. One of: `generic`, `jira`, `junit`, `pull_request`, `snyk`, `sonar`, `decision`, `*` (matches any type), or `custom:<custom-type-name>` for custom attestation types.

Fix this →

Everything else looks good

• Redirects (config/redirects.json): Both redirects correctly preserve backward compatibility for the old /schemas/flow-template.json URL and the extensionless /schemas/flow-template/v1 path.
• Schema URL updates: All 5 pages with $schema references have been updated from flow-template.json to flow-template/v1.json — no stale references remain.
• CLAUDE.md: New "Schemas" section clearly documents the regeneration workflow and the don't-hand-edit rule.
• scripts/update_schemas.py: Clean, minimal script. --check mode is a nice touch for CI validation.
• tests/test_update_schemas.py: Good offline coverage — write mode, check-passes, and drift-detection are all tested.
• update-schemas.yml: Follows the existing update-cli-docs.yml pattern with peter-evans/create-pull-request. Harden Runner is included.
• No navigation changes needed — no new pages were added, just moved/regenerated static assets.

@claude this is already captured in #294