Rules engine standard library#

Functions in the Smithy rules engine are named routines that operate on a finite set of specified inputs, returning an output. See the function object documentation for more information. The rules engine has a set of included functions that can be invoked without additional dependencies, called the standard library, which are defined as follows:

`booleanEquals` function#

Summary

Evaluates two boolean values for equality, returning true if they match.

Argument type

value1: bool
value2: bool

Return type

bool

The following example uses booleanEquals to check if value of the foo parameter is equal to the value false:

{
    "fn": "booleanEquals",
    "argv": [
        {"ref": "foo"},
        true
    ]
}

`coalesce` function#

Summary

Evaluates arguments in order and returns the first non-empty result, otherwise returns the result of the last argument.

Argument types

This function is variadic and requires two or more arguments, each of type T or option<T>
All arguments must have the same inner type T

Return type

coalesce(T, T, ...) → T
coalesce(option<T>, T, ...) → T (if any argument is non-optional)
coalesce(T, option<T>, ...) → T (if any argument is non-optional)
coalesce(option<T>, option<T>, ...) → option<T> (if all arguments are optional)

Since

1.1

The coalesce function provides null-safe chaining by evaluating arguments in order and returning the first non-empty result. If all arguments leading up to the last argument evaluate to empty, it returns the result of the last argument. This is particularly useful for providing default values for optional parameters, chaining multiple optional values together, and related optimizations.

The function accepts two or more arguments, all of which must have the same inner type after unwrapping any optionals. The return type is option<T> only if all arguments are option<T>; otherwise it returns T.

The following example demonstrates using coalesce with multiple arguments to try several optional values in sequence:

{
    "fn": "coalesce",
    "argv": [
        {"ref": "customEndpoint"},
        {"ref": "regionalEndpoint"},
        {"ref": "defaultEndpoint"}
    ]
}

Important

All arguments must have the same type after unwrapping any optionals (types are known at compile time and do not need to be validated at runtime). Note that the first non-empty result is returned even if it's false (coalesce is looking for a non-empty value, not a truthy value).

`getAttr` function#

Summary

Extracts a value at the given path from an object or array.

Argument types

value: object or array
path: string

Return type

document

The following example uses getAttr to extract the scheme value from the parsed value of the foo parameter:

{
    "fn": "getAttr",
    "argv": [
        {
            "fn": "parseURL",
            "argv": [
                {"ref": "foo"}
            ]
        },
        "scheme"
    ]
}

Parsing `path` strings#

Path strings for the getAttr function are composed of two components:

Keys, e.g. scheme in uri#scheme.
Indexes, e.g. [2] in list[2].

An index MUST only occur at the end of a path, as indexes always return option values.

An algorithm for parsing path strings is as follows:

