Documentation

baml.json.path

Navigates a jq-style selector into a `json` value and coerces the leaf to `T`.

Reference version

Signature

function baml.json.path<T>(j: baml.json.json, selector: string) -> T throws baml.json.PathError

Navigates a jq-style selector into a json value and coerces the leaf to T.

Selectors start with . or [. Dot and quoted-bracket steps address object fields; integer bracket steps address arrays. A dot step runs to the next . or [, so a field name containing either must use the bracket form: ["a.b"]. Bracket keys accept single or double quotes, and take \ as a literal escape for one following character. Indices are non-negative and absolute — there is no jq-style negative indexing, and [-1] reports out of bounds. A bare . selects nothing, so "." is the identity selector.

The leaf is coerced with to<T>, so baml.FromJson overrides apply and T may be a whole class, not only a scalar. Every way this can fail — malformed selector, missing field, wrong shape, out-of-range index, leaf that will not decode — collapses into one PathError, which is what makes path_or a clean total wrapper.

Throws

  • baml.json.PathError if the selector is malformed, if a step does not resolve, or if the selected leaf does not decode to T.

Examples

let doc: json = { "users": [{ "name": "Ada", "age": 36 }] };
assert.equal(baml.json.path<string>(doc, ".users[0].name"), "Ada");
assert.equal(baml.json.path<int>(doc, "[\"users\"][0][\"age\"]"), 36);

Source:<builtin>/baml/ns_json/json.bamlbytes 14149–17341