Signal Schema

The complete structure of an Axiomo Signal

Overview

An Axiomo Signal is a structured artifact that captures everything relevant about a pull request for review. It transforms raw PR data into actionable intelligence: who submitted it, what they're trying to do, what's the risk, and where to focus.

Signals are versioned (axiomo.signal.v1) and have stable IDs for permanent reference. Every section is computed by deterministic analyzers, with optional LLM augmentation for intent extraction.

What Signals Capture

Contributor trust signals and history
Risk assessment with explicit drivers
Evidence from CI/CD and checks
Supply chain modifications
Focus files ranked by priority
Policy evaluation results
LLM-extracted intent summary

What Signals Don't Capture

Full source code or diffs
Secrets or credentials
Line-by-line code review comments
Personal information beyond username

Top-Level Structure

axiomo-signal.json

{
  "version": "axiomo.signal.v1",
  "signal_id": "ax-owner-repo-123-a1b2c3d4",
  "signal_url": "https://axiomo.app/signal/ax-owner-repo-123-a1b2c3d4",

  "pr": { /* PR metadata */ },
  "contributors": [ /* contributor context */ ],
  "intent": { /* LLM-extracted intent */ },
  "risk": { /* risk assessment */ },
  "evidence": { /* CI/check signals */ },
  "supply_chain": { /* dependency changes */ },
  "triage": { /* review effort */ },
  "conventions": { /* guideline compliance */ },
  "focus": { /* priority files */ },
  "governance": { /* policy evaluation */ },
  "review": { /* recommendation */ },
  "meta": { /* generation metadata */ }
}

Field	Required	Description
`version`	Yes	Schema version, always `axiomo.signal.v1`
`signal_id`	Yes	Unique identifier: `ax-{owner}-{repo}-{pr}-{hash}`
`signal_url`	Yes	Permanent URL for this signal
`pr`	Yes	Source PR metadata
`contributors`	Yes	Array of contributors with trust signals
`intent`	No	LLM-extracted goal, non-goals, criteria
`risk`	Yes	Risk level, score, and drivers
`evidence`	Yes	CI signals and completeness
`supply_chain`	Yes	Dependency and build changes
`triage`	Yes	Review effort and staleness
`conventions`	Yes	Contribution guideline compliance
`focus`	Yes	Priority files for review
`governance`	Yes	Policy evaluation results
`review`	Yes	Suggested action and rationale
`meta`	Yes	Generation timestamp and duration

PR Reference

Basic metadata about the source pull request.

{
  "provider": "github",
  "owner": "expressjs",
  "repo": "express",
  "number": 5765,
  "url": "https://github.com/expressjs/express/pull/5765",
  "title": "Add streaming response support",
  "author": "contributor-username",
  "base_branch": "main",
  "head_branch": "feature/streaming",
  "created_at": "2026-01-20T10:30:00Z",
  "updated_at": "2026-01-22T14:15:00Z"
}

Contributors

Trust signals for each contributor. The primary author is marked with is_primary: true.

contributors[0]

{
  "username": "contributor-username",
  "trust_level": "established",
  "basis": "public_github_data",
  "context": "Established contributor with 47 PRs, 92% approval rate",
  "is_primary": true,
  "commit_count": 3,
  "public_signals": {
    "account_age_days": 1825,
    "public_repos": 42,
    "followers": 156,
    "first_contribution_to_repo": false,
    "prior_prs_to_repo": 47,
    "prior_prs_merged": 43
  }
}

Trust Level	Meaning
`new`	Limited history, higher scrutiny recommended
`low`	Some history but insufficient for confidence
`established`	Consistent positive track record
`trusted`	Strong history with high approval rate
`maintainer`	Has write access to the repository

Risk Assessment

Computed risk with explicit, inspectable drivers. The score (0-1) maps to discrete levels.

risk

