JSON — AEL documentation

Programs in AEL, the Agent Engineering Language, will 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 (command names may change before launch). Wherever your program reads JSON, the JSON will be read into a value of a type you declared, and checked against that type, before your code sees it. You will not pick values out of untyped JSON by hand.

Status

Planned for AEL Beta 0.0.1. AEL is not available yet.

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

Limits

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

A refusal will name 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 will take typed inputs and return typed outputs. When an agent is called with JSON, over HTTP or from another program, each input will be checked against the type you declared for it, and each output will be written from your typed value. See Typed inputs and outputs.

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

Logs

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

Command output

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

Preview syntax — may change before launch

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 will never change. See JSON Schemas.

Not yet described

How structs and enums of your own will be spelled in JSON, and the operations for reading and writing JSON in your own code, will be published when the library is final.