Skip to main content

String Alternation

String alternation is a constraint that enables you to manipulate string values, including concatenation and hashing. It’s particularly useful when you need to generate a new string based on existing property values. While it can be used in both schema and plan configuration files, it is recommended to be employed in the plan configuration.

Supported types of string alternation are:

  • concatenation
  • bcrypt hashing
  • pbkdf2 hashing
  • text letter case conversion

Like correlation constraints, string alternation uses properties follows:

  • type: The value needs to be "alternation".
  • properties: A set of properties used to generate the new string value.
  • formula: A formula of how the new values should be used.

Sample Files

Concatenation​

Concatenation allows you to join multiple string values together using the + operator.

The following example demonstrates how to concatenate two string properties "text1" and "text2" using hyphen as a delimiter:

Schema File
  - name: "text1"
    type: "text"
    constraints:
      - type: "char_group"
        groups:
          - "ascii_alpha_numerals"
      - type: "size"
        min: 8
        max: 12
    index:
      id: 1
  - name: "text2"
    type: "text"
    constraints:
      - type: "char_group"
        groups:
          - "ascii_alpha_numerals"
      - type: "size"
        min: 8
        max: 10
  - name: "concatenated_text"
    type: "text"
    constraints:
      - type: "alternation"
        properties:
          - "text1"
          - "text2"
        formula: "text1 + '-' + text2"
note

For concatenation, the fixed string value should be enclosed in either single quote or double quotes. If using double quote, it needs to be escaped with a backslash.

Bcrypt​

It hashes a string value using the bcrypt algorithm. There are two implementations exist:

  • BCRYPT(rawpass): The bcrypt algorithm with a strength of 10.
  • BCRYPT_STRENGTH(rawpass, strength): The bcrypt algorithm allows specifying the cost (strength) of the hashing algorithm (between 4 and 10) for performance reasons.
Encrypt property text1 with BCRYPT
- name: "bcrypt_hash"
  type: "text"
  constraints:
    - type: "alternation"
      properties:
        - "text1"
      formula: "BCRYPT(text1)"

PBKDF2​

Hashes a string value using the PBKDF2(PBKDF2WithHmacSHA1) algorithm.

Encrypt property text1 with PBKDF2 using the value of text2 as secret
# The PBKDF2_SHA1 function takes 4 parameters:
# PBKDF2_SHA1(secret, saltLength, iterations, rawPassword)
# - secret: The secret used to generate the hash
# - saltLength: The length of the salt
# - iterations: The number of iterations
# - rawPassword: The password to hash
- name: "pbkdf2"
  type: "text"
  constraints:
    - type: "alternation"
      properties:
        - "text1"
        - "text2"
      formula: "PBKDF2_SHA1(text2, 16, 1000, text1)"
danger

The PBKDF2 implementation uses Pbkdf2PasswordEncoder from SpringBootSecurity 6.3.0. Keep in mind that if your backend uses a different encoder, the hashed value may not match.

Text Letter Case Conversion​

Formula function STRING_CASE(str, caseType) converts the string str to the specified caseType. The caseType is case insensitive and can be one of the following:

  • upper: Converts the string to uppercase. E.g. "hello world" -> "HELLO WORLD"
  • lower: Converts the string to lowercase. E.g. "HELLO WORLD" -> "hello world"
  • pascal: Converts the string to pascal case. E.g. "hello world" -> "Hello World"
  • title: Converts the string to title case. E.g. "hello world" -> "Hello world"
Convert text to upper case
- name: "to_uppercase"
  type: "text"
  constraints:
    - type: "alternation"
      properties:
        - "text1"
      formula: "STRING_CASE(text1, 'upper')"

Full Email Address​

Formula function FULL_EMAIL_ADDRESS(emailAddress, name) generates a full email address by concatenating the name and emailAddress properties. The output is using format ${name}<${emailAddress}>, e.g. Michael Rath<michael.rath@duotail.com>.

Function parameters:

  • emailAddress: The email address property.
  • name: The optional name property.
Generate email address: Michael Rath<michael.rath@duotail.com>
- name: "email"
  type: "text"
  constraints:
    - type: "alternation"
      formula: "FULL_EMAIL_ADDRESS('michael.rath@duotail.com', 'Michael Rath')"

String Template​

Formula function STRING_TEMPLATE(template, ...values) generates a new string by replacing placeholders in the template with the provided values. The placeholders are defined using ${} syntax, e.g. Hello ${name}.

Function parameters:

  • template: The template string with placeholders.
  • values: The values to replace the placeholders. The values are used in pairs, where the first value is the placeholder name and the second value is the replacement value.

Substitution Rule​

The following rules are applied when replacing placeholders:

  • A placeholder is defined using ${} syntax, e.g. ${name}.
  • Placeholder is case sensitive
  • If the placeholder is not found in the template, the placeholder is removed.
  • Escape character $ is used to escape the placeholder, e.g. $${name} is not replaced by the value of name.
Generate string using template
# Generated string: Hello John, your order number is 123, amount is $100.00.
- name: "templated_text"
  type: "text"
  constraints:
    - type: "alternation"
      formula: "STRING_TEMPLATE('Hello ${name}, your order number is ${orderId}, amount is $$${amount}.', 'name', 'John', 'orderId', '123', 'amount', '100.00')"