AJSON — Agent JSON

A superset of JSON purpose-built for autonomous agent communication, with deterministic compilation to canonical JSON.

📦 PyPI package: ajson-spec — installed via pip install ajson-spec

📢 Community feedback window: open until 2026-09-15. AJSON is heading to v1.0 and we want your input before we freeze the core. Review the spec, try the CLI, and tell us what breaks. Post via GitHub Discussions or issues. Every substantive comment gets a reply.

---

Why AJSON?

JSON is the lingua franca of AI agents. Every LLM API, every tool-calling framework, every agent protocol speaks JSON. But JSON was designed for machines to parse, not for humans — or other agents — to write.

AJSON fixes this without breaking anything. It's a superset of JSON: every valid JSON file is valid AJSON. Write with superpowers, compile to canonical JSON for runtime.

// AIP Contract in AJSON — comments, multi-line, and reusable references
{
  "contract_name": "Data Process",
  
  "description": """A data processing contract between
two autonomous agents governed by WitnessOS.""",

  // Reusable terms template
  "&terms": {
    "max_retries": 3,
    "sla_seconds": 60,
    "jurisdiction": "AU"
  },

  "contract_terms": {"*terms": null}
}

Compiles to clean, deterministic JSON:

{"contract_name":"Data Process","contract_terms":{"jurisdiction":"AU","max_retries":3,"sla_seconds":60},"description":"A data processing contract between\ntwo autonomous agents governed by WitnessOS."}

---

Features

Feature	JSON	AJSON
Comments (// and /* */)	❌	✅
Multi-line strings ("""...""")	❌	✅
Reusable references (&anchor / *ref)	❌	✅
Deterministic output (sorted keys)	❌ (depends on library)	✅ Always
Self-documenting schemas (@type, @desc)	❌	✅
Valid JSON — zero migration cost	—	✅ Every JSON is valid AJSON
Zero dependencies	—	✅ Pure Python stdlib

---

Quick Start

Install

pip install ajson-spec

Or use directly from source:

python3 -m ajson contract.ajson -o contract.json

CLI Usage

# Compile AJSON to canonical JSON
ajson compile contract.ajson -o contract.json

# Validate an AJSON file
ajson validate contract.ajson

# Expand (show compiled tree)
ajson expand contract.ajson

# Watch mode — recompile on file change
ajson watch contract.ajson -o contract.json

Python API

from ajson import compile_ajson

ajson_text = """
// My contract
{
  "name": "example",
  "description": """Multi-line
description here""",
  "&schema": {"type": "object"},
  "data": {"*schema": null}
}
"""

canonical_json = compile_ajson(ajson_text)
# '{"data":{"type":"object"},"description":"Multi-line\\ndescription here","name":"example"}'

---

Language Reference

Comments

Both // line comments and /* block comments */ are supported. Comments are stripped during compilation and never appear in the output.

{
  // Line comment
  "a": 1,
  
  /* Block
     comment */
  "b": 2
}

Multi-Line Strings

Triple-quoted strings ("""...""") allow multi-line values with automatic dedentation.

{
  "description": """This is a long
  description that spans multiple
  lines without ugly \n escaping."""
}

References (Anchors & Dereferences)

Inspired by YAML anchors, AJSON supports reusable value templates:

{
  // Define once
  "&schema": {
    "type": "object",
    "required": ["id", "timestamp"]
  },
  
  // Use everywhere
  "input": {"*schema": null},
  "output": {"*schema": null}
}

References are resolved at compile time with deep copy semantics. Circular references are detected and rejected.

Inline Annotations

Annotations provide self-documenting schemas that are stripped from the output but available for tooling:

{
  "max_records": @type "uint" 1000,
  "priority":   @type "enum" @default "normal" "high"
}

---

Why Not YAML?

YAML is the natural comparison — it has comments, multi-line strings, and anchors. But YAML has critical problems for agent communication:

Problem	YAML	AJSON
yes → boolean, NO → null	✅ Untrapped pitfalls	❌ Impossible
Indentation-dependent	✅ Fragile	❌ Bracket-delimited
Multiple valid representations	✅ Non-deterministic	❌ Always canonical
Agent framework support	❌ None	✅ Compiles to exactly what agents consume
Deterministic signing	❌ Broken	✅ Natural

AJSON gives you the ergonomics of YAML with the determinism and agent-compatibility of JSON.

---

Use Cases

• AIP (Agent Interaction Protocol): Write contract templates with inline documentation, compile to signed JSON for agent execution
• WitnessOS governance: Self-documenting compliance manifests that compile to verifiable evidence receipts
• ACI capability descriptions: Rich capability files with reusable schema references
• Agent-to-agent manifests: Any structured data that agents exchange, with comments for human review

---

Integration with Empire Labs Stack

AJSON is the authoring format for the Empire Stack — a complete stack for autonomous agent commerce:

Layer	Project	What It Does
✍️ Author	AJSON ← you are here	Write manifests with comments, refs, multi-line — compiles to canonical JSON
🔍 Discover	ACI	Autonomous Company Interface — describes orgs to agents (who you are, what you offer)
🤝 Interact	AIP	Agent Interaction Protocol — negotiates contracts and executes interactions

→ ACI discovers, AIP negotiates, AJSON writes it all down.

---

Roadmap

Version	Features
v0.1 (current)	Comments, multi-line strings, references, canonical output, CLI
v0.2	Inline schema annotations, @type/@desc/@default support
v0.3	File inclusion (@include "schema.ajson"), multi-file compilation
v0.4	MCP server (agents use AJSON directly via MCP tools)
v1.0	Stable spec, language server, IDE integration

---

Acknowledgements

This implementation uses the Python standard library only. There are no third-party runtime dependencies, so there is no upstream code to attribute.

AJSON is an original design by Empire Labs Pty Ltd. It has not been reviewed, approved or certified by any standards body.

---

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

This project follows the ACI Code of Conduct.

---

🍻 Buy the Empire a Pint

If AJSON saved your agents from YAML hell and JSON purgatory, buy the Empire a pint. We like to split the G.

Pay what you want. No tiers, no rewards, no strings. Just a cold pint and a thank you from the Empire.

Every donation helps keep this project sovereign, dependency-free, and maintained on Empire time.

---

License

AJSON is open source under the MIT License. See LICENSE for details.

Copyright (c) 2026 Empire Labs Pty Ltd

Built and maintained by Security Division, Empire Labs Pty Ltd

---

_{Part of the WitnessOS launch family: eu-ai-act-compliance-grade · witnessos-verifier · agent-interaction-specs · aci-spec · aip-spec · ajson — Empire Labs Pty Ltd}

Dependencies

Runtime dependencies are declared in pyproject.toml (Python 3.10+). The dependency set is kept minimal. SCA is enforced in CI via OSV-Scanner.

Building from source

git clone https://github.com/narko4u/ajson.git
cd ajson
python -m venv .venv && source .venv/bin/activate
pip install -e .

Verifying releases

Release assets (wheel, source distribution, sbom.cdx.json, SHA256SUMS, plus the published Docker image) are attached to the GitHub release. To verify integrity and authorship:

1. Download SHA256SUMS and the assets for the release tag.

2. Verify checksums: sha256sum -c SHA256SUMS

3. Verify the Sigstore signature on an asset (keyless, OIDC-bound to this repository's release.yml workflow):

   cosign verify-blob --certificate <asset>.pem --signature <asset>.sig --certificate-identity-regexp "^https://github.com/narko4u/ajson/.github/workflows/release.yml@refs/tags/v.*" --certificate-oidc-issuer "https://token.actions.githubusercontent.com" <asset>