blueprint-builder

Blueprint Builder Skill

Sorcha blueprints define multi-participant workflows as JSON documents. Each blueprint has participants, actions (with data schemas), and routes that determine the action flow. Templates wrap blueprints with parameterization for reuse.

Quick Start

Minimal Blueprint (Two-Party, No Cycles)

{
  "id": "my-blueprint",
  "title": "My Workflow",
  "description": "A simple two-participant workflow (min 5 chars)",
  "version": 1,
  "metadata": { "category": "demo" },
  "participants": [
    { "id": "sender", "name": "Sender", "description": "Initiates the workflow" },
    { "id": "receiver", "name": "Receiver", "description": "Receives and completes" }
  ],
  "actions": [
    {
      "id": 0,
      "title": "Submit",
      "sender": "sender",
      "isStartingAction": true,
      "dataSchemas": [
        {
          "type": "object",
          "properties": {
            "message": { "type": "string", "minLength": 1 }
          },
          "required": ["message"]
        }
      ],
      "routes": [
        { "id": "to-receiver", "nextActionIds": [1], "isDefault": true }
      ]
    },
    {
      "id": 1,
      "title": "Complete",
      "sender": "receiver",
      "dataSchemas": [
        {
          "type": "object",
          "properties": {
            "status": { "type": "string", "enum": ["accepted", "rejected"] }
          },
          "required": ["status"]
        }
      ],
      "routes": []
    }
  ]
}

Cyclic Blueprint (Looping Workflow)

{
  "metadata": { "hasCycles": "true" },
  "actions": [
    {
      "id": 0, "title": "Ping", "sender": "ping", "isStartingAction": true,
      "routes": [{ "id": "ping-to-pong", "nextActionIds": [1], "isDefault": true }]
    },
    {
      "id": 1, "title": "Pong", "sender": "pong",
      "routes": [{ "id": "pong-to-ping", "nextActionIds": [0], "isDefault": true }]
    }
  ]
}

Cycle detection produces warnings (not errors). Cyclic blueprints publish with metadata["hasCycles"] = "true".

Key Concepts

Instance Reference

Define instanceReference to give each workflow instance a human-readable id instead of a bare GUID:

"instanceReference": {
  "prefix": "CP",
  "components": [
    { "field": "/projectName", "transform": "FirstWord", "chars": 3 },
    { "field": "/siteAddress", "transform": "FirstWord", "chars": 3 }
  ]
}

• prefix — 1–5 uppercase alpha chars identifying the workflow type.
• components — 1–5 field extractions from the starting action's schema.
• transform — FirstWord (split on space, take first) or Truncate (first N chars). Output is uppercased.
• A 4-char uniqueness hash is appended automatically.

⚠ The reference is public metadata. Any field value you reference here is visible in plaintext on the instance, outside the encrypted disclosure groups. Never build one from a name, date of birth, or any other identifying value — pick a project/site/case field.

Open Participants & Late Binding

isStartingAction: true already encodes "open" semantics end-to-end. There is no separate openSubmission flag and no bindingPolicy block — IsStartingAction is the open flag, and credentialRequirements is the gate. Use these correctly and the runtime does the rest.

What the runtime already does for starting actions

Line numbers are indicative (verified 2026-06); they drift — grep the method bodies if a citation misses.

Author rules

1. Participants targeted by a starting action MUST have walletAddress null in the published blueprint. Do not pre-fill the wallet at publish time. The strict-equality check (ActionExecutionService.cs:~236-248) only fires when walletAddress is set, so a baked-in wallet defeats late binding and rejects every real submitter.
2. All other participants (case officers, assessors, internal roles) should have a known walletAddress at publish time — they are not open.
3. Credential-bootstrapped flows (e.g. "Driving Licence" requires a AssuredIdentityCredential to start) belong on the starting action's credentialRequirements, not on a new flag. The runtime gates the open submission on credential possession before binding the participant.
4. Once bound, the binding is canonical for that instance. Subsequent actions resolve disclosures, recipients, and credential issuance targets via instance.ParticipantWallets[participantId], not via the blueprint's null wallet.

Open citizen application (Assured Identity Phase 1 pattern)

{
  "participants": [
    { "id": "citizen", "name": "Citizen", "organisation": "Public" }       // walletAddress OMITTED
    { "id": "analyst", "name": "Verification Analyst", "walletAddress": "ws1..." }
  ],
  "actions": [
    {
      "id": 1,
      "isStartingAction": true,        // open — anyone with a wallet can submit
      "sender": "citizen",              // participant resolved by late binding
      "dataSchemas": [ /* personal details */ ],
      "routes": [{ "id": "to-review", "nextActionIds": [2], "isDefault": true }]
    },
    {
      "id": 2,
      "sender": "assessor",             // pre-bound
      "requiredPriorActions": [1],
      "credentialIssuanceConfig": { "recipientParticipantId": "citizen", ... }
    }
  ]
}

Credential-bootstrapped application (Driving Licence pattern — Assured Identity Phase 2)

{
  "participants": [
    { "id": "applicant", "name": "Applicant", "organisation": "Public" }   // walletAddress OMITTED
    { "id": "council",   "name": "Council Officer", "walletAddress": "ws1..." }
  ],
  "actions": [
    {
      "id": 1,
      "isStartingAction": true,
      "sender": "applicant",
      "credentialRequirements": [
        {
          "type": "https://sorcha.dev/vc/assured-identity/v1",
          "presentationSource": "HaipExternalWallet",
          "requiredClaims": [ { "claimName": "givenName" }, { "claimName": "dateOfBirth" } ]
        }
      ],
      "dataSchemas": [ /* licence-specific fields only — identity comes from the credential */ ]
    }
  ]
}

The applicant doesn't authenticate as a pre-existing identity; they prove they hold an AssuredIdentityCredential and that fact binds them as the applicant. The HAIP presentation pipeline runs before the late-bind block.

Common foot-guns

• Don't pre-bind the citizen wallet in walkthroughs. A walletMap[citizen] = someWallet at publish time will lock the participant to that single wallet and reject every real public submitter with "Wallet X is not authorized to execute action 1. This action requires participant 'citizen' with wallet 'Y'." Strip the open participants out of your wallet map.
• Don't rely on starting-action open semantics for sensitive roles. If the starting participant should be restricted, either set their walletAddress (closed) or attach credentialRequirements (gated). Open + no requirements = anyone with a JWT can become that participant.
• Re-binding is immutable. Once instance.ParticipantWallets[citizen] is set, attempting to submit again from a different wallet throws. If a workflow needs an applicant to "swap identity", that is a new instance.

Reusable Schema Components (Sorcha core library)

Status: Shipped (Feature 103). The resolver (SchemaRefResolver.cs, prefix https://schemas.sorcha.dev/core/, child-wins layout override) and the startup seeder (CoreSchemaSeedService.cs) are live; the five catalog primitives exist on disk under blueprints/schemas/sorcha-core/*.json; and PublishService.PublishAsync flattens $refs (FlattenActionSchemas) before validation, surfacing SchemaRefResolutionException as a publish error. Blueprints SHOULD prefer $ref to a core component over inlining identity primitives. Design spec: docs/superpowers/specs/2026-04-13-verified-citizen-v2-design.md.

Why

Identity primitives (a person's name, date of birth, email, postal address) appear in every citizen-facing blueprint. Inlining the JSON Schema for them in each blueprint duplicates validation, layout, persona bindings, and address-lookup

Content truncated.