This is a tool for the validation of Decision Model Notation (DMN) files. It performs various static analyses to detect inconsistencies and bugs in your decision models.
You can use dmn-check in six ways.
- As a Maven or Gradle plugin that can be integrated into your build process and continues integration to prevent bugs from slipping into your artifacts.
- Integrated into the Camunda Modeler via the dmn-check plugin.
- Integrated into your custom tools by using the artifacts dmn-check-core or dmn-check-validators.
- As a standalone CLI tool.
- As a Docker image (e.g. in you CI pipeline).
- Integrated in dmnmgr.
Currently, dmn-check checks among others for the following:
- Duplicate rules
- Conflicting rules
- Shadowed rules
- Types of the expressions
- Correct use of enumerations
- Correctly connected requirement graphs
In section validations, you find a complete list with detailed descriptions of what they do.
Most properties and invariants that are validated by dmn-check are described informally in
the DMN specification. In case you have questions about a validations it might be worth
to skim the specification.
This plugin requires Java 17 or later and Apache Maven 3 or later. Some analyses are tailored towards the Camunda DMN implementation and might not work for different DMN implementations.
dmn-check can be used either as a normal Maven plugin inside your projects pom.xml or as a standalone program.
The following example shows the basic configuration of the plugin:
<plugin>
<groupId>de.redsix</groupId>
<artifactId>dmn-check-maven-plugin</artifactId>
<version>...</version>
<executions>
<execution>
<phase>verify</phase>
<goals>
<goal>check-dmn</goal>
</goals>
</execution>
</executions>
</plugin>
Using this configuration, the plugin will search all folders of the current project for files with the extension .dmn and apply all
available validators. It is possible to provide a set of search paths instead, as well as to ignore certain files and specify the validators
that should be executed. The following example shows how you can make use of these options by restricting the search path to the
folders src/ and model/, as well as ignoring file test.dmn. The configuration further specifies that only
the ShadowedRuleValidator should be executed. To specify validators, you have to use the fully-qualified name.
<configuration>
<searchPaths>
<searchPath>src/</searchPath>
<searchPath>model/</searchPath>
</searchPaths>
<excludes>
<exclude>test.dmn</exclude>
</excludes>
<validatorClasses>
<validatorClass>de.redsix.dmncheck.validators.ShadowedRuleValidator</validatorClass>
</validatorClasses>
</configuration>
Additionally, the failOnWarning (default is false) parameter can be set to fail a Maven execution if there are
validation errors with Warning severity.
<configuration>
<failOnWarning>true</failOnWarning>
</configuration>
To use dmn-check without or outside a Maven project, you can invoke it in the following way
mvn de.redsix:dmn-check-maven-plugin:check-dmn
This plugin requires Java 11 or later and Gradle 6.5 or later. Some analyses are tailored towards the Camunda DMN implementation and might not work for different DMN implementations.
dmnmgr is a toolkit incoperating the Camunda DMN implementation and providing tools to develop DMN based applications in cross-functional teams. It ships with a dmn-check integration and visualizes the warnings and errors in the graphical representation of the DMN model. You need to install the dmnmgr-client and dmnmgr-server to use it.
A Docker image containing dmn-check is available from the GitHub Container Registry and you can pull the latest version by executing
docker pull ghcr.io/red6/dmn-check:latest
If you want to use docker run to execute dmn-check you have to mount the directory containing the DMN files into
the container and set the search path appropriately, e.g.
docker run -v ~/dmn-files:/dmn-files ghcr.io/red6/dmn-check:latest --searchPath=/dmn-files
If you want to use the Docker image in a Gitlab pipeline you have to overwrite the entrypoint and call dmn-check directly.
In the following example of a Gitlab Pipeline, we specify the project classpath as well, to make the enum validation possible.
variables:
MAVEN_OPTS: "-Dmaven.repo.local=.m2/repository"
default:
artifacts:
paths:
- ./cp.txt
- .m2/repository
stages:
- analysis
image:
name: ghcr.io/red6/dmn-check:latest
entrypoint: [ "" ]
create-classpath-for-dmn-check:
image: adoptopenjdk/maven-openjdk11
stage: analysis
script: mvn dependency:build-classpath --settings .m2/settings.xml --batch-mode -Dmdep.outputFile=cp.txt
dmn-check:
stage: analysis
needs:
- create-classpath-for-dmn-check
script: |
/opt/java/openjdk/bin/java -cp /app/resources:/app/classes:/app/libs/* de.redsix.dmncheck.cli.Main --projectClasspath=$(< cp.txt)
The following subsections describe the available validations in detail. The DMN decision tables used in this section are derived from an example on camunda.org.
Consider the following DMN decision table with hit policy UNIQUE:
| Season ᴵᴺᴾᵁᵀ | How many guests ᴵᴺᴾᵁᵀ | Dish ᴼᵁᵀᴾᵁᵀ | |
|---|---|---|---|
| 1 | "Fall" | <= 8 | "Spareribs" |
| 2 | "Winter" | <= 8 | "Roastbeef" |
| 3 | "Spring" | [5..8] | "Steak" |
| 4 | "Winter" | <= 8 | "Roastbeef" |
It is pretty obvious that rule number two is a duplicate of rule number four. This is not allowed by the UNIQUE hit policy
and thus an error.
Definition: A rule is a duplicate of another rule if and only if all inputs and outputs of those rules are identical.
dmn-check will report duplicate rules for all decision tables except for those with hit policy COLLECT.
Conflicting rules are somewhat similar to duplicate rules. Consider the following example with hit policy UNIQUE:
| Season ᴵᴺᴾᵁᵀ | How many guests ᴵᴺᴾᵁᵀ | Dish ᴼᵁᵀᴾᵁᵀ | |
|---|---|---|---|
| 1 | "Fall" | <= 8 | "Spareribs" |
| 2 | "Winter" | <= 8 | "Roastbeef" |
| 3 | "Spring" | [5..8] | "Steak" |
| 4 | "Winter" | <= 8 | "Stew" |
We look again a rule two and four. This time, all their inputs are identical, but they differ in the output. This is arguably worse than a duplicate rule, since it may produce different results depending on the evaluation order of the decision table. Assuming that the runtime does not detect those inconsistencies.
Definition: Rule r is in conflict with rule s if and only if all inputs of rules r and s are identical and if they differ
in at lease one output.
dmn-check will report duplicate rules for all decision tables, except for those with hit policy COLLECT and RULE_ORDER.
Some rules prevent others from even being considered. Have a look at the following example with hit policy FIRST:
| Season ᴵᴺᴾᵁᵀ | How many guests ᴵᴺᴾᵁᵀ | Dish ᴼᵁᵀᴾᵁᵀ | |
|---|---|---|---|
| 1 | "Fall" | <= 8 | "Spareribs" |
| 2 | "Winter" | <= 8 | "Roastbeef" |
| 3 | – | – | "Stew" |
| 4 | "Spring" | [5..8] | "Steak" |
This example contains no duplicate rules and no conflicting rules. However, all inputs of rule three are empty (represented with a dash in
this example). As empty inputs match everything and since we assume hit policy FIRST rule four will never match as rule three matches for
all possible inputs. Therefore, stew is served to the guests of 5 to 8 in Spring. Assuming that each rule serves a purpose, shadowed rules are
always an error as they will never be matched.
Definition: Rule r shadows rule s if and only if the inputs of rule r matches at least for all values for which the inputs of
rule s match.
dmn-check will report duplicate rules for all decision tables except for those with hit policy COLLECT and RULE_ORDER.
DMN offers a rich expression language called Friendly Enough Expression Language (FEEL) that can be used to describe the conditions for the input entries. However, as with most
expression languages, not all syntactically possible expressions are valid (have semantic). dmn-check integrates a type checker for the
FEEL expression language that ensures that a decision table contains only well-typed expressions.
An example of an ill-typed expression is [1..true] which would describe the range between 1 and true which is (at lease in FEEL) not a
valid expression. In contrast, [1..9] is well-typed and describes the numbers from 1 to 9.
| FEEL-Expression | Type |
|---|---|
| true | boolean |
| [1..3] | integer |
| [1.."string"] | ✘ |
| 1, 2, true | ✘ |
| > 5 | integer |
| > true | ✘ |
Of course the type declaration is validated as well.
Decision-making often involves a fixed set of values (e.g. a list of supported currencies) and therefore those values are used in DMN
decision tables. Those values are often implemented in form of Java enums. dmn-check also to specify the fully-qualified class name of an
enum in the type declaration of the input- / output-column and checks the values in the DMN decision table against the enum implementation.
By default dmn-check uses the project dependencies to resolve the enums. As this is not possible in the Maven
standalone mode, you can specify the classpath that is used to resolve the enums
mvn de.redsix:dmn-check-maven-plugin:check-dmn -Dclasspath=foo.jar,bar.jar
The DMN standard also provides a way to connect decisions tables with each other and to model inputs and knowledge sources. The resulting graphs are called Decision Requirement Graphs (DRG).
dmn-check verifies that a Decision Requirement Graph
- is connected
- is acyclic and directed
- ensures compatibility of in- and outputs
- has only one leaf node (i.e. exactly one node determines the output)
- has no (self-) loops
In the following example, decision table Dish has Season and How many guests as inputs, but instead of the input Season there is an
input Lunar phase connected to the decision table.
graph TD;
x(Lunar phase)-->Dish;
y(How many guests)-->Dish;
Dish-->Beverages;
z(Guests with children)-->Beverages;
The DMN standard allows the aggregation of values for hit policy collect. For example, you can compute the sum of all matching rows in a decision table. You could use this feature to calculate a credit score.
We ensure that those aggregations are only applied to columns with a numeric type. In addition, we validate that aggregations are only used when hit policy collect is used.
Usually you do not have to care much about ids and names of DMN elements. However, during upgrades and refactoring it might happen that an id or a name is lost. Those errors usually stay unnoticed for a long time. Depending on the scenario missing ids or names might break your decision model or make error analysis tricky.
dmn-check validates that the following DMN elements always have an id and a name:
- Decision
- Definition
- InputData
- ItemDefinition
- KnowledgeSource
ItemDefinitions are DMNs way to express enumeration. In the definition of an ItemDefinition you declare which
values are allowed. Currently, we only validate if the expressions from an ItemDefintion is well-typed.
When we started to work on dmn-check we were not are of analysis tools for DMN files that suited our needs and worked in our Camunda flavored
environment. Since then DMN became more popular and other tools started provide some analysis capabilities as well. If you want to know how
dmn-check compares to other tools, you can read a comparision in GCD.
Ülari Laurson and Fabrizio Maria Maggi extended the dmn-js editing toolkit of Camunda with analysis capabilities and published it
at github.com/ulaurson/dmn-js. The tool is able to detect syntax and type errors and to identify
overlapping and missing rules. It also is able to simplify decision tables by merging rules. In the demo paper LM16 they describe
the tool. Further details about the analyses performed by the tool are published in CDL+16.
CDL+16 Calvanese, D., Dumas, M., Laurson, Ü., Maggi, F.M., Montali, M., Teinemaa, I.: Semantics and analysis of DMN decision tables. In Proceedings of the 14th International Conference on Business Process Management (BPM) 2016
LM16 Laurson, Ü. and Maggi, F.M., 2016, September. A Tool for the Analysis of DMN Decision Tables. In BPM (Demos) (pp. 56-60).
BW-a Batoulis, K. and Weske, M., A Tool for Checking Soundness of Decision-Aware Business Processes.
BW-b Batoulis, K. and Weske, M., Disambiguation of DMN Decision Tables.
FMTV18 Figl, K., Mendling, J., Tokdemir, G. and Vanthienen, J., 2018. What we know and what we do not know about DMN. Enterprise Modelling and Information Systems Architectures, 13, pp.2-1.
Silver16 Silver, B., 2016. Decision Table Analysis in DMN.
HDSV17 Hasic, F., De Smedt, J. and Vanthienen, J., 2017. Towards assessing the theoretical complexity of the decision model and notation (dmn). Enterprise, Business-Process and Information Systems Modeling. Springer International Publishing.
GCD Grohé, C., Corea, C. and Delfmann P, 2021. DMN 1.0 Verification Capabilities: An Analysis of Current Tool Support. Business Process Management Forum, BPM Forum 2021, Rome, Italy.
Valencia-Parra, A., Parody, L., Varela-Vaca, A., Caballero, I., and Gómez-López M., 2020. DMN4DQ: When data quality meets DMN. Journal 'Decision Support Systems'.