feat: unify schema versioning — use repo release tag for all schemas, publish JSONL schemas as release assets#2398
Conversation
✅ Coverage Check PassedOverall Coverage
📁 Per-file Coverage Changes (2 files)
Coverage comparison generated by |
There was a problem hiding this comment.
Pull request overview
This PR moves AWF’s schema versioning away from ad hoc v1 filenames and toward release-version-based identifiers, so config schemas, audit logs, and token-usage logs all reference the repo version in a more unified way. It touches runtime emitters, schema generation, release packaging, tests, samples, and docs to align the new naming/versioning model across the codebase.
Changes:
- Replaces
*.v1.schema.jsonnaming with stable filenames and semver-pattern_schemafields for audit/token-usage records. - Updates schema generation and release packaging to publish config, audit, and token-usage schemas as release assets with versioned
$idvalues. - Threads AWF version information into runtime log emitters and refreshes tests, samples, and documentation to reflect the new contract.
Show a summary per file
| File | Description |
|---|---|
src/squid-config.ts |
Stamps audit JSONL _schema with the AWF version in generated Squid config. |
src/squid-config.test.ts |
Updates audit logformat tests for semver-style _schema values. |
src/schema.test.ts |
Removes legacy v1-schema expectations from config schema tests. |
src/logs/log-parser.test.ts |
Refreshes parser fixture data to use versioned audit _schema values. |
src/docker-manager.ts |
Forwards AWF_VERSION into the api-proxy container environment. |
src/awf-config-schema.json |
Updates embedded config schema metadata to the new unversioned filename. |
scripts/generate-schema.mjs |
Reworks schema generation to emit config/audit/token-usage schemas with versioned $ids. |
schemas/token-usage.schema.json |
Renames/updates token usage schema to semver-pattern _schema validation. |
schemas/audit.schema.json |
Renames/updates audit schema to semver-pattern _schema validation. |
schemas/README.md |
Documents the new schema naming, release URLs, and _schema conventions. |
samples/audit/audit.jsonl |
Refreshes sample audit records to the new _schema format. |
docs/releasing.md |
Updates release documentation for the new schema assets and versioning model. |
docs/awf-config.v1.schema.json |
Removes the legacy version-suffixed config schema file. |
docs/awf-config.schema.json |
Drops the old in-body version field from the published config schema. |
containers/api-proxy/token-tracker.test.js |
Adjusts token-tracker tests for semver _schema handling. |
containers/api-proxy/token-tracker.js |
Emits versioned token-usage _schema values and validates them by pattern. |
.github/workflows/release.yml |
Changes release packaging to generate/upload the new schema asset set. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 17/17 changed files
- Comments generated: 7
| // eslint-disable-next-line @typescript-eslint/no-require-imports | ||
| const { version: AWF_VERSION } = require('../package.json') as { version: string }; | ||
|
|
| // AWF version — embedded in JSONL _schema fields by token-tracker.js | ||
| AWF_VERSION, |
| release/awf-config.schema.json | ||
| release/awf-config.v1.schema.json | ||
| release/audit.schema.json | ||
| release/token-usage.schema.json |
| const parsed = mockStream.writtenRecords[0]; | ||
| expect(parsed._schema).toBe('token-usage/v1'); | ||
| expect(parsed._schema).toMatch(/^token-usage\/v\d+\.\d+\.\d+$/); |
| | Config | `https://github.com/github/gh-aw-firewall/releases/download/<tag>/awf-config.schema.json` | `https://raw.githubusercontent.com/github/gh-aw-firewall/main/docs/awf-config.schema.json` | | ||
| | Audit | `https://github.com/github/gh-aw-firewall/releases/download/<tag>/audit.schema.json` | `https://raw.githubusercontent.com/github/gh-aw-firewall/main/schemas/audit.schema.json` | | ||
| | Token usage | `https://github.com/github/gh-aw-firewall/releases/download/<tag>/token-usage.schema.json` | `https://raw.githubusercontent.com/github/gh-aw-firewall/main/schemas/token-usage.schema.json` | | ||
|
|
| // The audit_jsonl logformat line must embed a semver schema identifier so that | ||
| // every emitted record carries the version tag. | ||
| expect(result).toMatch(/logformat audit_jsonl \{.*"_schema":"audit\/v1"/); | ||
| expect(result).toMatch(/logformat audit_jsonl \{.*"_schema":"audit\/v\d+\.\d+\.\d+"/); |
| // Log a warning (to stderr to avoid polluting stdout) when running without the env var. | ||
| // This can happen during local development or tests outside the container. | ||
| process.stderr.write('{"level":"warn","event":"awf_version_missing","message":"AWF_VERSION env var not set; _schema will use 0.0.0"}\n'); | ||
| } | ||
| const TOKEN_USAGE_SCHEMA = `token-usage/v${AWF_VERSION || '0.0.0'}`; |
|
@copilot address the review feedback |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
Addressed all review feedback in commits
|
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
|
Smoke Test Results: Status: PASS
|
🔬 Smoke Test Results
PR: feat: unify schema versioning — use repo release tag for all schemas, publish JSONL schemas as release assets Overall: PARTIAL — MCP ✅, pre-step data not injected (template variables were not expanded by the runner).
|
Smoke Test: Copilot BYOK (Offline) Mode
Running in BYOK offline mode ( Overall: PASS (core BYOK path verified) PR author:
|
Smoke Test
Warning Firewall blocked 1 domainThe following domain was blocked by the firewall during workflow execution:
network:
allowed:
- defaults
- "registry.npmjs.org"See Network Configuration for more information.
|
Chroot Version Comparison Results
Overall: ❌ Not all versions match — Python and Node.js versions differ between host and chroot environments.
|
🏗️ Build Test Suite Results
Overall: 8/8 ecosystems passed — ✅ PASS
|
Smoke Test: Gemini Engine Validation
Overall Status: PASS
|
Smoke Test Results
Overall: FAIL —
|
AWF had two inconsistent schema versioning schemes: config schema used
awf-config.v1.schema.json(independentv1), while JSONL schemas usedaudit/v1/token-usage/v1constants and were never published as release assets. Thev1naming was ambiguous and external consumers couldn't pin to a specific release's schema.Schema files
schemas/audit.v1.schema.json→schemas/audit.schema.jsonandschemas/token-usage.v1.schema.json→schemas/token-usage.schema.jsondocs/awf-config.v1.schema.json; onlyawf-config.schema.jsonremains"version": "1"field from config schema body_schemaJSON Schema constraint fromconsttopattern:^audit/v\d+\.\d+\.\d+(-\w+)?$(allows dev-build suffix)_schemawire-format field now embeds the writer's versionsrc/squid-config.ts: reads version frompackage.jsonat module load and interpolates it into the Squid logformat string; audit records reflect the AWF CLI versioncontainers/api-proxy/Dockerfile:AWF_VERSIONis now baked into the api-proxy image at build time viaARG AWF_VERSION=0.0.0-dev/ENV AWF_VERSION; the release workflow passes--build-arg AWF_VERSION=<version>so each released image carries its own correct version. Token-usage records therefore reflect the api-proxy image version, which remains correct even when--image-tagpins the proxy to a different releasecontainers/api-proxy/token-tracker.js: readsAWF_VERSIONfrom the baked-in env var; emits a stderr warning if unset and falls back to0.0.0-dev; updatedvalidateTokenUsageRecordto allow the-devsuffix via regex patternsrc/docker-manager.ts: no longer injectsAWF_VERSION— the container's baked-in version is used instead, with a comment explaining the rationaleRelease workflow
scripts/generate-schema.mjs: no longer writes av1file; generates all three schemas (awf-config,audit,token-usage) with versioned$idURLs at release time.github/workflows/release.yml: copies all three schemas torelease/and uploads them as release assets; keepsawf-config.v1.schema.jsonas a compatibility alias (identical toawf-config.schema.json) so existing consumers are not brokenRelease asset URLs follow the pattern:
Tests & docs
squid-config.test.ts: asserts the exactpackage.jsonversion string in the logformat (not just a semver-shaped regex)token-tracker.test.js: adds ajest.isolateModules()describe block that setsAWF_VERSION=9.8.7and verifies the emitted_schemais exactlytoken-usage/v9.8.7; all existing pattern assertions tightened to(-\w+)?$schema.test.ts,log-parser.test.ts,schemas/README.md, anddocs/releasing.mdwith new versioning policy, download URLs, and a deprecation/migration note for the oldawf-config.v1.schema.jsonraw URLsamples/audit/audit.jsonlsample file