Generators

A Generator generates a value that will be used in a request. Most Generators produce a different value each time they are used to construct a request.

A Generator may be specified for a field(s) of a request in a GeneratorSet in the configuration, or used as functions in templates (e.g., see generator OneOfJSON). In either case, a Generator produces a single value of type boolean, number, string, object, or array.

In the web UI, Generators are configured in the API Settings of an API Asset. When Sift fetches a configuration or a configuration is downloaded from the web UI, the GeneratorSet definedin API Setting may be included in the configuration (see option "Include generators" in the Configuration Editor).

Configuration

Generators are configured by specifying a GeneratorSet. A GeneratorSet is an array of GeneratorScopes.

A GeneratorScope specifies a context and a set of GeneratorRules. The context specifies the subset of fields to which the rules apply. Sift applies the rules of the most-specific scope that matches a particular field in a request. A GeneratorScope has two properties:

context: a JSON Path of the form /{opID}/input/{parameterName}[/{fieldSelector}].
- The context specifies which subset of fields in an API to which the associated rules are applied.
- OpenAPI parameter names have the format "{location}/{name}", where location is one of "path", "query", "header", "cookie", "body". A "body" parameter does not have a name.
- Examples:
  - /listPets/input/query/name: Rules only apply to the name field in the listPets operation.
  - /listPets/input/query: Rules apply to any query parameters in the listPets operation.
  - /listPets: Rules apply to any fields in the listPets operation.
  - /: Rules apply to any fields in any operation in the target API.
rules: an array of GeneratorRule. The rules are evaluated in the order of the array, and the first rule that matches selects the Generator to use.

A GeneratorRule specifies a Generator that generates input values for any field that matches the pattern and type in the rule. The properties of a Generator Rule are:

kind: Kind of Generator to use for fields that match this rule.
params: Generator Parameters that are specific to the kind of Generator. This is a key-value map. Refer to Generator Kinds for the parameters of a particular kind of Generator.
pattern: A regular expression (RE2 format) that matches the name of a field. A field's name is the last element of the JSON Path to the field.
type: The type of the field. One of "boolean", "integer", "number", "string". A field must have this value type for the rule to match. This is an optional property.

Both pattern and type are optional. If not specified, then that part of the rule rule matches any field. One of pattern or type should be specified in a rule. If both are missing, then a rule will match any field.

Generator Parameters

Some generators require parameter values to be given. In the table below, the parameters are described as named function parameters, such as:

(min int, max int)

When using a Generator in a template (e.g., for OneOfJSON), the parameters are passed as function arguments, such as:

{{ IntRange 2 7 }}

where min=2 and max=7.

When using a Generator in a Generator Rule, parameters are expressed as key-value pairs. Use the parameter name as the key. For example:

params:
  min: 2
  max: 7

Available Generators

Various kinds of Generators are available in Sift, as described in the following table.

Name	Parameters	Description
DateTime	-	Generates a timestamp for the current UTC time. The string is formatted according to Internet Date/Time Format defined in RFC 3339, Section 5.6 which is a profile of ISO8601.
IntRange	(min int, max int)	Generates an integer in a specified range.
IntConstant	(value int)	Generates a fixed integer every time.
OneOfJSON	(options []string)	Chooses one random element from an array of strings that are each a text represention of a JSON element. A value is generated by parsing the chosen JSON element string into a boolean, number, string, object, or array value. The JSON element string may include template syntax to construct the element string. Within a template expression, other Generators may be called as functions to produce dynamic elements. Template expressions are wrapped inside of `{{ }}`. For example, the JSON value `{"name": {{ Regex "[a-z]{5}" }}, "quantity": {{ IntRange 4 9 }}}` will generate an object with a key "name" that has a string value of five lower-case characters and a key "quantity" which has a number value between 4 and 9 (inclusive). The generated value used in a request may look like `{"name": "afjix", "number": 8 }`.
Regex	(expr string)	Generates a random string that matches a given regular expression.
ResourceReference	(resource string)	Generates an identifier that refers to a resource instance of the kind of specified in the `resource` parameter. This generator defines a dependency relationship between the operation that contains the field for which the generator is configured and another operation that can create or list the given kind of resource. This dependency relationship affects the sequences of operations that are generated, so that a valid resource identifier may first be obtained.
StringConstant	(value string)	Generates a fixed string every time.

In addition, within the context of a template inside of OneOfJSON generator, the following functions may be called to generate common kinds of values.

Name	Parameters	Description
Email	-	Generates an email address.
Username	-	Generates a username of 3-30 alphanumeric and underscore characters.
Password	-	Generates a password with at least one uppercase letter, one lowercase letter, one digit, one special character, and at least 9 characters in length.
URL	-	Generates a URL.

Domain	-	Generates a domain name.
IPv4	-	Generates an IPv4 address.
IPv6	-	Generates an IPv6 address.
MAC	-	Generates a MAC address.

