Rules engine parameters#

Rules engine parameters are a set of named property values that are used by a rules engine implementation to resolve a service rule set. The set of parameters are rule set specific, and MUST be generated as a public type in the service’s package or namespace. The rule set MAY define zero or more parameters.

Parameter names MUST start with a letter and be followed by one or more alphabetical or numerical characters. Parameter names are case-sensitive when used in a rule set and accompanying Smithy traits. Parameters MUST have case-insensitively unique names. This restriction allows for parameter names to be normalized to a more idiomatic language naming convention. For example, a parameter with the name endpointId may be converted to EndpointId or endpoint_id.

This following is the ABNF grammar for rule set parameter names:


Parameters declare their respective type using the type key. The following parameter types are supported: string, boolean, and stringArray. The following table provides the description of these types, and their Smithy compatible types whose values can be bound to these parameters. Rule set parameters are always considered nullable and have no default value associated with them.

Parameter type Smithy type Description
string string UTF-8 encoded string.
boolean boolean Boolean value type.
stringArray list A list with string members.

Parameter implementations#

Implementations MUST always generate a parameter structure, even in the absence of parameters. This provides for a stable API interface regardless of a service’s rule set evolution over time. The addition of parameters to a rule set MUST be a backwards-compatible.

Implementations MUST generate parameter types using their language idiomatic interfaces to distinguish whether values are set or unset by users. For example, the Go programming language would generate these types as pointer values, whereas Rust would wrap types using the Option type.

Parameter evolution#

Services MAY add additional parameters to their rule set in subsequent revisions. Services MUST NOT remove parameters, but MAY remove the usage of those parameters from their rule set. Service teams SHOULD use the deprecated property to provide a description of the deprecation and relevant recourse. Implementations SHOULD use the deprecated property value to generate language specific documentation to indicate a parameter's deprecation. A service SHOULD provide documentation for a parameter using the documentation property.

Binding parameter values#

Rules engine implementations bind values to parameters defined in rule sets, utilizing information in the service model in addition to the rules. Rules engine parameter traits are used to bind runtime values to rule sets. Additionally, the rules engine contains "built-ins" that implementations are responsible for sourcing the value of and binding it to any applicable parameter. The rules engine has a set of included built-ins that can be invoked without additional dependencies.

If a parameter has multiple values that can be bound to it, the most specific value must be selected and provided to the implementation. The following is the order of the most specific to least specific value locations:

  1. smithy.rules#staticContextParams trait
  2. smithy.rules#contextParam trait
  3. smithy.rules#operationContextParams trait
  4. smithy.rules#clientContextParams trait
  5. Built-in bindings
  6. Built-in binding default values

Rules engine parameter traits#

Rule set parameters MAY be bound to values from various locations in a client's request flow using traits.

The examples in the following trait definitions are valid bindings into the following rule set:

{
    "version": "1.0",
    "serviceId": "example",
    "parameters": {
        "linkId": {
            "type": "string",
            "documentation": "The identifier of the link to target."
        },
        "previewEndpoint": {
            "type": "boolean",
            "documentation": "Whether the client should target the service's preview endpoint."
        }
    },
    "rules": [
        // Abbreviated for clarity
    ]
}
smithy.rules#clientContextParams trait#
Summary
Defines one or more rule set parameters that MUST be generated as configurable client configuration parameters
Trait selector
service
Value type
map of string containing a rule set parameter name to a clientContextParam structure.

The clientContextParam structure has the following properties:

Property Type Description
type string Required. The shape type used to generate the client configuration parameter. MUST be one of string or boolean.
documentation string A description of the parameter that will be used to generate documentation for the client configurable.

Each parameter is identified using it’s name as specified in the rule set. It is mapped to properties describing how the parameter should be configured on the generated client. The type of a clientContextParam MUST be compatible with the parameter type specified in the rule set. The client configuration parameters SHOULD be configurable or overridable per operation invocation.

The following example specifies two parameters to be generated on clients as configurable values:

