BlueprintSpec

The blueprint's content. Only envelopes is required — at minimum a blueprint bundles documents to render. From there, optional fields layer on capability:

  • Add inputs to declare data the caller must supply when running the blueprint.
  • Add participants to declare the parties involved.
  • Add orchestration to drive those participants through a signing flow.

Without orchestration, a blueprint is a document rendering engine — it generates documents from templates and (optionally) inputs, but doesn't trigger any signing. Add orchestration (typically with participants) to turn it into a full signing workflow.

customFields and functions are auxiliary: customFields carry runtime metadata; functions pin JSONata functions referenced by expressions inside the blueprint.

  • envelopes
    Type: array object[] · BlueprintEnvelope[]
    required

    Required. Envelopes bundle documents that get rendered together (and, if orchestration is present, signed together).

    An envelope bundles documents that get rendered (and, if orchestration is present, signed) together. Multiple envelopes split a single blueprint into independent signing sessions — each envelope generates its own emails to participants and tracks its own completion state.

    • documents
      Type: array object[]
      required

      Documents within this envelope. Each document specifies what to render — either through a template (templateKey + templateVersion), directly from an uploaded file (fileId), or a template with a fileId override. At least one of templateKey or fileId must be set per document.

    • key
      Type: string
      required

      Unique identifier for this envelope within the blueprint. Referenced by action.envelopeKey on participant steps.

    • subject
      Type: string
      required

      Subject line used in email notifications sent to participants for this envelope (e.g. "Your offer letter from Acme Corp"). Free-form text — what recipients see in their inbox.

    • resolutionMode
      Type: stringenum

      When the envelope's documents are materialized:

      • immediate (default) — documents render at workflow creation, using the inputs supplied at that point. Use when input data is fully known up front.
      • just_in_time — documents render right before the participant signs, using whatever input data is current then. Use when earlier steps update the entity data that this envelope's templates consume.
      values
      • immediate
      • just_in_time
  • customFields
    Type: array object[] · CustomFieldConfig[]

    Custom fields whose values are computed at run time and carried alongside the blueprint output.

    Caller-extensible field carried alongside the blueprint at run time. Unlike inputs (data the caller supplies) or template fields (placed on documents), custom fields are arbitrary key/value metadata — useful for tagging workflows with reference IDs, deal numbers, or computed flags that downstream systems consume.

    • key
      Type: string
      required

      Unique identifier for this custom field. Used as the property name when the value is exposed downstream.

    • name
      Type: string
      required

      Human-readable label shown in Studio.

    • value

      Value for the custom field (can be literal or JSONata expression)

      • Type: string

        Value for the custom field (can be literal or JSONata expression)

  • functions
    Type: array object[]

    JSONata functions referenced by expressions inside the blueprint. Each entry pins a specific function key + version, 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 functions without rewriting every expression.

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

  • inputs
    Type: array object[] · Input[]

    Optional. Entity inputs the caller must supply when running this blueprint. Omit if the blueprint's templates need no caller-supplied data.

    • key
      Type: string
      required

      Unique identifier for this input

    • required
      required

      Whether this entity slot must be populated (boolean literal or JSONata expression)

      • Type: boolean

        Whether this entity slot must be populated (boolean literal or JSONata expression)

    • schemaKey
      Type: string
      required

      Key of the schema that defines this entity's structure

    • schemaVersion
      Type: string
      required

      Schema version. Either a semantic version (e.g. 1.2.0) or draft while the parent blueprint is itself a draft.

    • description
      Type: string

      Description of what this input represents

    • name
      Type: string

      Human-readable name for this input

  • orchestration
    Type: object

    Optional. Root step of the signing flow. Just two primitives:

    • participant — one task assigned to a participant. Set participantKey and action.
    • group — a container that runs children either sequentially or in parallel, with optional completion (all / any / quorum).

    Groups nest — that's the entire composition mechanism. From these two primitives plus nesting you can model any signing flow:

    • Linear chain — group:sequential of participants: A signs, then B, then C.
    • Parallel sign-off — group:parallel of participants: board members sign concurrently.
    • Phased approvals — group:sequential whose children are group:parallels: each phase opens after the previous one completes; signers within a phase work in parallel.
    • Quorum — group:parallel with completion: quorum, quorum: 2: first 2 of 3 approvers wins; the third is skipped.
    • Conditional branches — includeIf on any step gates the path on a JSONata expression evaluated at run time.

    onComplete on any step adds validation or entity-data updates when the step finishes — useful for chaining state forward (e.g. write the manager's signed-off salary into the next phase's inputs).

    Omit orchestration entirely to use the blueprint as a document rendering engine with no signing flow.

    • key
      Type: string
      required

      Unique identifier for this step within the orchestration.

    • type
      Type: stringenum
      required

      group for a container that runs children; participant for a single signer task.

      values
      • group
      • participant
    • action
      Type: object

      What the participant does at this step (participant steps only).

    • children
      Type: array object[] · BlueprintStep[]

      Nested steps (group steps only). Recursive — each child is itself a BlueprintStep.

      A step in the blueprint's orchestration tree — either a participant (one task assigned to a participant) or a group (a container of nested children).

    • completion
      Type: stringenum

      When the group is considered complete (group steps only):

      • all (default) — every child must complete before the group is done.
      • any — the group completes as soon as any one child completes; remaining children no longer block.
      • quorum — the group completes as soon as at least N children complete, where N is set in the quorum field below.
      values
      • all
      • any
      • quorum
    • execution
      Type: stringenum

      How children execute (group steps only). sequential runs them in order; parallel runs them concurrently.

      values
      • sequential
      • parallel
    • includeIf
      Type: string

      Optional JSONata expression evaluated at run time. If it returns false, this step is skipped.

    • name
      Type: string

      Optional human-readable label shown in Studio and in audit/event logs. The key is the machine-readable handle.

    • onComplete
      Type: object

      Optional hooks that run when this step completes.

    • participantKey
      Type: string

      Participant whose action this step represents (participant steps only). Must match a key in spec.participants.

    • quorum
      Type: integer
      min:  
      1

      The number of children that must complete to satisfy the group. Required when completion is quorum (ignored otherwise). Example: quorum: 2 with 3 children means the group completes as soon as any 2 of them complete.

  • participants
    Type: array object[] · BlueprintParticipant[]

    Optional. Roles involved in the blueprint. Each participant's name/email may be bound dynamically from inputs via JSONata expressions. Omit for pure document-rendering blueprints (no signing).

    A party involved in the blueprint. key and name define the role slot ("Hiring Manager", "Candidate"); participantName and participantEmail resolve to the actual person at run time, either as literals or via JSONata expressions that derive them from inputs.

    • key
      Type: string
      required

      Unique identifier for this participant within the blueprint.

    • name
      Type: string
      required

      Human-readable role label shown in Studio and audit trails (e.g. "Hiring Manager"). Distinct from the resolved person's name — that comes from participantName.

    • participantEmail
      required

      Resolved email of the actual person filling this participant slot at run time. Either a literal string or a JSONata expression that derives the email from inputs (e.g. { "expression": "candidate.email" }). Required — a participant whose email doesn't resolve at run time would otherwise be silently dropped from the workflow.

      • Type: string

        Resolved email of the actual person filling this participant slot at run time. Either a literal string or a JSONata expression that derives the email from inputs (e.g. { "expression": "candidate.email" }). Required — a participant whose email doesn't resolve at run time would otherwise be silently dropped from the workflow.

    • participantName
      required

      Resolved name of the actual person filling this participant slot at run time. Either a literal string or a JSONata expression that derives the name from inputs (e.g. { "expression": "candidate.fullName" }). Required — a participant whose name doesn't resolve at run time would otherwise be silently dropped from the workflow.

      • Type: string

        Resolved name of the actual person filling this participant slot at run time. Either a literal string or a JSONata expression that derives the name from inputs (e.g. { "expression": "candidate.fullName" }). Required — a participant whose name doesn't resolve at run time would otherwise be silently dropped from the workflow.

    • roleCategory
      Type: string

      Optional category for grouping or filtering participants (e.g. "Signer", "Reviewer").