Split the string on the dot character (.).
Iterate over the parts:
1. If the part contains the open square bracket character ([):
  1. If there are characters before the [ character, parse these characters as a key.
  2. Parse the value between the [ and a close square bracket character (]) as an index.
2. Otherwise, parse the value as a key.

Note

Implementers SHOULD assume that the path string has been validated, meaning they do not need to perform their own validation at runtime.

`isSet` function#

Summary

Evaluates whether a value, such as an endpoint parameter, is not null.

Argument type

value: option<T>

Return type

bool

The following example uses isSet to check if the foo parameter is not null:

{
    "fn": "isSet",
    "argv": [
        {"ref": "foo"}
    ]
}

Important

isSet must accept an option and only considers optionality. isSet does not consider truthiness.

`isValidHostLabel` function#

Summary

Evaluates whether the input string is a compliant RFC 1123 host segment. When allowSubDomains is true, evaluates whether the input string is composed of values that are each compliant RFC 1123 host segments joined by dot (.) characters.

Argument type

value: string
allowSubDomains: bool

Return type

bool

The following example uses isValidHostLabel to check if the value of the foo parameter is an RFC 1123 compliant host segment.

{
    "fn": "isValidHostLabel",
    "argv": [
        {"ref": "foo"},
        false
    ]
}

`not` function#

Summary

Performs logical negation on the provided boolean value, returning the negated value.

Argument type

value: bool

Return type

bool

The following example uses not to negate the value of the foo parameter:

{
    "fn": "not",
    "argv": [
        {"ref": "foo"}
    ]
}

The following example uses not to negate the value of an isSet function:

{
    "fn": "not",
    "argv": [
        {
            "fn": "isSet",
            "argv": [
                {"ref": "foo"}
            ]
        }
    ]
}

`parseURL` function#

Summary

Computes a URL structure given an input string.

Argument type

value: string

Return type

option<URL>

Contains the parsed URL, or an empty optional if the URL could not be parsed

Important

If the URL given contains a query portion, the URL MUST be rejected and the function MUST return an empty optional.

The following example uses parseURL to parse the value of the foo parameter into its component parts:

{
    "fn": "parseURL",
    "argv": [
        {"ref": "foo"}
    ]
}

`URL` structure#

The URL structure is returned from the parseURL function when its input is a valid URL. The URL object contains the following properties:

Property	Type	Description
scheme	`string`	The URL scheme, such as `https`. The value returned MUST NOT include the `://` separator.
authority	`string`	The host and optional port component of the URL. A default port MUST NOT be included. A userinfo segment MUST NOT be included.
path	`string`	The unmodified path segment of the URL.
normalizedPath	`string`	The path segment of the URL. This value is guaranteed to start and end with a `/` character.
isIp	`bool`	Indicates whether the authority is an IPv4 _or_ IPv6 address.

Examples#

The following table shows valid and invalid values for an input to the parseURL function:

Input	Valid?	scheme	authority	path	normalizedPath	isIp
https://example.com	`true`	`https`	`example.com`	`/`	`/`	`false`
https://example.com:8443?foo=bar&faz=baz	`false`
http://example.com:80/foo/bar	`true`	`http`	`example.com:80`	`/foo/bar`	`/foo/bar/`	`false`
https://127.0.0.1	`true`	`https`	`127.0.0.1`	`/`	`/`	`true`
https://[fe80::1]	`true`	`https`	`[fe80::1]`	`/`	`/`	`true`

`split` function#

Summary

Divides a string into an array of substrings based on a delimiter.

Argument types

value: string
delimiter: string
limit: int

Return type

array<string>

Since

1.1

The split function divides a string into an array of substrings based on a non-empty delimiter. The behavior is controlled by the limit parameter:

limit = 0: Split all occurrences (unlimited)
limit = 1: No split performed (returns original string as single element array)
limit > 1: Split into at most 'limit' parts (performs limit-1 splits)

Important

The delimiter must not be null or empty. The limit must not be negative. For empty input strings, the function returns an array containing a single empty string.

The following example uses split to divide a bucket name into parts using -- as the delimiter:

{
    "fn": "split",
    "argv": [
        {"ref": "bucketName"},
        "--",
        0
    ]
}

Examples#

The following table shows various inputs and their corresponding outputs for the split function:

Input	Delimiter	Limit	Output
`"a--b--c"`	`"--"`	`0`	`["a", "b", "c"]`
`"a--b--c"`	`"--"`	`2`	`["a", "b--c"]`
`"a--b--c"`	`"--"`	`1`	`["a--b--c"]`
`""`	`"--"`	`0`	`[""]`
`"--"`	`"--"`	`0`	`["", ""]`
`"----"`	`"--"`	`0`	`["", "", ""]`
`"--b--"`	`"--"`	`0`	`["", "b", ""]`
`"--x-s3--azid--suffix"`	`"--"`	`0`	`["", "x-s3", "azid", "suffix"]`
`"--x-s3--azid--suffix"`	`"--"`	`2`	`["", "x-s3--azid--suffix"]`
`"abc"`	`"x"`	`0`	`["abc"]`
`"mybucket"`	`"--"`	`1`	`["mybucket"]`

`stringEquals` function#

Summary

Evaluates two string values for equality, returning true if they match.

Argument type

value1: string
value2: string

Return type

bool

The following example uses stringEquals to check if value of the foo parameter is equal to the value something:

{
    "fn": "booleanEquals",
    "argv": [
        {"ref": "foo"},
        "something"
    ]
}

`substring` function#

Summary

Computes a portion of a given string based on the provided start and end indices.

Argument type

input: string
startIndex: int
endIndex: int
reverse: bool

Return type

option<string>

The startIndex is inclusive and the endIndex is exclusive.

Important

If the string is not long enough to fully include the substring, the function MUST return an empty optional. The length of the returned string, when present, will always be sendIndex - startIndex.

The function MUST return an empty optional when the input contains non-ASCII characters.

The following example uses substring to extract the first four characters of value of the foo parameter:

{
    "fn": "substring",
    "argv": [
        {"ref": "foo"},
        0,
        4,
        false
    ]
}

`uriEncode` function#

Summary

Performs RFC 3986#section-2.1 defined percent-encoding on the input value.

Argument type

value: string

Return type

string

The function MUST percent-encode all characters except the unreserved characters that RFC 3986 defines: A-Z, a-z, 0-9, hyphen (-), underscore (_), period (.), and tilde (~). This includes percent- encoding the following printable/visible ASCII characters as well as all unicode characters: /:,?#[]{}|@! $&'()*+;=%<>"^`\. The function MUST use uppercase hexadecimal digits for all percent-encodings to ensure consistency.

Note

The space character must be percent encoded.

The following example uses uriEncode to percent-encode the value of the foo parameter:

{
    "fn": "uriEncode",
    "argv": [
        {"ref": "foo"}
    ]
}

Adding functions through extensions#

Extensions to the rules engine can provide additional functions. Code generators MAY support these additional functions and SHOULD document which extensions are supported. Additional functions MUST be namespaced, using two colon : characters to separate namespace portions. This is utilized to add the AWS rules engine functions.

The rules engine is highly extensible through software.amazon.smithy.rulesengine.language.EndpointRuleSetExtension service providers. See the Javadocs for more information.

Rules engine standard library#

booleanEquals function#

coalesce function#

getAttr function#

Parsing path strings#

isSet function#

isValidHostLabel function#

not function#

parseURL function#

URL structure#

Examples#

split function#

Examples#

stringEquals function#

substring function#

uriEncode function#

Adding functions through extensions#

`booleanEquals` function#

`coalesce` function#

`getAttr` function#

Parsing `path` strings#

`isSet` function#

`isValidHostLabel` function#

`not` function#

`parseURL` function#

`URL` structure#

`split` function#

`stringEquals` function#

`substring` function#

`uriEncode` function#