Skip to content

json-envelope.md

Latest commit

 

History

History
135 lines (104 loc) · 3.49 KB

json-envelope.md

File metadata and controls

135 lines (104 loc) · 3.49 KB
Raw

JSON Envelope Contract

All animus commands that accept --json wrap their output in the animus.cli.v1 envelope. This contract provides a stable, machine-readable interface for scripts, CI pipelines, and MCP tool integrations.

Schema Identifier

The schema field is always the string literal "animus.cli.v1". This value is defined as a constant (CLI_SCHEMA_ID) in the protocol crate and is shared across all producers.

Success Envelope

Written to stdout.

{
  "schema": "animus.cli.v1",
  "ok": true,
  "data": <T>
}
Field Type Description
schema string Always "animus.cli.v1"
ok boolean Always true for success
data T Command-specific payload (object, array, or simple value)

The data field varies by command. For simple acknowledgments it may be {"message": "ok"}. For queries it contains the full result object or array.

Examples

Simple acknowledgment:

{
  "schema": "animus.cli.v1",
  "ok": true,
  "data": { "message": "task TASK-001 status updated to in-progress" }
}

Query result:

{
  "schema": "animus.cli.v1",
  "ok": true,
  "data": {
    "id": "TASK-001",
    "title": "Fix login bug",
    "status": "in-progress",
    "priority": "high"
  }
}

Error Envelope

Written to stderr.

{
  "schema": "animus.cli.v1",
  "ok": false,
  "error": {
    "code": "<error_code>",
    "message": "<human-readable message>",
    "exit_code": <N>
  }
}
Field Type Description
schema string Always "animus.cli.v1"
ok boolean Always false for errors
error.code string Machine-readable error category (see Exit Codes)
error.message string Human-readable error description
error.exit_code integer Process exit code (1-5)
error.details object? Optional structured context (present only when available)

Error Codes

code exit_code Meaning
"internal" 1 Unclassified or unexpected error
"invalid_input" 2 Bad arguments or values
"not_found" 3 Resource does not exist
"conflict" 4 State conflict
"unavailable" 5 Service unreachable

Error with Details

{
  "schema": "animus.cli.v1",
  "ok": false,
  "error": {
    "code": "internal",
    "message": "daemon failed to start",
    "exit_code": 1,
    "details": {
      "startup_log_tail": "error: panic in scheduler loop"
    }
  }
}

The details field is omitted (not present) when no structured context is available.

Versioning

The schema field enables future evolution. Consumers should check schema == "animus.cli.v1" before parsing. If the schema changes (e.g., "animus.cli.v2"), the envelope structure may differ.

Within animus.cli.v1, the envelope shape is stable:

  • ok, schema are always present.
  • Success always has data.
  • Error always has error with code, message, and exit_code.

Serialization

The JSON envelope is serialized in compact form (no pretty-printing, no newlines) to ensure single-line output suitable for line-oriented log processing.

Usage with --json

# Capture success data
data=$(animus subject get --kind task --id task:TASK-001 --json 2>/dev/null)
echo "$data" | jq '.data.status'

# Capture error
animus subject get --kind task --id task:NONEXISTENT --json 2>err.json
cat err.json | jq '.error.code'

See also: Exit Codes, Global Flags.