This directory contains JSON Schema files for the JSONL artifact files emitted by AWF at runtime.

Schema files do not carry an independent version suffix. Instead, the repo release tag is used as the version:

• The $id field in each schema is updated at release time to a stable release download URL (e.g. https://github.com/github/gh-aw-firewall/releases/download/v0.26.0/audit.schema.json).
• The _schema wire-format field in each JSONL record embeds the repo version (e.g. "_schema": "audit/v0.26.0").
• Additive changes (new optional fields) → update the schema file directly; no special action required.
• Breaking changes (field removal, rename, type change, new required field) → document in the changelog; consumers should pin to a specific release tag.

Every JSONL record includes a _schema field that identifies the record type and the AWF version that produced it:

{ "_schema": "token-usage/v0.26.0", "timestamp": "2025-01-01T00:00:00.000Z", ... }
{ "_schema": "audit/v0.26.0", "ts": 1761074374.646, ... }

The _schema field uses the pattern <type>/v<semver>. Consumers should use a prefix match (_schema.startsWith("audit/")) rather than an exact match to handle future versions gracefully.

Each release publishes all schemas as release assets:

https://github.com/github/gh-aw-firewall/releases/download/<tag>/audit.schema.json
https://github.com/github/gh-aw-firewall/releases/download/<tag>/token-usage.schema.json
https://github.com/github/gh-aw-firewall/releases/download/<tag>/awf-config.schema.json

For always-latest (main branch) references:

https://raw.githubusercontent.com/github/gh-aw-firewall/main/schemas/audit.schema.json
https://raw.githubusercontent.com/github/gh-aw-firewall/main/schemas/token-usage.schema.json
https://raw.githubusercontent.com/github/gh-aw-firewall/main/docs/awf-config.schema.json

You can validate a JSONL file against its schema using any JSON Schema validator. Example using ajv-cli:

# Install validator
npm install -g ajv-cli

# Validate all records in audit.jsonl
while IFS= read -r line; do
  echo "$line" | ajv validate -s schemas/audit.schema.json -d /dev/stdin
done < /path/to/audit.jsonl