JsonataFunctionSpec

Function signature and implementation. params declares the inputs (typed, optionally schema-pinned), returnType declares the output, and body is the JSONata expression that turns one into the other.

Calling the function in JSONata: invoke as $<alias>(arg1, arg2, ...) from any expression that has the function in scope (template data.transform, blueprint inputMap, or another function's body). The alias is the one declared by the caller in its functions[] entry; if no alias is declared, the function's own key is used. Arguments are positional and must match the declared params order and types.

Calling other custom functions from body: declare each callee in the functions[] array with its functionKey + pinned functionVersion (and optional alias). This is the same explicit-registration pattern blueprints and templates use — pinning a version locks the dependency so the function keeps producing the same result even after the dependency publishes a new semver.

  • body
    Type: string
    required

    The JSONata expression that computes the return value from the parameters. Standard JSONata syntax — referenced parameters are scoped variables (no $ prefix), built-in JSONata functions are invoked with the $ prefix (e.g. $sum, $now, $fromMillis), and other custom functions are invoked as $<alias>(...) for each callee declared in functions[] (alias defaults to functionKey when not specified).

  • returnType
    Type: object
    required

    Type the function returns. For primitives (string, number, boolean), the bare type is enough. For object, pair with schemaKey + schemaVersion to pin the produced shape to a schema. For array, pair with itemType to declare the element type (and add schemaKey + schemaVersion when itemType is object).

    • type
      Type: stringenum
      required

      The return type.

      values
      • string
      • number
      • boolean
      • object
      • array
    • itemType
      Type: stringenum

      Element type when type is array.

      values
      • string
      • number
      • boolean
      • object
    • schemaKey
      Type: string

      Schema key pinning the returned shape (when type is object, or when type is array and itemType is object).

    • schemaVersion
      Type: string

      Version of the pinned schema (draft or a published semver).

  • functions
    Type: array object[]

    Other JSONata functions this function calls from body. Each entry pins a specific functionKey + functionVersion, with an optional alias used at call sites (defaults to functionKey when not specified). Aliases let you decouple call-site names from resource keys so you can rename or swap the callee later by changing this entry without touching body. Same shape used by BlueprintSpec.functions and TemplateSpec.functions.

    • functionKey
      Type: string
      required

      Resource key of the JSONata function being referenced.

    • functionVersion
      Type: string
      required

      Specific version of the function being pinned (semver like 1.0.0 or draft while iterating).

    • alias
      Type: string Pattern: ^[a-z][a-zA-Z0-9]*$

      Optional name used in JSONata expressions to invoke this function as $<alias>(...). Defaults to functionKey when not specified.

  • params
    Type: array object[] · JsonataFunctionParam[]

    Ordered list of input parameters. Inside body, each is referenced by name without the $ prefix (e.g. params: [{name: "amount"}] is read as amount in the expression).

    • name
      Type: string Pattern: ^[a-z][a-zA-Z0-9]*$
      required

      Parameter name. Becomes a variable accessible inside the function body — referenced by name (no $ prefix). Convention: camelCase (e.g. amount, taxRate, startDate).

    • type
      Type: stringenum
      required

      Parameter type. For primitives (string, number, boolean), the bare type is enough. For object, pair with schemaKey + schemaVersion to pin the expected shape. For array, pair with itemType to declare the element type (and add schemaKey + schemaVersion when itemType is object).

      values
      • string
      • number
      • boolean
      • object
      • array
    • itemType
      Type: stringenum

      Element type when type is array. For arrays of objects, also set schemaKey + schemaVersion to pin the element shape.

      values
      • string
      • number
      • boolean
      • object
    • schemaKey
      Type: string

      Schema key pinning the expected shape. Required when type is object (or when type is array and itemType is object).

    • schemaVersion
      Type: string

      Version of the pinned schema (draft or a published semver).