AJSON

September 13, 2026 · View on GitHub

AJSON — Agent JSON

AJSON — Agent JSON

OpenSSF Best Practices - Baseline 1 OpenSSF Best Practices - Baseline 2 OpenSSF Best Practices - Baseline 3

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

PyPI version Tests License: MIT Python 3.9+ Built by Empire Labs

📢 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

FeatureJSONAJSON
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:

ProblemYAMLAJSON
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:

LayerProjectWhat It Does
✍️ AuthorAJSON ← you are hereWrite manifests with comments, refs, multi-line — compiles to canonical JSON
🔍 DiscoverACIAutonomous Company Interface — describes orgs to agents (who you are, what you offer)
🤝 InteractAIPAgent Interaction Protocol — negotiates contracts and executes interactions

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

Roadmap

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

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.

ko-fi

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 by Empire Labs Pty Ltd | Maintained by Sovereign

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>