Definitions and Versioning

DMN models are stored as definitions in your project. Every save creates a new immutable version under the same definition identity — there's no separate deploy step like BPMN has, and a freshly-saved version is callable immediately.

Concepts

Concept	Identifier	What it is
Definition	definitionsID (from the DMN XML's outer <definitions id="…">)	The stable identity of a DMN model across versions. The same definitionsID is shared by every version of the model
Version	platform UUID + integer version	One stored revision of a definition. Each save auto-increments the version number for that definitionsID
Decision	decisionID (from <decision id="…">)	One decision node inside a definition. A definition usually contains several

Two ways to address a definition in the API:

• Platform UUID (definitionID path parameter on most endpoints) — points at one specific stored version. Stable forever.
• DMN definitions id (definitionsID path parameter on the by-definitions-id/… endpoints) — points at the definition logically; resolves to the latest version unless a specific version is requested.

This mirrors BPMN, where the outer <definitions id> is also exposed as definitionsID. Use the definitionsID form when callers know decisions by their model-level identifier; use the platform UUID when you need to pin to a specific version.

Lifecycle

   ┌──────────────┐    save     ┌──────────────────┐
   │  In modeler  │ ──────────► │  Stored version  │
   │  (browser)   │             │   (immutable,    │
   │              │             │    evaluable)    │
   └──────────────┘             └──────────────────┘
                                        │
                                edit / save again
                                        │
                                        ▼
                                ┌──────────────────┐
                                │ New version, same│
                                │  definitionsID   │
                                └──────────────────┘

Three things to know:

• No separate deploy step. Once a version is stored it can be evaluated, listed, and called by name from BPMN business-rule tasks.
• Versions are immutable. To change the logic, save a new version with the same definitionsID. Old versions stay around for re-evaluation against historical inputs and to keep instance history meaningful.
• Old versions can be deleted individually. Past executions remain in history regardless — deleting the version that ran them doesn't erase the audit trail.

The Models view

Open DMN Models from the navigation. One row per definitionsID, showing the latest version's metadata:

Column	Description
Definitions ID	The stable <definitions> ID from the DMN XML
Name	Display name from the latest version
Latest Version	Version number of the most recent save
Created at	When the latest version was saved
Actions	Open the latest in the modeler, view version history, delete

A New button (visible to project Editors and Admins) opens an empty modeler.

The Definition Detail view

Drill into a definition to see all of its versions, latest first:

Column	Description
Version	Sequential v1, v2, … per definitionsID
Name	Display name as set when that version was saved
Created at	Save timestamp
Created by	The user who saved that version
Actions	Open in modeler, delete (Editor / Admin role only)

Past executions of a deleted version stay in history — deleting a version cleans up the model itself, not its audit trail.

The Decisions list

The DMN Decisions view aggregates by individual decision (rather than by definition). One row per unique decision XML id across the project:

Column	Description
Decision ID	The id attribute on <decision>
Decision name	Human-readable name
Owning definition	Which definitionsID this decision lives in
Latest version	The most recent version of the owning definition

Use this view when wiring a BPMN business-rule task — the quantum:calledDecision decisionId="…" extension expects a decision XML id, and this list is the catalogue.

Saving from the modeler

The DMN modeler doesn't ship the same overwrite-vs-new-version dialog the BPMN modeler does. Saving stores a new version under the same definitionsID as the model being edited. The first save of a brand-new model establishes the definitionsID; subsequent saves keep it stable and increment the version.

For the modeler UI itself, see The DMN Editor.

API reference

Endpoint	Use
GET /projects/{projectID}/dmn/definitions/latest	List the latest version of each definition (drives the Models view)
GET /projects/{projectID}/dmn/definitions	List all stored versions across the project
GET /projects/{projectID}/dmn/definitions/by-definitions-id/{definitionsID}	Get the latest version (or a specific version) of a definition addressed by its DMN <definitions id>
GET /projects/{projectID}/dmn/definitions/by-definitions-id/{definitionsID}/versions	List every version of one definition, newest to oldest
GET /projects/{projectID}/dmn/definitions/{definitionID}	Get a single version by platform UUID
POST /projects/{projectID}/dmn/definitions	Save a new version. Pass the same XML <definitions id> to add a version under an existing definition; use a new id to create a fresh one
PUT /projects/{projectID}/dmn/definitions/{definitionID}	Update display name on a stored version. The DMN XML and version number themselves are immutable — to change logic, save a new version
DELETE /projects/{projectID}/dmn/definitions/{definitionID}	Delete a single version. Past executions of the deleted version remain in history
GET /projects/{projectID}/dmn/decisions	List one entry per decision XML id in the project

The save endpoint accepts:

{
  "name": "Underwriting rules",
  "xml": "<definitions xmlns=\"https://www.omg.org/spec/DMN/20240513/MODEL/\" id=\"underwriting\">…</definitions>",
  "version": 3
}

name is the display label and xml is the DMN body. version is optional — leave it out and the server auto-increments per definitionsID.

For evaluating a stored definition, see Evaluation and history.