@clientContextParams(
    linkId: {
        type: "string"
        documentation: "The identifier of the link to target."
    }
    previewEndpoint: {
        type: "boolean"
        documentation: "Whether the client should target the service's preview endpoint."
    }
)
service ExampleService {
    version: "2020-07-02"
    operations: [GetThing]
}
smithy.rules#staticContextParams trait#
Summary
Defines one or more rule set parameters that MUST be bound to the specified values.
Trait selector
operation
Value type
map of string containing a rule set parameter name to a staticContextParam structure.

The staticContextParam structure has the following properties:

Property Type Description
value document Required. The static value to be set for the parameter. The type of the value MUST be either a string, boolean or an array of string.

Each parameter is identified using it’s name as specified in the rule set. The type of a staticContextParam MUST be compatible with the parameter type specified in the rule set.

The following example specifies three parameters to statically set for an operation:

@staticContextParams(
    linkId: {
        value: "some value"
    }
    previewEndpoint: {
        value: true
    },
    supportedPrefixes: {
        value: ["host", "id", "resourceId"]
    }
)
operation GetThing {}
smithy.rules#operationContextParams trait#
Summary
Defines one or more rule set parameters that MUST be bound to values specified in the operation input.
Trait selector
operation
Value type
map of string containing a rule set parameter name to a operationContextParam structure.

The operationContextParam structure has the following properties:

Property Type Description
path string Required. A JMESPath expression to select element(s) from the operation input to bind to.

Each parameter is identified using it’s name as specified in the rule set. The type of a operationContextParam MUST be compatible with the parameter type specified in the rule set.

The following example specifies a parameter bound to an array of object keys in the operation input using a JMESPath expression:

@operationContextParams(
    ObjectKeys: {
        path: "Delete.Objects[*].Key"
    }
)
operation DeleteObjects {
    input: DeleteObjectsRequest
}

structure DeleteObjectsRequest {
    Delete: Delete
}

structure Delete {
    Objects: ObjectIdentifierList
}

list ObjectIdentifierList {
    member: ObjectIdentifier
}

structure ObjectIdentifier {
    Key: String
}

paths specified in OperationContextParams are limited to a subset of JMESPath:

  • Identifiers - the most basic expression and can be used to extract a single element from a JSON document. The return value for an identifier is the value associated with the identifier. If the identifier does not exist in the JSON document, than a null value is returned.
  • Sub Expressions - a combination of two expressions separated by the . char. Example: grandparent.parent.child
  • Wildcard Expressions - Creates a projection over the values in an array or map. Remaining expressions are evaluated against each returned element.
  • Keys function - return a list of the keys in a map. This is the only supported function but is required for binding to key values.
smithy.rules#contextParam trait#
Summary
Binds a top-level operation input structure member to a rule set parameter.
Trait selector
structure > member
Value type

An object that supports the following properties:

Property Type Description
name string Required. The name of the context parameter to bind the member value to.

The following example specifies an operation with an input parameter buzz bound to the linkId rule set parameter:

operation GetThing {
    input := {
        fizz: String

        @contextParam(name: "linkId")
        buzz: String
    }
}

Important

If a member marked with the @contextParam trait is also marked as required, clients MUST NOT send requests if the parameter is unset, empty, or exclusively whitespace characters. This ensures that servers can reliably dispatch to operations based on these parameters.

Rules engine built-ins#

Rule set parameters MAY be annotated with the builtIn property. When a parameter has this property, the parameter’s value MUST be bound to the value retrieved from the identified source, if present, UNLESS a more specific value supersedes it.

{
    "parameters": {
        "endpoint": {
            "type": "string",
            "builtIn": "SDK::Endpoint"
        }
    }
}

The rules engine has a set of included built-ins that can be invoked without additional dependencies, which are defined as follows:

SDK::Endpoint built-in#
Description
A custom endpoint for a rule set.
Type
string
Adding built-ins through extensions#

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

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