JSON Schema - Codanna

Codanna is a local code intelligence MCP server and CLI for AI coding agents. All CLI commands with --json output follow the Envelope schema (version 1.0.0) — type, status, code, exit_code, message, hint, data, meta.

Envelope Structure

{
  "type": "result",
  "status": "success",
  "code": "OK",
  "exit_code": 0,
  "message": "Found 1 symbol(s)",
  "hint": "Symbol found with full context...",
  "data": [...],
  "meta": {
    "schema_version": "1.0.0",
    "entity_type": "symbol",
    "count": 1,
    "query": "Parser"
  }
}

Envelope Fields

Field	Type	Required	Description
`type`	string	yes	`result`, `error`
`status`	string	yes	`success`, `not_found`, `partial_success`, `error`
`code`	string	yes	`OK`, `NOT_FOUND`, `PARSE_ERROR`, `INDEX_ERROR`, `INVALID_QUERY`, `INTERNAL_ERROR`
`exit_code`	integer	yes	Unix exit code: 0=success, 1=not_found, 2=error
`message`	string	yes	Human-readable description
`hint`	string	no	Suggested next action
`data`	varies	yes	Payload (null on error)
`error`	object	no	Error details with `suggestions` array
`meta`	object	yes	Metadata

Meta Fields

Field	Type	Description
`schema_version`	string	Always `1.0.0`
`entity_type`	string	`symbol`, `search_result`, `callers`, `calls`, `document`
`count`	integer	Number of items
`query`	string	Original query
`lang`	string	Language filter applied

Data Shapes

The data field structure depends on the command. Check meta.entity_type to determine the shape.

symbol (find_symbol, describe)

{
  "data": [{
    "symbol": {
      "id": 5156,
      "name": "Parser",
      "kind": "Struct",
      "file_path": "src/parser.rs",
      "range": {
        "start_line": 88,
        "end_line": 118
      },
      "signature": "pub struct Parser",
      "visibility": "Public",
      "language_id": "rust"
    },
    "file_path": "src/parser.rs",
    "relationships": {
      "defines": [...],
      "calls": [...],
      "called_by": [...]
    }
  }]
}

data is an array even for a single match. calls/called_by entries are [symbol, metadata] pairs; the metadata object carries line (1-indexed), column (0-indexed), receiver, and static_call.

search_result (search_symbols)

{
  "data": [{
    "symbol": {
      "id": 123,
      "name": "parse",
      "kind": "Function",
      "file_path": "src/parser.rs",
      "line": 42,
      "language_id": "rust"
    },
    "score": 0.95,
    "highlights": ["parse"]
  }]
}

callers/calls (get_calls, find_callers)

{
  "data": [{
    "id": 123,
    "name": "process",
    "kind": "Function",
    "file_path": "src/lib.rs",
    "range": {"start_line": 50, "end_line": 75},
    "call_line": 62,
    "call_column": 8
  }]
}

Every call edge carries its call site: call_line is 1-indexed (editor coordinate), call_column is 0-indexed (machine coordinate, like range columns). range objects stay 0-indexed throughout.

document (search_documents)

{
  "data": [{
    "chunk_id": 150,
    "collection": "docs",
    "source_path": "/path/to/doc.md",
    "content_preview": "Matched content...",
    "similarity": 0.398
  }]
}

Error Response

{
  "type": "error",
  "status": "error",
  "code": "INVALID_QUERY",
  "exit_code": 2,
  "message": "Ambiguous: found 100 symbol(s) named 'parse'",
  "hint": "Use: codanna retrieve callers symbol_id:<id>",
  "data": null,
  "error": {
    "suggestions": ["symbol_id:587", "symbol_id:3702"]
  }
}

Machine-Readable Schema

For code generation or tooling integration, the formal JSON Schema is available at:

https://docs.codanna.sh/schema/envelope.schema.json

Next Steps

Unix Piping

Consume the envelope with jq, xargs, and Unix tools.

CLI Reference

Commands that emit JSON envelopes.

​Envelope Structure

​Envelope Fields

​Meta Fields

​Data Shapes

​symbol (find_symbol, describe)

​search_result (search_symbols)

​callers/calls (get_calls, find_callers)

​document (search_documents)

​Error Response

​Machine-Readable Schema

​Next Steps

Unix Piping

CLI Reference

Envelope Structure

Envelope Fields

Meta Fields

Data Shapes

symbol (find_symbol, describe)

search_result (search_symbols)

callers/calls (get_calls, find_callers)

document (search_documents)

Error Response

Machine-Readable Schema

Next Steps