DateISO8601	-	Generates a random date in the ISO 8601 format (YYYY-MM-DD).
DateMMDDYYYY	-	Generates a random date in MM/DD/YYYY format.
DateDDMMYYYY	-	Generates a random date in DD/MM/YYYY format.
DateYYYYMMDD	-	Generates a random date in YYYY/MM/DD format.
TimestampISO8601	-	Generates a random timestamp that includes a combined date and time in ISO 8601 format.
Time24Hour	-	Generates a random time in 24-hour format (hh:mm).
Time12Hour	-	Generates a random time in 12-hour format (hh:mm AM/PM).

UUID	-	Generates a UUID (version 1-5).
Base64	-	Generates a Base64-encoded string.

Percentage	-	Generates a percentage value with optional decimal places.
Currency	-	Generates a currency value with optional decimal places.
CurrencyCode	-	Generates a three-letter currency code.
CreditCard	-	Generates a phony credit card number.
CVV	-	Generates a credit card CVV (3 or 4 digits).

SSN	-	Generates a random US Social Security Number (SSN).
UKNationalInsuranceNumber	-	Generates a random UK National Insurance Number.
CanadianSIN	-	Generates a random Canadian Social Insurance Number (SIN).
DUNS	-	Generates a random 9-digit DUNS number.
EIN	-	Generates a random U.S. Federal Tax Identification Number (EIN).
IBAN	-	Generates a random International Bank Account Number (IBAN).
ISBN	-	Generates a random International Standard Book Number (ISBN). Check digit may be incorrect.
ASIN	-	Generates an Amazon Standard Identification Number (ASIN).
VAT	-	Generates a random European Union VAT number
VIN	-	Validates a random Vehicle Identification Number (VIN)
LicensePlate	-	Generates a random license plate (alphanumeric, hyphen-separated, 1-10 characters)

Slug	-	Generates a URL slug (lowercase, alphanumeric, hyphen-separated).
FileExtension	-	Generates a random file extension (1-5 alphanumeric characters)
TwitterUsername	-	Generates a random Twitter username
YouTubeVideoID	-	Generates a random YouTube video ID.
GitHubRepository	-	Generates a random GitHub repository path

PhoneNumber	-	Generates a phone number with optional international prefix.
PhoneExtension	-	Generates a phone extension (1 to 5 digits).
StreetAddress	-	Generates a random street address.
CountryCode	-	Generates a two-letter country code.
PostalCodeUS	-	Generates a US ZIP code (5 or 9 digits).
PostalCodeCanada	-	Generates a Canadian postal code.
PostalCodeAustralia	-	Generates an Australian postal code.
PostalCodeIndia	-	Generates an Indian postal code.
PostalCodeBrazil	-	Generates a Brazilian postal code (CEP).
PostalCodeUK	-	Generates a UK postcode.
PostalCodeFrance	-	Generates a French postal code.
PostalCodeGermany	-	Generates a German postal code.
PostalCodeItaly	-	Generates an Italian postal code.
PostalCodeSpain	-	Generates a Spanish postal code.
Latitude	-	Generates a latitude coordinate.
Longitude	-	Generates a longitude coordinate.

MIMEType	-	Generates a random MIME type.
HTMLTag	-	Generates an HTML tag.
ColorHex	-	Generates a 3- or 6-digit hexadecimal color code.
ColorRGB	-	Generates an RGB color value.
ColorRGBA	-	Generates an RGBA color value.
ColorHSL	-	Generates an HSL color value.

Example

Consider the following snippets of an OpenAPI definition that describes two operations: listPets, updatePet.

paths:
  /pets:
    get:
      summary: Finds Pets by status
      operationId: listPets
      parameters:
        - name: status
          in: query
          description: Status values that need to be considered for filter
          required: false
          schema:
            type: string
            enum:
              - available
              - pending
              - sold

  /pets/{id}:
    put:
      summary: Updates a pet in the store with form data
      operationId: updatePet
      parameters:
        - name: id
          in: path
          description: ID of pet that needs to be updated
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        description: Update a pet in the store
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                status:
                  type: string
                  description: pet status in the store
                  enum:
                    - available
                    - pending
                    - sold

The following GeneratorSet defines two GeneratorScopes, each with one GeneratorRule:

generators:
  - context: /
    rules:
    - kind: Regex
      params:
        expr: "[a-z]{8}"
      pattern: "^name$"
  - context: /updatePet
    rules:
    - kind: StringConstant
      params:
        value: "sold"
      pattern: "^status$"

With this configuration, Sift will generate values as follows:

listPets:
- /input/query/status: No GeneratorRule matches. Sift will use the default generator, which will select from the enum defined in the OpenAPI definition.
updatePets:
- /input/path/id: No GeneratorRule matches. Sift will use the default generator, which may reference a value from the response of another operation that produces a Pet ID.
- /input/body/name: GeneratorRule in global scope ("/") matches. Value will be produced by Regex generator.
- /input/body/status: GeneratorRule in scope "/updatePet" matches. Value will be the constant value "sold".