JSON Sidecar Pattern

Get the pattern

Add structured JSON output to any AI task.

Download JSON sidecar pattern View on GitHub

The JSON sidecar pattern instructs an AI assistant to produce structured JSON alongside human-readable markdown during any task. The AI writes both simultaneously — no post-processing needed.

The insight most people miss

Most people treat AI output as “the response” — whatever appears in the conversation. They don’t realise you can instruct the AI to:

• Write structured data to a file while also explaining findings in prose
• Append JSON objects to a growing file as it works through a task
• Maintain a consistent schema across dozens of findings
• Produce output that feeds directly into CI/CD, dashboards, and tracking tools

It’s a prompt instruction, not a tool feature. You just tell the AI to do it.

The core instruction

Add this to any audit MAP, prompt, or task instruction:

## Output Requirements

For each finding, produce TWO outputs:

1. **Human-readable**: Append the finding in markdown to checkpoint.md
2. **Machine-readable**: Append a JSON object to findings.json

That’s it. The AI will produce both outputs for every finding.

Audit finding schema

{
  "id": "SEC-001",
  "lens": "security",
  "severity": "HIGH",
  "confidence": "MEDIUM",
  "decision": "SQL injection via string concatenation",
  "file": "src/api/users.ts",
  "line": 47,
  "evidence": "query = 'SELECT * FROM users WHERE id=' + userId",
  "reasoning": [
    "User input reaches SQL directly",
    "No parameterised query"
  ],
  "alternatives_rejected": [
    "Considered ORM — confirmed raw SQL"
  ],
  "weaknesses": [
    "Only tested GET endpoint"
  ],
  "remediation_hint": "Use parameterised queries",
  "timestamp": "2026-03-06T14:30:00Z"
}

This schema maps directly to the Finding Contract — the same 10 required fields, in machine-readable form.

What JSON sidecar enables

Use case	How
Diff between audit runs	Compare findings.json from audit v1 to audit v2 — see what’s new, fixed, or regressed
CI/CD integration	Parse JSON, fail the build on any CRITICAL finding
Dashboards	Feed findings into Grafana, Metabase, or any reporting tool
Trend tracking	Track severity distribution across audits over time
Remediation tracking	Match finding IDs to git commits that fix them
Cross-project analysis	Aggregate findings across all projects in an organisation
Compliance reporting	Filter by regulation (GDPR, COPPA, HIPAA) and export

Beyond audits

The JSON sidecar pattern works for any AI task that produces structured findings. Here are examples:

Compliance checks

{
  "id": "GDPR-001",
  "regulation": "GDPR",
  "article": "Art. 17 — Right to erasure",
  "status": "NON_COMPLIANT",
  "evidence": "No deletion endpoint for user data",
  "file": "src/api/users.ts",
  "remediation": "Add DELETE /api/users/:id endpoint"
}

Code review

{
  "id": "CR-001",
  "type": "suggestion",
  "category": "performance",
  "file": "src/services/search.ts",
  "line": 89,
  "current": "Array.filter().map() creates intermediate array",
  "suggested": "Single reduce() pass",
  "impact": "Reduces allocations on large datasets"
}

Test gap analysis

{
  "id": "GAP-001",
  "untested_function": "processPayment",
  "file": "src/services/payment.ts",
  "risk": "HIGH",
  "reason": "Financial operation with no unit tests",
  "suggested_tests": [
    "Happy path: valid payment succeeds",
    "Invalid card: returns error",
    "Idempotency: duplicate request doesn't double-charge"
  ]
}

Documentation drift

{
  "id": "DRIFT-001",
  "doc_file": "README.md",
  "doc_line": 45,
  "claim": "Run npm start to launch server",
  "reality": "package.json uses bun run dev",
  "severity": "MEDIUM"
}

Migration/upgrade tracking

{
  "id": "MIG-001",
  "dependency": "express",
  "current_version": "4.18.2",
  "target_version": "5.0.0",
  "breaking_changes": [
    "req.host no longer includes port",
    "app.del() removed"
  ],
  "files_affected": ["src/server.ts", "src/middleware/cors.ts"],
  "effort": "LOW"
}

Implementation tips

• Tell the AI explicitly: “Write each finding as JSON to findings.json AND as markdown to checkpoint.md”
• Incremental writes: “Append after each finding” prevents data loss if the session ends
• Include the schema: Put the full schema in the prompt — the AI follows it consistently
• Validate: After completion, run jq . findings.json to verify valid JSON
• Aggregate multi-pass: jq -s 'add' pass1.json pass2.json > all-findings.json

Full reference

The complete JSON sidecar pattern with all schemas, checkpoint summary format, and implementation checklist is at json-sidecar-pattern.md.