Generate flow-template and policy JSON schemas from the API (source of truth)

[dangrondahl]

Problem

The two JSON Schema files served from this repo as static assets are maintained by hand and have drifted from the live schemas the API actually enforces:

• https://docs.kosli.com/schemas/flow-template.json ← schemas/flow-template.json
• https://docs.kosli.com/schemas/policy/v1.json ← schemas/policy/v1.json (with the redirect /schemas/policy/v1 → /schemas/policy/v1.json in config/redirects.json)

The source of truth for both schemas is the kosli-dev/server API, which generates them from the Pydantic models in src/fastapi_app/v2/schemas.py:

Static file (docs repo)	Authoritative API endpoint (server repo)
schemas/flow-template.json	GET /api/v2/flow-template/v1 ($id: https://docs.kosli.com/schemas/flow-template/v1)
schemas/policy/v1.json	GET /api/v2/environment-policy/v1 ($id: https://docs.kosli.com/schemas/policy/v1)

Because the static copies are edited manually, they go stale. Concrete example: the decision attestation type was added to flow templates in kosli-dev/server (PR kosli-dev/server#5988) and is returned by the API endpoint, but the committed schemas/flow-template.json still only lists ["generic", "jira", "junit", "pull_request", "snyk", "sonar", "*"]. Editors that validate against the published static file will incorrectly flag type: decision as invalid.

Proposed solution

Generate both static files from the API endpoints rather than hand-editing them, so the published schemas are always derived from the source of truth.

Add a script (e.g. under scripts/) and/or a CI step that:

1. Fetches the live schema from each API endpoint:
   • GET <api-base>/api/v2/flow-template/v1 → write schemas/flow-template.json
   • GET <api-base>/api/v2/environment-policy/v1 → write schemas/policy/v1.json
2. Writes them to the existing static paths so the published URLs are unchanged.
3. Runs in CI (and/or as a pre-commit / refresh script) so drift is caught — ideally failing the build if the committed files differ from what the API returns.

Notes / decisions to confirm

• Cross-repo dependency: the source of truth lives in kosli-dev/server. Decide how the docs build reaches the schema (hit a deployed environment's public endpoint, vs. server publishing the artifacts somewhere the docs build can pull).
• $id mismatch to reconcile: the API serves the flow-template schema with $id: .../schemas/flow-template/v1, but the published static file lives at .../schemas/flow-template.json. Decide whether to keep the .json path, move to the versioned /v1 path, or rewrite $id on generation. The policy schema already aligns (/schemas/policy/v1 via redirect).
• The flow-template static file currently declares draft-07 ($schema: http://json-schema.org/draft-07/schema#) while the API generates draft 2020-12 — generating from the API will change this; verify editor/tooling compatibility.

Acceptance criteria

• schemas/flow-template.json and schemas/policy/v1.json are generated from the server API endpoints, not edited by hand.
• A documented command/script regenerates them.
• CI fails (or a scheduled job opens a PR) when the committed files drift from the API.
• Published URLs continue to resolve unchanged.

References

• Server schema generator: kosli-dev/server src/fastapi_app/v2/schemas.py
• Drift example: decision type added in kosli-dev/server#5988
• Related docs-page update: see companion issue for template-reference/flow_template