13. Extensions and plugins

Contents of DISL 0.5

13.1 Plugin declarations

Plugins provide what the declarative core does not: exotic shapes, special routers and layouts, domain-specific widgets, imports/exports, snapping to external data, custom actions. A specification declares every plugin it uses:

{
  "plugins": {
    "acme.bpmnRouter": {
      "version": "^2.0.0",
      "provides": ["routing", "layout"],
      "required": false,
      "fallback": { "routing": "orthogonal", "layout": "layered" },
      "args": { "gridAware": { "type": "bool", "default": true } },
      "doc": "Specialised BPMN router that keeps sequence flows off pool boundaries.",
      "source": { "npm": "@acme/disl-bpmn-router", "integrity": "sha256-…" }
    }
  }
}

Property	Type	Description
`version`	SemVer range	Accepted plugin versions.
`provides`	string[]	Extension points: `shape`, `marker`, `lineEffect`, `routing`, `layout`, `snap`, `widget`, `action`, `celFunctions`, `import`, `export`, `persistenceFormat`, `collaboration`.
`required`	bool	If `true`, runtimes without the plugin MUST refuse to open diagrams of the type for editing (read-only viewing MAY still be offered). If `false`, `fallback` is used.
`fallback`	map extension point → built-in name	Declarative fallbacks.
`args`	map → Attribute	Declared arguments with types, so uses of the plugin are validated.
`source`	object	Hints where implementations can be obtained (`npm`, `maven`, `url`, …) with integrity hashes. Runtimes MUST NOT download and execute code automatically without user or administrator approval.
`celFunctions`	`{name, params, returns, cost, uses, deterministic, fallback, doc}`[]	Declarations of CEL functions the plugin adds, so validators can type-check expressions that use them (13.1.1).
`plans`	(`"add"`, `"set"`, `"remove"`, `"move"`, `"retype"`)[]	(DISL 0.3) For a `persistenceFormat` plugin: the model changes its `plan` operation accepts (FBL 0.2, section 11.2). Default `["add", "set", "remove"]`. A change it does not declare is sent as the changes it does: a `move` as a remove and an add, a `retype` as a remove and an add, with the host's warning.
`add`, `move`	`{position: bool}`	(DISL 0.3) For a `persistenceFormat` plugin: `position: true` declares that it honours the position of an add or a move, inserting there or refusing (FBL 0.2, section 11.2).
`doc`	Doc

Every plugin use ({ "plugin": "acme.bpmnRouter", "args": {…} }) references a declared plugin; args are validated against the declaration.

"net.etalii.adp.etalii.abmMarkdown": { "version": "^0.1.0", "provides": ["persistenceFormat"], "required": true,
  "plans": ["add", "set", "remove", "move", "retype"], "add": { "position": true }, "move": { "position": true } }

An agent behavior model's Markdown plugin plans a move, a retype and a positioned add as line splices of their own, so a node moved to another parent keeps its bytes.

13.1.1 Plugin functions in CEL

A celFunctions entry declares one function:

Property	Type	Description
`name`	simple identifier	The function's name. Required.
`params`	(string or `{name, type, doc}`)[]	The parameters in order: a CEL type (the 0.1 form), or an object that also names the parameter, for `fallback`.
`returns`	string	The CEL result type.
`cost`	int	The cost a validator charges per call (2.5).
`uses`	(`"diagram"`, `"env"`)[]	As for user functions (3.4): the implementation receives a read-only view of the working state, `env`, or both. Without it, the result MUST depend on the arguments only.
`deterministic`	bool	Whether the result depends only on the arguments and what `uses` names. Default `true`; `false` forbids calls in the deterministic contexts of 12.5.
`fallback`	CEL source	Evaluated in place of the call when the plugin is absent, over the named parameters.
`doc`	Doc

A plugin function MUST be called by its bare name, like a user function. Its name MUST NOT equal a function of 12.4, a user function (3.4) or another declared plugin function; a clash is a specification error.
Validators MUST type-check calls against the declaration (14.1, step 8) and charge its cost per call.
A plugin function MUST NOT change the model or any state visible to CEL.
When the plugin is absent, a call MUST evaluate fallback when one is declared; otherwise the call is an evaluation error, handled per the table of 2.5, so a constraint reports that it could not be evaluated and never passes. The runtime MUST report one std.pluginMissing finding (8.7) per missing plugin, not per call.
The rule for required: true is unchanged: a diagram whose required plugin is absent is not opened for editing, and read-only viewing follows the rules above.

{ "name": "rdfDisplayName", "params": [ { "name": "iri", "type": "string" } ], "returns": "string",
  "cost": 10, "uses": ["diagram"], "fallback": "rdfLocalName(iri) != '' ? rdfLocalName(iri) : iri",
  "doc": "An IRI as drawn: prefixed name under the file's prefixes, else the local name, else the IRI." }

An RDF graph shows prefixed names through its Turtle plugin, which knows the file's prefixes; without the plugin, its cards fall back to local names.

13.2 Extension properties and profiles

x- properties (2.8) carry tool-specific data. A group of related extension properties MAY be documented as a profile — a JSON Schema published by a vendor or community that constrains x-<prefix>-* properties. Specifications list profiles they use in language.profiles: ["https://…/simulation-profile.json"]; validators that know a profile validate accordingly.