File formats#

#Persisted formats

Every file phax writes starts with $schema, naming its format and the phax release that wrote it, for example https://docs.phax.run/schemas/run-status/0.17.0.json. Each URL serves that format's JSON Schema, and stays up for good. Files written before 0.17.0 have no $schema.

#Read phax files from code

@lbdremy/phax-schemas reads all of them, with phax's own types and verdicts, without phax installed. parseDocument reads any file that carries $schema; the JSON Schema of each format is in the package, as json/<format id>.schema.json.

npm install @lbdremy/phax-schemas

// read-record.mjs: Node 20+, phax not installed, only @lbdremy/phax-schemas
import { execFileSync } from "node:child_process";
import { parsePhaseRecordManifest } from "@lbdremy/phax-schemas";

const [runId, phaseId] = process.argv[2].split("/"); // "<runId>/phase-01"
const git = (...args) => execFileSync("git", args, { encoding: "utf8" }).trim();

// Each commit on the records branch holds only its own record: find the
// record's commit by its trailers, then read the file at that commit.
const sha = git(
  "log",
  "phax/records/v1",
  "--format=%H",
  "--fixed-strings",
  "--all-match",
  `--grep=Run-Id: ${runId}`,
  `--grep=Phase-Id: ${phaseId}`,
  "-1",
);
if (!sha) {
  console.error(`no record for ${runId}/${phaseId} on phax/records/v1`);
  process.exit(1);
}
const raw = git("show", `${sha}:${runId}/${phaseId}/record.json`);

const parsed = parsePhaseRecordManifest(JSON.parse(raw));
if (!parsed.ok) {
  console.error(`record.json: ${parsed.error.path}: ${parsed.error.message}`);
  process.exit(1);
}
const { outcome, usage } = parsed.value; // typed PhaseRecord
console.log(runId, phaseId, outcome, usage.available ? usage.usage.provider : "no usage");

node read-record.mjs <runId>/phase-01

A failed parse is a value, never an exception: parsed.ok is false, with a path and a message. A file stays readable as phax evolves: an older shape still parses, upgraded in memory by the format's toLatest* function (a fact phax did not track yet becomes { kind: "unknown" }), and a file written by a newer phax asks you to upgrade the package.

Each commit on phax/records/v1 holds only its own record, so git show phax/records/v1:<path> sees only the newest one: find a record by its commit trailers (Run-Id and Phase-Id, or Authoring-Id), as above. To read them all, list the branch's commits (git log phax/records/v1 --format=%H), read the record.json each one holds (git ls-tree -r --name-only <sha>, then git show <sha>:<path>) and give it to parseRecordManifest.

#Served JSON Schemas

Every $schema URL a released phax writes is served here, byte for byte:

• https://docs.phax.run/schemas/authoring-record-manifest/0.17.0.json
• https://docs.phax.run/schemas/authoring-record-manifest/0.18.0.json
• https://docs.phax.run/schemas/compliance-review/0.17.0.json
• https://docs.phax.run/schemas/compliance-review/0.18.0.json
• https://docs.phax.run/schemas/gate-attribution/0.17.0.json
• https://docs.phax.run/schemas/gate-attribution/0.18.0.json
• https://docs.phax.run/schemas/gate-diagnostics/0.17.0.json
• https://docs.phax.run/schemas/gate-diagnostics/0.18.0.json
• https://docs.phax.run/schemas/gate-pending/0.17.0.json
• https://docs.phax.run/schemas/gate-pending/0.18.0.json
• https://docs.phax.run/schemas/phase-file-reconciliation/0.17.0.json
• https://docs.phax.run/schemas/phase-file-reconciliation/0.18.0.json
• https://docs.phax.run/schemas/phase-record-manifest/0.17.0.json
• https://docs.phax.run/schemas/phase-record-manifest/0.18.0.json
• https://docs.phax.run/schemas/phase-status/0.17.0.json
• https://docs.phax.run/schemas/phase-status/0.18.0.json
• https://docs.phax.run/schemas/phax-plan/0.17.0.json
• https://docs.phax.run/schemas/phax-plan/0.18.0.json
• https://docs.phax.run/schemas/plan-approvals/0.17.0.json
• https://docs.phax.run/schemas/plan-approvals/0.18.0.json
• https://docs.phax.run/schemas/plan-document/0.17.0.json
• https://docs.phax.run/schemas/plan-document/0.18.0.json
• https://docs.phax.run/schemas/registry/0.17.0.json
• https://docs.phax.run/schemas/registry/0.18.0.json
• https://docs.phax.run/schemas/run-status/0.17.0.json
• https://docs.phax.run/schemas/run-status/0.18.0.json
• https://docs.phax.run/schemas/spec-approvals/0.17.0.json
• https://docs.phax.run/schemas/spec-approvals/0.18.0.json
• https://docs.phax.run/schemas/spec-document/0.17.0.json
• https://docs.phax.run/schemas/spec-document/0.18.0.json