JSON — AEL documentation

JSON

Programs in AEL, the Agent Engineering Language, meet JSON wherever they meet the outside world: the inputs and outputs of agents, request and response bodies, structured model output, log files and the machine-readable output of the ael command. Wherever your program reads JSON, the JSON is read into a value of a type you declared, and checked against that type, before your code sees it. You do not pick values out of untyped JSON by hand.

Built-in types in JSON

AEL type	JSON	Example
`()`	`null`	`null`
`bool`	`true` or `false`	`true`
`i8` … `i64`, `u8` … `u64`	An integer within the type's range.	`8080`
`Str<N>`	A string of at most `N` bytes of UTF-8.	`"urgent"`
`[T; N]`	An array of exactly `N` values.	`[12, 7, 30]`
`Vec<T, N>`	An array of at most `N` values.	`[200, 404]`
`Option<T>`	`null`, or the spelling of `T`.	`"urgent"` or `null`
`Result<T, E>`	An object with exactly one member, `ok` or `err`.	`{"ok": 42}` or `{"err": "not found"}`

The rules

Integers are exact. An integer must fit its type, and a number with a fraction or an exponent is refused.
Text is checked, not changed. A string must be valid UTF-8 in the composed Unicode form (NFC), contain no NUL character and fit the capacity of its type. AEL does not trim, normalize or shorten it for you: a string that breaks a rule is refused.
Arrays and lists keep their bounds. An array needs exactly its length; a list accepts up to its capacity.
null has one meaning. Option<()> and an Option of an Option are refused as JSON types, because null could stand for either level. Choose a different type instead.
Missing is not the same as null. An optional input that is left out and an input given as null are treated differently: a declared default applies only to an input that is left out.
No surprises in objects. Unknown fields and duplicate keys are refused.

Limits

Every JSON document has a maximum size, a maximum nesting depth and a maximum number of items, and they are checked before any value is built. A document that breaks a limit or a rule is refused as a whole.

A refusal names the rule it broke and the position of the first problem, written as a JSON Pointer such as /lines/2.

Agent inputs and outputs

Agents take typed inputs and return typed outputs. When an agent is called with JSON, over HTTP or from another program, each input is checked against the type you declared for it, and each output is written from your typed value. See Typed inputs and outputs.

Output from a model goes through the same checks, in order: the response must be complete, it is decoded into your type, and then your own output checks run. An output that ended early or does not match your type never counts as a success. When you want the model's text as it is, you can ask for the raw result instead.

Logs

The file log sink writes JSON Lines: one event per line, each a complete JSON object. See Console and logging.

Command output

Every ael command takes --json for machine-readable output. Diagnostics then follow the published diagnostic schema. Machine-readable output and Diagnostics describe both.

ael check --json

Published JSON Schemas

The JSON Schemas for AEL's project, package and agent files are published on docs.ael.openeng.ai, each at an address that never changes. See JSON Schemas.