{
  "level": "high",
  "score": 0.65,
  "drivers": [
    {
      "id": "large_diff",
      "weight": 0.25,
      "source": "baseline",
      "description": "Large change: 847 lines across 23 files",
      "triggered_by": []
    },
    {
      "id": "touches_auth",
      "weight": 0.35,
      "source": "governed_path",
      "description": "Modifies authentication code",
      "triggered_by": ["src/middleware/auth.ts", "src/services/session.ts"],
      "recommendation": "Require security review"
    }
  ]
}

low

0.0 - 0.3

medium

0.3 - 0.6

high

0.6 - 0.8

critical

0.8 - 1.0

Evidence

CI/CD signals and verification status. The completeness score indicates how much evidence is available versus expected.

evidence

{
  "completeness_score": 0.85,
  "signals": [
    {
      "id": "ci_status",
      "status": "pass",
      "source": "github_actions",
      "source_url": "https://github.com/.../actions/runs/123",
      "timestamp": "2026-01-22T14:10:00Z"
    },
    {
      "id": "tests",
      "status": "pass",
      "source": "jest",
      "details": "142 tests passed"
    },
    {
      "id": "security_scan",
      "status": "unavailable"
    }
  ],
  "missing_signals": ["security_scan", "coverage"]
}

Supply Chain

Tracks modifications to dependencies, CI configuration, and build scripts - changes that can have outsized impact.

supply_chain

{
  "risk_level": "elevated",
  "modifies_dependencies": true,
  "new_dependencies": ["@streaming/core@2.1.0"],
  "removed_dependencies": [],
  "modifies_lockfile": true,
  "modifies_ci_config": false,
  "modifies_build_scripts": false,
  "modifies_release_config": false,
  "ci_files_changed": []
}

Focus Files

Ranked list of files that deserve attention, filtering out noise like lockfiles and generated code.

focus

{
  "summary": "Focus on auth middleware and streaming implementation",
  "files": [
    {
      "path": "src/middleware/auth.ts",
      "reason": "Touches authentication logic",
      "priority": "critical",
      "lines_changed": 45,
      "is_new_file": false,
      "is_deleted": false
    },
    {
      "path": "src/streaming/handler.ts",
      "reason": "Core feature implementation",
      "priority": "high",
      "lines_changed": 234,
      "is_new_file": true,
      "is_deleted": false
    }
  ],
  "noise_files": ["package-lock.json", "dist/bundle.js"]
}

Governance

Policy evaluation results. Mode indicates whether policies are baseline (no config), advisory (warn only), or enforcing.

governance

{
  "mode": "advisory",
  "governed_paths_touched": ["src/middleware/auth.ts"],
  "policy_id": "security-policy-v1",
  "policy_result": "warn",
  "findings": [
    {
      "rule_id": "SEC-01",
      "rule_name": "Auth changes require security review",
      "status": "warn",
      "requirement": "Changes to auth code require security team approval",
      "remediation": "Request review from @security-team"
    }
  ]
}

Review Recommendation

Suggested action based on all signals, with rationale.

review

{
  "readiness_score": 0.72,
  "suggested_action": "request_changes",
  "action_rationale": "High-risk change touching auth with policy warning. Recommend security review before approval.",
  "draft_comments": [
    {
      "file": "src/middleware/auth.ts",
      "line": 42,
      "comment": "This modifies token validation logic. Consider adding test coverage.",
      "type": "suggestion"
    }
  ]
}

Action	Meaning
`approve`	Low risk, adequate evidence, can merge
`comment`	Minor concerns, provide feedback
`request_changes`	Issues to address before merging
`needs_discussion`	Requires broader team input

Metadata

API Access

Retrieve signals programmatically via the API.

Get Signal by ID

curl https://axiomo.app/api/signals/ax-owner-repo-123-a1b2c3d4

Analyze a PR

curl -X POST https://axiomo.app/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"url": "https://github.com/owner/repo/pull/123"}'