@swaggerexpert/arazzo-runtime-expression

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.

Getting started

Installation

You can install @swaggerexpert/arazzo-runtime-expression using npm:

 $ npm install @swaggerexpert/arazzo-runtime-expression

Usage

@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.

Extraction

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 }

By default, extraction is strict and all-or-nothing: the whole string must consist of literal text and valid {expression} patterns. Literal { and } characters are not allowed, so if any part of the string doesn't fit (e.g. JSON braces, a stray } or an invalid expression), an empty array is returned, even when other parts contain valid expressions.

extract('{"petId": "{$inputs.petId}"}'); // => []
extract('x={$inputs.}&y={$inputs.ok}'); // => []

With strict: false, extraction is tolerant. An expression attempt is a span that starts with {$ and ends at the first }. Everything else, including any { not followed by $ and stray }, is literal text. Every valid expression is extracted; invalid attempts (e.g. {$inputs.}, {$foo.bar}) are skipped.

If another { or the end of the string comes before the closing }, the attempt is unterminated and is skipped as well. Scanning then resumes at that {, so it can start a new attempt: {$a{$inputs.ok} contains the unterminated attempt {$a followed by the valid {$inputs.ok}.

extract('{"petId": "{$inputs.petId}"}', { strict: false }); // => ['$inputs.petId']
extract('x={$inputs.}&y={$inputs.ok}', { strict: false }); // => ['$inputs.ok']
extract('{{$inputs.ok}}', { strict: false }); // => ['$inputs.ok']
extract('{$a{$inputs.ok}', { strict: false }); // => ['$inputs.ok']
extract('{$url', { strict: false }); // => []

For every string that strict mode accepts, tolerant mode returns the same result.

Interpolation

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}'

Like extraction, interpolation is strict by default: if the template doesn't parse as a whole (e.g. it contains JSON braces, a stray } or an invalid expression), it is returned unchanged and no expression is substituted.

With strict: false, interpolation is tolerant and follows the same rules as tolerant extraction: every valid {$...} span is substituted and all other text is kept as it is. This makes it possible to interpolate templates that contain literal braces, such as JSON payloads.

Every invalid or unterminated expression attempt is passed to the onError callback, and its return value replaces the span in the output. By default, the span is left unchanged. Throw from onError to fail instead. onError is ignored in strict mode.

The callback receives { text, start, length, error }:

text - the raw span, including braces (e.g. {$inputs.}), or without the closing brace when unterminated (e.g. {$url)
start, length - position of the span in the template
error - an ArazzoRuntimeExpressionParseError describing the attempt; its runtimeExpression property is the span without braces (e.g. $inputs.)

import { interpolate } from '@swaggerexpert/arazzo-runtime-expression';

const values = { '$inputs.petId': 42 };
const resolver = (expression) => values[expression];

// Literal braces are kept as they are
interpolate('{"petId": {$inputs.petId}}', resolver, { strict: false });
// => '{"petId": 42}'

// Invalid expression attempts are left unchanged by default
interpolate('a={$inputs.petId}&b={$inputs.}', resolver, { strict: false });
// => 'a=42&b={$inputs.}'

// Throw to fail on invalid expression attempts
interpolate('a={$inputs.petId}&b={$inputs.}', resolver, {
  strict: false,
  onError: ({ text, start, length, error }) => {
    throw error; // ArazzoRuntimeExpressionParseError: Invalid runtime expression "{$inputs.}" at position 20
  },
});

Parsing

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.

Translators

@swaggerexpert/arazzo-runtime-expression provides several translators to convert the parse result into different tree representations.

CST translator

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).

AST translator

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).

XML translator

import { parse, XMLTranslator } from '@swaggerexpert/arazzo-runtime-expression';

const { tree: xml } = parse('$request.header.accept', { translator: new XMLTranslator() });

Statistics

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 string

Tracing

parse 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 string

Tracing 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.', ..."

Validation

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

Errors

@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
  }
}

Grammar

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);

More about Arazzo runtime expressions

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 "." ( workflows-value-reference / workflows-steps-reference )
workflows-value-reference = workflow-field "." workflow-field-name [ "#" json-pointer ]
workflows-steps-reference = "steps" "." step-id
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:

Examples

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.
Step dependency (`dependsOn`)	`$workflows.foo.steps.bar`	References a step (`bar`) defined in a different workflow (`foo`) within the current Arazzo Document.
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.

License

@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.

Name		Name	Last commit message	Last commit date
.github		.github
.husky		.husky
assets		assets
scripts		scripts
src		src
test		test
types		types
.browserslistrc		.browserslistrc
.commitlintrc.json		.commitlintrc.json
.editorconfig		.editorconfig
.gitignore		.gitignore
.lintstagedrc		.lintstagedrc
.mocharc.json		.mocharc.json
.nvmrc		.nvmrc
.prettierrc		.prettierrc
.releaserc		.releaserc
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
GOVERNANCE.md		GOVERNANCE.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
SECURITY.md		SECURITY.md
babel.config.cjs		babel.config.cjs
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json

Navigation Menu

Repository navigation

About

Repository files navigation

@swaggerexpert/arazzo-runtime-expression

Table of Contents

Getting started

Installation

Usage

Extraction

Interpolation

Parsing

Translators

CST translator

AST translator

XML translator

Statistics

Tracing

Validation

Errors

Grammar

More about Arazzo runtime expressions

Examples

License

About

Releases

Sponsor this project

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

@swaggerexpert/arazzo-runtime-expression

Table of Contents

Getting started

Installation

Usage

Extraction

Interpolation

Parsing

Translators

CST translator

AST translator

XML translator

Statistics

Tracing

Validation

Errors

Grammar

More about Arazzo runtime expressions

Examples

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Sponsor this project

Used by

Contributors

Languages