Document AWF schema URLs for config and JSONL output formats

[lpcox]

Summary

AWF publishes versioned JSON Schemas for its config file format and its runtime JSONL output artifacts. These URLs should be documented in gh-aw so that workflow authors and downstream consumers can discover and reference them.

Published Schemas

AWF Config Schema

Used for awf.yml / awf.json config file validation. Users can add a $schema field to their config files for editor autocompletion and validation.

Channel	URL
Latest (main)	https://raw.githubusercontent.com/github/gh-aw-firewall/main/docs/awf-config.schema.json
Pinned to release	https://github.com/github/gh-aw-firewall/releases/download/<tag>/awf-config.schema.json
Latest release shortcut	https://github.com/github/gh-aw-firewall/releases/latest/download/awf-config.schema.json

Example usage in awf.yml:

$schema: https://github.com/github/gh-aw-firewall/releases/latest/download/awf-config.schema.json
network:
  allowDomains:
    - api.github.com

JSONL Output Schemas

AWF emits two JSONL artifact files at runtime. Each line contains a _schema field identifying the record type and AWF version (e.g., "_schema": "audit/v0.26.0").

Audit Log Schema (audit.schema.json)

L7 HTTP/HTTPS traffic decisions (allowed/denied) logged by the Squid proxy.

Channel	URL
Latest (main)	https://raw.githubusercontent.com/github/gh-aw-firewall/main/schemas/audit.schema.json
Pinned to release	https://github.com/github/gh-aw-firewall/releases/download/<tag>/audit.schema.json

Token Usage Schema (token-usage.schema.json)

Per-API-call token usage records emitted by the api-proxy sidecar.

Channel	URL
Latest (main)	https://raw.githubusercontent.com/github/gh-aw-firewall/main/schemas/token-usage.schema.json
Pinned to release	https://github.com/github/gh-aw-firewall/releases/download/<tag>/token-usage.schema.json

Versioning Policy

• Schemas do not carry independent version numbers — they are versioned by the AWF release tag
• The $id field in each schema is updated at release time to point to the release download URL
• Each JSONL record includes _schema: "<type>/v<semver>" for self-describing records
• Consumers should use prefix matching (e.g., _schema.startsWith("audit/")) for forward compatibility
• Additive changes (new optional fields) are non-breaking; breaking changes are documented in the changelog

Source Locations in gh-aw-firewall

• Config schema source: docs/awf-config.schema.json (generated by scripts/generate-schema.mjs)
• Config schema runtime copy: src/awf-config-schema.json (kept in sync, verified by tests)
• JSONL schemas: schemas/
• Schema README: schemas/README.md

Suggested Action

Add a brief section to the gh-aw documentation (or the AWF config file docs) that references these URLs so workflow authors know where to find them.