3.3.2.1. Use of AFD custom functions in JMESPath (AFD 2.0)

1 Why custom functions?

JMESPath includes many built-in functions, such as abs, avg, starts_with, and length. However, some validations required in the AFD-definition Standard go beyond what is possible with these standard functions. To meet these needs, custom functions can be added to JMESPath.
These custom functions can be implemented using JMESPath libraries in programming languages like Python or .NET. A list of compatible libraries is available at jmespath.org/libraries.
Please note: custom functions are not recognized by general online JMESPath testers, as they are not part of the standard JMESPath language. The available standard libraries for JMESPath can handle custom functions, but users have to set up their own test environment to test these functions.

2 AFD custom functions

To avoid every party developing their own versions of custom functions, SIVI provides standard custom functions within the AFD-definition Standard: AFD custom functions. These functions are developed to cover missing functionality in the JMESPath standard in a consistent way.
An AFD custom function is a function predefined by SIVI that you use within a JMESPath expression, but that is not part of the standard functions. These functions are specifically tailored for use within the definitions of AFD 2.0.

Each AFD custom function comes with a formal specification including:

• Name
  Name of the function in camelCase, should be self-explaining about the purpose of the function.
• Signature
  Formal function call, including types. Example: number acfCountDateDiff(string subjectDate, string referenceDate, string unit)
• Input parameters
  For each parameter the following is defined: the name, the data type (such as string or number), the expected format (such as ‘YYYY-MM-DD’), an explanation of the meaning and code lists if applicable.
• Return value
  Description of the type, the expected format and the interpretation of the result.
• Examples
  Input with corresponding expected output, for example: acfCountDateDiff(‘2024-01-01’, ’2024-01-10’, ‘days’), result = ‘9’
  

If a needed function is not yet available, users are encouraged to contact SIVI. If the required logic is sufficiently generic, SIVI will consider developing a standard AFD custom function.

3 Overview of available AFD custom functions

Below is a summary of the AFD custom functions currently available. Click on a function to see more details.

acfCountDateDiff

Calculates the number of whole units (year, month, week, day) between two dates. The result is truncated and not rounded.

Signature:
number acfCountDateDiff(string $subjectDate, string $referenceDate, string $calendarUnit)

Input parameters

• subjectDate
  Startdate (YYYY-MM-DDDD) of the calculation
• referenceDate
  Date that is checked
• calendarUnit
  Unit of the difference between the two dates: ‘day’, ‘week’, ‘month’ of ‘year’
  

Example:

birthDate.acfCountDateDiff(@, '2024-07-07', 'year') >= `18`

This checks whether a person is at least 18 years old on 7 July 2024.

acfDateAdd

Adds a number of time units (positive or negative) to a given date, returning the resulting date.

Signature:
string acfDateAdd(string $subjectDate, number $number, string $calendarUnit)

Example:
effectiveDate.acfDateAdd(@, -2, ‘year’)
This subtracts two years from the effective date and returns the result.

acfSubString

Extracts a number of characters from a string, starting at a given position.

Signature:
string acfSubString(string $subjectText, number $startCharacter, number $numberOfCharacters)

Example:

licensePlate.acfSubString(@, 1, 3)
This results the first three characters of the license plate.

acfTrim, acfTrimLeft, acfTrimRight

Removes specified characters (or spaces by default) from a string.

Signatures:

• string acfTrim(string $subject [, string $chars])
• string acfTrimLeft(string $subject [, string $chars])
• string acfTrimRight(string $subject [, string $chars])
  

Example:

!starts_with(licensePlate.acfTrimLeft(@, '1234567890'), 'B')

This checks whether the first letter of the license plate (after removing any leading digits) is not a ‘B’.