Arazzo Runtime Expressions allows values to be defined based on information that will be available within the HTTP message in an actual API call, or within objects serialized from the Arazzo document such as workflows or steps.
@swaggerexpert/arazzo-runtime-expression is a parser, validator, extractor and interpolator for Arazzo Runtime Expressions.
It supports Runtime Expressions defined in following Arazzo specification versions:
|
Get professionally supported @swaggerexpert/arazzo-runtime-expression with Tidelift Subscription. |
You can install @swaggerexpert/arazzo-runtime-expression using npm:
$ npm install @swaggerexpert/arazzo-runtime-expression@swaggerexpert/arazzo-runtime-expression currently supports extraction, interpolation, parsing and validation.
Both parser and validator are based on a superset of ABNF (SABNF)
and use apg-lite parser generator.
Arazzo embeds Runtime Expressions into string values surrounded with {} curly braces.
To extract Runtime Expressions from this embedded form, use the extract function.
The function returns an array of all extracted expressions, which can be used for further parsing or validation.
import { extract, test, parse } from '@swaggerexpert/arazzo-runtime-expression';
// Extract single expression
extract('{$request.header.accept}'); // => ['$request.header.accept']
// Extract multiple expressions from a template string
extract('client_id={$inputs.clientId}&grant_type={$inputs.grantType}');
// => ['$inputs.clientId', '$inputs.grantType']
// No expressions found
extract('no expressions here'); // => []
// Use extracted expressions
const expressions = extract('{$url}');
test(expressions[0]); // => true
parse(expressions[0]); // => { result, tree }Arazzo embeds Runtime Expressions into string values surrounded with {} curly braces.
To render such a template string, use the interpolate function. It replaces every {expression}
occurrence with a value produced by a resolver callback, while preserving all literal content.
Because this package is a parser and has no knowledge of the runtime context (HTTP messages, workflow
inputs/outputs, etc.), you supply the resolution logic through the resolver callback. The callback
receives the raw expression (e.g. $inputs.name) and returns its value.
import { interpolate } from '@swaggerexpert/arazzo-runtime-expression';
// Single expression
interpolate('Hello {$inputs.name}!', () => 'world'); // => 'Hello world!'
// Multiple expressions resolved from a lookup table
const values = { '$inputs.clientId': 'abc', '$inputs.grantType': 'authorization_code' };
interpolate('client_id={$inputs.clientId}&grant_type={$inputs.grantType}', (expression) => values[expression]);
// => 'client_id=abc&grant_type=authorization_code'
// Strings without expressions are returned unchanged
interpolate('no expressions here', () => 'X'); // => 'no expressions here'Resolved values are stringified before being spliced into the template. The default stringification
renders undefined and null as an empty string, uses strings as-is, serializes objects with
JSON.stringify and coerces everything else via String(). This can be customized via the
stringify option.
import { interpolate } from '@swaggerexpert/arazzo-runtime-expression';
interpolate('{$request.body}', () => ({ id: 1 }), {
stringify: (value) => JSON.stringify(value, null, 2),
});
// => '{\n "id": 1\n}'Parsing a Runtime Expression is as simple as importing the parse function and calling it.
import { parse } from '@swaggerexpert/arazzo-runtime-expression';
const parseResult = parse('$request.header.accept');parseResult variable has the following shape:
{
result: <ParseResult['result']>,
tree: <ParseResult['tree']>,
stats: <ParseResult['stats']>,
trace: <ParseResult['trace']>,
}
TypeScript typings are available for all fields attached to parse result object returned by the parse function.
@swaggerexpert/arazzo-runtime-expression provides several translators to convert the parse result into different tree representations.
Concrete Syntax Tree (Parse tree) representation is available on parse result
when instance of CSTTranslator is provided via a translator option to the parse function.
CST is suitable to be consumed by other tools like IDEs, editors, etc...
import { parse, CSTTranslator } from '@swaggerexpert/arazzo-runtime-expression';
const { tree: cst } = parse('$request.header.accept', { translator: new CSTTranslator() });CST tree has a shape documented by TypeScript typings (CSTNode).
Default translator. Abstract Syntax Tree representation is available on parse result
by default or when instance of ASTTranslator is provided via a translator option to the parse function.
AST is suitable to be consumed by implementations that need to analyze the structure of the runtime expression.
import { parse } from '@swaggerexpert/arazzo-runtime-expression';
const { tree: ast } = parse('$request.header.accept');or
import { parse, ASTTranslator } from '@swaggerexpert/arazzo-runtime-expression';
const { tree: ast } = parse('$request.header.accept', { translator: new ASTTranslator() });AST tree has a shape documented by TypeScript typings (ASTNode).
import { parse, XMLTranslator } from '@swaggerexpert/arazzo-runtime-expression';
const { tree: xml } = parse('$request.header.accept', { translator: new XMLTranslator() });parse function returns additional statistical information about the parsing process.
Collection of the statistics can be enabled by setting stats option to true.
import { parse } from '@swaggerexpert/arazzo-runtime-expression';
const { stats } = parse('$request.header.accept', { stats: true });
stats.displayStats(); // returns operator statistics as stringparse function returns additional tracing information about the parsing process.
Tracing can be enabled by setting trace option to true. Tracing is essential
for debugging failed parses or analyzing rule execution flow.
import { parse } from '@swaggerexpert/arazzo-runtime-expression';
const { result, trace } = parse('$invalid', { trace: true });
result.success; // false
trace.displayTrace(); // returns trace information as stringTracing also allows you to infer expected tokens at a failure point. This is useful for generating meaningful syntax error messages.
import { parse } from '@swaggerexpert/arazzo-runtime-expression';
const { trace } = parse('$invalid', { trace: true });
const expectations = trace.inferExpectations();
console.log(expectations.toString()); // e.g., "expected '$url', '$method', '$statusCode', '$request.', ..."Validating a Runtime Expression is as simple as importing the test function and calling it.
import { test } from '@swaggerexpert/arazzo-runtime-expression';
test('$request.header.accept'); // => true
test('nonsensical string'); // => false@swaggerexpert/arazzo-runtime-expression provides a structured error class hierarchy,
enabling precise error handling across runtime expression operations.
import { ArazzoRuntimeExpressionError, ArazzoRuntimeExpressionParseError } from '@swaggerexpert/arazzo-runtime-expression';ArazzoRuntimeExpressionError is the base class for all errors. ArazzoRuntimeExpressionParseError is thrown when parsing fails and includes additional context about the expression that failed to parse.
import { parse, ArazzoRuntimeExpressionParseError } from '@swaggerexpert/arazzo-runtime-expression';
try {
parse(123); // non-string input
} catch (error) {
if (error instanceof ArazzoRuntimeExpressionParseError) {
console.log(error.runtimeExpression); // the expression that failed
}
}New grammar instance can be created in following way:
import { Grammar } from '@swaggerexpert/arazzo-runtime-expression';
const grammar = new Grammar();To obtain original ABNF (SABNF) grammar as a string:
import { Grammar } from '@swaggerexpert/arazzo-runtime-expression';
const grammar = new Grammar();
grammar.toString();
// or
String(grammar);The runtime expression is defined by the following ABNF syntax
; Arazzo runtime expression ABNF syntax
; Rule order mirrors the Arazzo 1.1.0 specification (Runtime Expressions section).
; Top-level expression
expression = (
"$url" /
"$method" /
"$statusCode" /
"$request." source /
"$response." source /
"$message." source /
"$inputs." inputs-reference /
"$outputs." outputs-reference /
"$steps." steps-reference /
"$workflows." workflows-reference /
"$sourceDescriptions." source-reference /
"$components." components-reference /
"$self"
)
; Request/Response/Message sources
source = ( header-reference / query-reference / path-reference / body-reference / payload-reference )
header-reference = "header." token
query-reference = "query." name
path-reference = "path." name
body-reference = "body" ["#" json-pointer ]
payload-reference = "payload" ["#" json-pointer ]
; Input/Output references
inputs-reference = input-name [ "#" json-pointer ]
outputs-reference = output-name [ "#" json-pointer ]
input-name = identifier
output-name = identifier
; Steps expressions
steps-reference = step-id ".outputs." output-name [ "#" json-pointer ]
step-id = identifier-strict
; Workflows expressions
workflows-reference = workflow-id "." workflow-field "." workflow-field-name [ "#" json-pointer ]
workflow-id = identifier-strict
workflow-field = "inputs" / "outputs"
workflow-field-name = identifier
; Source descriptions expressions
source-reference = source-name "." source-reference-id
source-name = identifier-strict
source-reference-id = 1*CHAR
; operationIds have no character restrictions in OpenAPI/AsyncAPI
; Components expressions
components-reference = component-type "." component-name
component-type = "parameters" / "successActions" / "failureActions"
component-name = identifier
; Identifier rules
identifier-strict = 1*( ALPHA / DIGIT / "-" / "_" )
; Alphanumeric with hyphens, underscores (no dots)
identifier = 1*( ALPHA / DIGIT / "." / "-" / "_" )
; Alphanumeric with dots, hyphens, underscores
; Unconstrained name rule for query/path references
name = *( CHAR )
; JSON Pointer (RFC 6901, adapted)
; { (%x7B) and } (%x7D) are excluded from 'unescaped' for unambiguous embedded expression parsing
json-pointer = *( "/" reference-token )
reference-token = *( unescaped / escaped )
unescaped = %x00-2E / %x30-7A / %x7C / %x7F-10FFFF
; %x2F ('/'), %x7E ('~'), %x7B ('{'), %x7D ('}') are excluded
escaped = "~" ( "0" / "1" )
; representing '~' and '/', respectively
; https://datatracker.ietf.org/doc/html/rfc7230#section-3.2.6
token = 1*tchar
tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*"
/ "+" / "-" / "." / "^" / "_" / "`" / "|" / "~"
/ DIGIT / ALPHA
; any VCHAR, except delimiters
; https://www.rfc-editor.org/rfc/rfc7159#section-7
CHAR = unescape /
escape (
%x22 / ; " quotation mark U+0022
%x5C / ; \ reverse solidus U+005C
%x2F / ; / solidus U+002F
%x62 / ; b backspace U+0008
%x66 / ; f form feed U+000C
%x6E / ; n line feed U+000A
%x72 / ; r carriage return U+000D
%x74 / ; t tab U+0009
%x75 4HEXDIG ) ; uXXXX U+XXXX
escape = %x5C ; \
unescape = %x20-21 / %x23-5B / %x5D-7A / %x7C / %x7E-10FFFF
; %x7B ('{') and %x7D ('}') are excluded from 'unescape'
; Grammar for parsing template strings with embedded expressions
expression-string = *( literal-char / embedded-expression )
embedded-expression = "{" expression "}"
literal-char = %x00-7A / %x7C / %x7E-10FFFF ; anything except { (%x7B) and } (%x7D)
; https://datatracker.ietf.org/doc/html/rfc5234#appendix-B.1
ALPHA = %x41-5A / %x61-7A ; A-Z / a-z
DIGIT = %x30-39 ; 0-9
HEXDIG = DIGIT / "A" / "B" / "C" / "D" / "E" / "F"The name identifier is case-sensitive, whereas token is not.
The table below provides examples of runtime expressions and examples of their use in a value:
| Source Location | example expression | notes |
|---|---|---|
| HTTP Method | $method |
The allowable values for the $method will be those for the HTTP operation. |
| Requested media type | $request.header.accept |
|
| Request parameter | $request.path.id |
Request parameters MUST be declared in the parameters section of the parent operation or they cannot be evaluated. This includes request headers. |
| Request body property | $request.body#/user/uuid |
In operations which accept payloads, references may be made to portions of the requestBody or the entire body. |
| Request URL | $url |
|
| Response value | $response.body#/status |
In operations which return payloads, references may be made to portions of the response body or the entire body. |
| Response header | $response.header.Server |
Single header values only are available. |
| Message payload value | $message.payload#/user/id |
For event-driven (AsyncAPI) operations, references may be made to portions of the message payload or the entire payload. |
| Self URI | $self |
References the canonical URI of the current Arazzo Description. |
| Workflow input | $inputs.username |
Single input values only are available. |
| Workflow input property | $inputs.customer#/firstName |
To access nested properties within an input object, use JSON Pointer syntax. |
| Step output value | $steps.someStepId.outputs.pets |
In situations where the output named property return payloads, references may be made to portions of the response body (e.g., $steps.someStepId.outputs.pets#/0/id) or the entire body. |
| Workflow output value | $outputs.bar or $workflows.foo.outputs.bar |
In situations where the output named property return payloads, references may be made to portions of the response body (e.g., $workflows.foo.outputs.mappedResponse#/name) or the entire body. |
| Source description reference | $sourceDescriptions.petstore.getPetById |
References an operationId or workflowId from the named source description. |
| Components parameter | $components.parameters.foo |
Accesses a foo parameter defined within the Components Object. |
| Components action | $components.successActions.bar |
Accesses a success or failure action defined within the Components Object. |
Runtime expressions preserve the type of the referenced value.
Expressions can be embedded into string values by surrounding the expression with {} curly braces.
@swaggerexpert/arazzo-runtime-expression is licensed under Apache 2.0 license.
@swaggerexpert/arazzo-runtime-expression comes with an explicit NOTICE file
containing additional legal notices and information.
