JsonataFunctionResp

Full JSONata function — returned by GET /jsonata-functions/{key}, POST /jsonata-functions, PUT .../versions/draft, and POST .../versions/draft/publish. Carries the function's identity (metadata), signature + body (spec), and audit/publish metadata.

The optimistic-locking handle is returned in the HTTP ETag response header (RFC 7232) — capture it from the response and pass it back as If-Match on the next PUT / DELETE.

  • contentHash
    Type: string
    required

    Stable hash of the resource's content. Recomputed on every write (Create, Update, Publish), so it's available for both drafts and published versions. Useful for change detection — compare hashes across two snapshots (e.g. "did the draft actually change?" or "is the draft different from the latest published version?").

  • createdAt
    Type: stringFormat: date-time
    required

    When this version was created.

  • createdBy
    Type: object
    required

    Actor who created this version.

    • id
      Type: string
      required

      Stable ID for the actor (UUID for users; the API key's keyId for service accounts).

    • type
      Type: stringenum
      required
      values
      • user
      • api_key
  • metadata
    Type: object
    required

    The resource's identity and human-facing labels. Shared shape across all five resource kinds (blueprints, templates, schemas, assets, functions). The pair (key, version) is the canonical handle for any resource within a namespace.

    • key
      Type: string Pattern: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
      required

      Caller-supplied identifier, unique within the namespace per kind. Stable across versions — a blueprint's key doesn't change when you publish a new version. Snake_case; must start with a lowercase letter.

    • name
      Type: string
      max length:  
      200
      required

      Human-readable display name shown in Studio, list responses, and audit trails (max 200 chars).

    • version
      Type: string
      required

      Either draft (editable; only one draft per key at a time) or a semver like 1.2.0 (immutable once published). On create you choose: pass draft to iterate, or a semver to publish directly.

    • description
      Type: string
      max length:  
      1000

      Optional longer-form description. Helps both humans and AI assistants pick the right resource when browsing the catalog (max 1000 chars).

    • labels
      Type: object

      Arbitrary key/value tags for categorization and filtering — e.g. { "team": "people-ops", "env": "prod" }. Filterable on list endpoints via ?labels[key]=value.

  • spec
    Type: object
    required

    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).

    • 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.

    • 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).

  • updatedAt
    Type: stringFormat: date-time
    required

    When this version was last modified (drafts only — published versions are immutable).

  • apiVersion
    Type: string

    API version of the resource shape this function was stored against.

  • publishedAt
    Type: stringFormat: date-time

    When this version was published. Absent on drafts.

  • publishedBy
    Type: object

    Actor who published this version. Absent on drafts.

    • id
      Type: string
      required

      Stable ID for the actor (UUID for users; the API key's keyId for service accounts).

    • type
      Type: stringenum
      required
      values
      • user
      • api_key