Validate an expression
const url = 'https://example.com/api/v1/expressions:validate';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"inputs":[{"alias":"example","key":"example"}],"key":"example","owner_kind":"component","site":"calc","source":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/expressions:validate \ --header 'Content-Type: application/json' \ --data '{ "inputs": [ { "alias": "example", "key": "example" } ], "key": "example", "owner_kind": "component", "site": "calc", "source": "example" }'Compiles an expression against a registered site’s environment and answers whether it compiles, with positioned diagnostics, and the site’s bindings, admitted builtins and run budget, all generated from the site’s declaration. For criteria a sample key is required, and types the value (a metric is a number; a property is text, or a bool for a bool property). For calc the key is the rule’s output key, typing the result, and the rule’s inputs (and owner_kind, component by default) give the bindings, each input’s alias bound to the list of its key’s type (a system also binds members, one record per member); an input that is unknown, or an alias that is not an identifier, is reserved or repeats, is a 422; a name the expression uses that no alias binds is a diagnostic carrying that name (unbound); the answer’s value_type so reveals a key’s lane and data type to a rule:read holder, as the rule list already does. Compiles without the engine’s program cache and stores and runs nothing. An unknown site, a missing or unknown key is a 422. Gated by rule:read.
Request Body required
Section titled “Request Body required ”object
A URL to the JSON Schema for this object.
For calc (required there), the rule’s inputs: each bound by its alias, typed by its key (by name or uuid)
object
The name the reduce’s expression binds the input by: an identifier of at most 64, not a keyword, a builtin or list function’s name, or one of the calc site’s own bindings (component, has, members, system, value); unique in the rule
The property or metric the input reads, by name or uuid; the rule holds it by uuid, so a rename changes nothing
The sample key that types the expression (required at both sites). For criteria, the key the rule reads: its lane and data type type the value (a metric is a number; a property is text, or a bool for a bool property). For calc, the rule’s output key: its type is the result the reduce must yield
For calc, what the rule derives on: each input binds by its alias as the list of its current values (one per instance on a component, every member’s on a system); a system also binds members, one record per role-bound member with value.
Where the expression is written: calc, a calc rule’s reduce; criteria, an event rule’s fire_criteria or clear_criteria
The expression
Responses
Section titled “ Responses ”OK
object
A URL to the JSON Schema for this object.
The names the expression may use at the site, generated from the site’s environment
object
What it holds
The name an expression uses (component.name for a nested field)
Its Go type
What one run at the site may spend
object
The wall-clock backstop on a run’s charged work, a Go duration
The most a run may walk: the summed length of what its builtins and operators read, at least one per step
The most a run may allocate, in Expr’s memory units
The builtin functions the site admits
Why it does not compile (one error), or the warnings and hints it compiles with, each with its line and column; empty when it compiles clean
object
The registered diagnostic that gave it (sum-of-bools, float-equality, …), stable across releases and documented on the expressions page; absent for the engine’s own refusals
The 1-based column of the diagnostic; 0 when it has none
A quick fix the diagnostic offers: one text edit
object
The 1-based column it starts at, in characters
The 1-based column it ends before
The 1-based line it ends on
The 1-based line the replaced range starts on
The text that replaces the range
What the fix does, as an action’s label
The 1-based line of the diagnostic; 0 when it has none (a length cap, an input the expression never names)
Where it arose: parse (syntax), type (an unknown name, a mismatched type, a result that is not the site’s), limit (a cap), or lint (a warning or hint on an expression that compiles)
Error refuses the expression; warning (probably wrong) and hint (could be simpler) ride along with one that compiles and never refuse it
The name the expression uses that nothing binds, when that is the fault (an editor offers to bind it)
Whether the expression compiles at the site (no diagnostic of severity error)
The type the site requires the expression to yield
The value type the expression was checked against: for criteria the key’s value, for calc the output’s
Example
{ "$schema": "/api/v1/schemas/ValidateExpressionOutputBody.json", "diagnostics": [ { "phase": "parse", "severity": "error" } ], "value_type": "number"}default
Section titled “default ”Error
object
A URL to the JSON Schema for this object.
A human-readable explanation specific to this occurrence of the problem.
Optional list of individual error details
object
Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’
Error message text
The value at the given location
A URI reference that identifies the specific occurrence of the problem.
HTTP status code
A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
A URI reference to human-readable documentation for the error.
Example
{ "$schema": "/api/v1/schemas/ErrorModel.json", "detail": "Property foo is required but is missing.", "instance": "https://example.com/error-log/abc123", "status": 400, "title": "Bad Request", "type": "about:blank"}