@swaggerexpert/openapi-runtime-expression

@swaggerexpert/openapi-runtime-expression

OpenAPI Runtime Expressions allow defining values based on information that will only be available within the HTTP message in an actual API call. This mechanism is used by Link Objects and Callback Objects of OpenAPI specification.

@swaggerexpert/openapi-runtime-expression is a parser, validator and extractor for OpenAPI Runtime Expressions.

It supports Runtime Expressions defined in following OpenAPI specification versions:

• OpenAPI 3.0.0
• OpenAPI 3.0.1
• OpenAPI 3.0.2
• OpenAPI 3.0.3
• OpenAPI 3.0.4
• OpenAPI 3.1.0
• OpenAPI 3.1.1

Get professionally supported @swaggerexpert/openapi-runtime-expression with Tidelift Subscription.

Table of Contents

• Getting started
  • Installation
  • Usage
    • Extraction
    • Parsing
    • Validation
    • Grammar
• More about OpenAPI runtime expressions
• License

Getting started

Installation

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

 $ npm install @swaggerexpert/openapi-runtime-expression

Usage

@swaggerexpert/openapi-runtime-expression currently supports extraction, parsing and validation. Both parser and validator are based on a superset of ABNF (SABNF) and use apg-lite parser generator.

Extraction

OpenAPI embeds Runtime Expressions into string values surrounded with {} curly braces. To extract Runtime Expressions from this embedded form, use the extract function. Extracted Runtime Expression can be used for further parsing of validation.

import { extract, test, parse } from '@swaggerexpert/openapi-runtime-expression';

const expression = extract('{$request.header.accept}'); // => '$request.header.accept'

test(expression); // => true
parse(expression); // => { result, ast }

Parsing

Parsing a Runtime Expression is as simple as importing the parse function and calling it.

import { parse } from '@swaggerexpert/openapi-runtime-expression';

const parseResult = parse('$request.header.accept');

token non-terminal is by default being normalized to lower case.

import { parse } from '@swaggerexpert/openapi-runtime-expression';

const parseResult = parse('$request.header.Accept');
const parts = [];

parseResult.ast.translate(parts);
// [
//   [ 'expression', '$request.header.Accept' ],
//   [ 'source', 'header.Accept' ],
//   [ 'header-reference', 'header.Accept' ],
//   [ 'token', 'accept' ],
// ]

token normalization can be overridden by passing token normalizer to the parse function.

Upper case

import { parse, tokenUpperCaseNormalizer } from '@swaggerexpert/openapi-runtime-expression';

const parseResult = parse('$request.header.Accept', { tokenNormalizer: tokenUpperCaseNormalizer });
const parts = [];
parseResult.ast.translate(parts);
// [
//   [ 'expression', '$request.header.Accept' ],
//   [ 'source', 'header.Accept' ],
//   [ 'header-reference', 'header.Accept' ],
//   [ 'token', 'ACCEPT' ],
// ]`

Lower case

import { parse, tokenLowerCaseNormalizer } from '@swaggerexpert/openapi-runtime-expression';

const parseResult = parse('$request.header.Accept', { tokenNormalizer: tokenLowerCaseNormalizer });
const parts = [];
parseResult.ast.translate(parts);
// [
//   [ 'expression', '$request.header.Accept' ],
//   [ 'source', 'header.Accept' ],
//   [ 'header-reference', 'header.Accept' ],
//   [ 'token', 'accept' ],
// ]`

parseResult variable has the following shape:

{
  result: {
    success: true,
    state: 101,
    stateName: 'MATCH',
    length: 22,
    matched: 22,
    maxMatched: 22,
    maxTreeDepth: 13,
    nodeHits: 152
  },
  ast: fnast {
    callbacks: [
      expression: [Function: expression],
      source: [Function: source],
      'header-reference': [Function: headerReference],
      'query-reference': [Function: queryReference],
      'path-reference': [Function: pathReference],
      'body-reference': [Function: bodyReference],
      'json-pointer': [Function: jsonPointer],
      'reference-token': [Function: referenceToken],
      name: [Function: name],
      token: [Function: token]
    ],
    init: [Function (anonymous)],
    ruleDefined: [Function (anonymous)],
    udtDefined: [Function (anonymous)],
    down: [Function (anonymous)],
    up: [Function (anonymous)],
    translate: [Function (anonymous)],
    setLength: [Function (anonymous)],
    getLength: [Function (anonymous)],
    toXml: [Function (anonymous)]
  }
}

Interpreting AST as list of entries

import { parse } from '@swaggerexpert/openapi-runtime-expression';

const parseResult = parse('$request.header.accept');
const parts = [];

parseResult.ast.translate(parts);

After running the above code, parts variable has the following shape:

[
  [ 'expression', '$request.header.accept' ],
  [ 'source', 'header.accept' ],
  [ 'header-reference', 'header.accept' ],
  [ 'token', 'accept' ],
]

Interpreting AST as XML

import { parse } from '@swaggerexpert/openapi-runtime-expression';

const parseResult = parse('$request.header.accept');
const xml = parseResult.ast.toXml();

After running the above code, xml variable has the following content:

<?xml version="1.0" encoding="utf-8"?>
<root nodes="4" characters="22">
  <!-- input string -->
  $request.header.accept
  <node name="expression" index="0" length="22">
    $request.header.accept
    <node name="source" index="9" length="13">
      header.accept
      <node name="header-reference" index="9" length="13">
        header.accept
        <node name="token" index="16" length="6">
          accept
        </node><!-- name="token" -->
      </node><!-- name="header-reference" -->
    </node><!-- name="source" -->
  </node><!-- name="expression" -->
</root>

NOTE: AST can also be traversed in classical way using depth first traversal. For more information about this option please refer to apg-js and apg-js-examples.

Validation

Validating a Runtime Expression is as simple as importing the test function and calling it.

import { test } from '@swaggerexpert/openapi-runtime-expression';

test('$request.header.accept'); // => true
test('nonsensical string'); // => false

Grammar

New grammar instance can be created in following way:

import { Grammar } from '@swaggerexpert/openapi-runtime-expression';

const grammar = new Grammar();

To obtain original ABNF (SABNF) grammar as a string:

import { Grammar } from '@swaggerexpert/openapi-runtime-expression';

const grammar = new Grammar();

grammar.toString();
// or
String(grammar);

More about OpenAPI runtime expressions

The runtime expression is defined by the following ABNF syntax

; OpenAPI runtime expression ABNF syntax
expression       = "$url" / "$method" / "$statusCode" / "$request." source / "$response." source
source           = header-reference / query-reference / path-reference / body-reference
header-reference = "header." token
query-reference  = "query." name
path-reference   = "path." name
body-reference   = "body" ["#" json-pointer ]
name             = *( CHAR )

; https://datatracker.ietf.org/doc/html/rfc6901#section-3
json-pointer     = *( "/" reference-token )
reference-token  = *( unescaped / escaped )
unescaped        = %x00-2E / %x30-7D / %x7F-10FFFF
                 ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
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-10FFFF

; https://datatracker.ietf.org/doc/html/rfc5234#appendix-B.1
HEXDIG         =  DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
DIGIT          =  %x30-39   ; 0-9
ALPHA          =  %x41-5A / %x61-7A   ; A-Z / a-z

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

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/openapi-runtime-expression is licensed under Apache 2.0 license. @swaggerexpert/openapi-runtime-expression comes with an explicit NOTICE file containing additional legal notices and information.