BPMN structure, vendor namespaces and lane → actor

Check a DAK’s BPMN (validate.ts beside this file; bean folio-assistant-tgaj, which replaced four Python validators with it): well-formed XML whose root is <bpmn:definitions>, no Camunda or Zeebe namespace, no duplicate id, at least one process, no bpmn-moddle (bpmn-js) import warning; every process has a <laneSet>, every flow node sits in a lane, and lane ids are unique and valid FSH ids; and every innermost lane names its actor by id: its partitionElementRef (a top-level <bpmn:resource>), else its own id, matched exactly against the Instance: ids of the ActorDefinitions in the IG’s FSH (or JSON) and, for a harness process, the role ids of the mounted layers’ scenarios/roles.json. Never by file name or title. With no file named it reads the declared process directories, smart-base/**/processes/ and an IG’s input/bpmn/.

Skills it satisfies

A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.

smart-base-tools

Source: smart-base/skills/content/authoring-who-smart-guidelines/smart-base-tools.md.

Also satisfied by: extract-dak, kg-extract-dak, bpmn-graphviz-layout, bpmn-to-fsh, kg-extract-bpmn, kg-extract-citations, kg-extract-dmn, kg-extract-l3.

The skill declares no I/O contract (schemas/skills/smart-base-tools/{input,output}.schema.json).

Inputs and outputs

Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.

porttyperequireddescriptionconstraint
inbpmnRepoPathThe .bpmn files to check; when absent, every .bpmn under the declared process directories (or, with --changed <ref>, those the branch changed).string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
infshRepoPathDirectories of ActorDefinition FSH or JSON; default input/fsh and input/resources.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
inrolesRepoPathscenarios/roles.json files whose role ids a harness lane may bind; default those of smart-base and the mounted cat-harness, fhir-harness and folio-assistant-core.string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments.
outreportTextOne ✗ line per error and ! per warning, then a count. Exit 0 no error, 1 an error, 2 nothing to check (not a pass). --json prints the findings as data.string · A short single-line human string. Not admissible as a command-line argument.

Processes and tasks

Steps this Tool can carry out, because each names a skill it satisfies:

processsteplanevia skill
SMART Guideline end to end3 · Choose L2 dependencies (WHO / jurisdiction DAKs)Authoring agentsmart-base-tools
SMART Guideline end to end4 · Create / adapt L2 DAK assetsAuthoring agentsmart-base-tools
SMART Guideline end to end5 · Choose L3 dependencies (WHO / jurisdiction IGs)Authoring agentsmart-base-tools
SMART Guideline end to end6 · Produce L3 assetsAuthoring agentsmart-base-tools

How it is deployed and reached

  • Command line. From the repository root: bun run smart-base/L2-bpmn/tools/bpmn-validate/validate.ts [file.bpmn ...] [--root <repo>] [--fsh <dir>]... [--roles <roles.json>]... [--changed <git ref>] [--json] [--verbose].
  • GitHub Actions. No workflow in this checkout runs its command.

As an API: its operation in the OpenAPI document and the MCP tool list of its layer.

installnone
runtimebun
networkno
when to choose it
whenA DAK’s business process (L2, BPMN) is added or edited, before review (skill l2-component-edit-review, the BPMN row’s checker), and on every pull request that changes a .bpmn.
limitsAn ActorDefinition a dependency IG declares is found only when its FSH or JSON directory is passed with --fsh. Reads lanes, not pools: a participant whose process has no lanes is reported as a process with no laneSet. A lane bound to a harness role is accepted here; whether that role is equipped is cat-harness’s role-model check (kg:audit). A published DAK whose processes are still Visio figures is crosswalked against its personas by smart-base/scripts/dak-swimlanes.ts (always on, beside the web-annex kind’s dak-swimlanes/v1 validator), not by this Tool. It does not draw the diagram (render:bpmn does) or check DI completeness.
costSeconds, no network.

What it is made of

Linked data

The Tool is published as its own JSON-LD document at its IRI, http://smart.who.int/base/tools/bpmn-validate.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.

{
  "@context": "http://smart.who.int/base/smart-base.context.jsonld",
  "@id": "http://smart.who.int/base/tools/bpmn-validate.jsonld",
  "@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
  "partOf": "http://smart.who.int/base/smart-base.jsonld",
  "name": "bpmn-validate",
  "title": "BPMN structure, vendor namespaces and lane → actor",
  "description": "Check a DAK's BPMN (`validate.ts` beside this file; bean folio-assistant-tgaj, which replaced four Python validators with it): well-formed XML whose root is `<bpmn:definitions>`, no Camunda or Zeebe namespace, no duplicate id, at least one process, no bpmn-moddle (bpmn-js) import warning; every process has a `<laneSet>`, every flow node sits in a lane, and lane ids are unique and valid FSH ids; and every innermost lane names its actor by id: its `partitionElementRef` (a top-level `<bpmn:resource>`), else its own id, matched exactly against the `Instance:` ids of the ActorDefinitions in the IG's FSH (or JSON) and, for a harness process, the role ids of the mounted layers' `scenarios/roles.json`. Never by file name or title. With no file named it reads the declared process directories, `smart-base/**/processes/` and an IG's `input/bpmn/`.",
  "install": {
    "none": true
  },
  "invoke": {
    "shell": "bun run smart-base/L2-bpmn/tools/bpmn-validate/validate.ts [file.bpmn ...] [--root <repo>] [--fsh <dir>]... [--roles <roles.json>]... [--changed <git ref>] [--json] [--verbose]"
  },
  "io": {
    "inputs": [
      {
        "name": "bpmn",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "The .bpmn files to check; when absent, every .bpmn under the declared process directories (or, with `--changed <ref>`, those the branch changed).",
        "required": false
      },
      {
        "name": "fsh",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "Directories of ActorDefinition FSH or JSON; default `input/fsh` and `input/resources`.",
        "required": false,
        "arg": {
          "flag": "--fsh"
        }
      },
      {
        "name": "roles",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
        "description": "`scenarios/roles.json` files whose role ids a harness lane may bind; default those of smart-base and the mounted cat-harness, fhir-harness and folio-assistant-core.",
        "required": false,
        "arg": {
          "flag": "--roles"
        }
      }
    ],
    "outputs": [
      {
        "name": "report",
        "schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/Text",
        "description": "One `✗` line per error and `!` per warning, then a count. Exit 0 no error, 1 an error, 2 nothing to check (not a pass). `--json` prints the findings as data."
      }
    ]
  },
  "satisfies": [
    "smart-base-tools"
  ],
  "requirements": {
    "runtime": [
      "bun"
    ],
    "network": false
  },
  "selection": {
    "when": "A DAK's business process (L2, BPMN) is added or edited, before review (skill `l2-component-edit-review`, the BPMN row's checker), and on every pull request that changes a `.bpmn`.",
    "limits": "An ActorDefinition a dependency IG declares is found only when its FSH or JSON directory is passed with `--fsh`. Reads lanes, not pools: a participant whose process has no lanes is reported as a process with no laneSet. A lane bound to a harness role is accepted here; whether that role is equipped is cat-harness's `role-model` check (`kg:audit`). A published DAK whose processes are still Visio figures is crosswalked against its personas by `smart-base/scripts/dak-swimlanes.ts` (always on, beside the `web-annex` kind's `dak-swimlanes/v1` validator), not by this Tool. It does not draw the diagram (`render:bpmn` does) or check DI completeness.",
    "cost": "Seconds, no network."
  }
}

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev