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

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:

  1. Keys, e.g. scheme in uri#scheme.
  2. 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:

  1. Split the string on the dot character (.).
  2. 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

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.