From e489782487cb7036028b8f12c92ccf5894c45708 Mon Sep 17 00:00:00 2001 From: Falko Menge Date: Wed, 13 Dec 2023 18:13:36 +0100 Subject: [PATCH 1/9] Add design considerations and example --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++-- example.bpmn | 24 ++++++++++++++++++++++++ 2 files changed, 68 insertions(+), 2 deletions(-) create mode 100644 example.bpmn diff --git a/README.md b/README.md index 46cd361..0d49fe9 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,44 @@ -# bpmn-icon -BPMN 2.0 Extension for interchanging Custom Icons +# BPMN 2.0 Extension for Custom Icons + +This specification defines a BPMN 2.0 Extension for interchanging custom icons. + +## Design considerations + +The placement of the icons in the rendered diagram is not specified in this extension +and is deliberately left for to tool vendors to decide. + +The icon is stored using the +[Data URI Scheme (RFC2397)](https://en.wikipedia.org/wiki/Data_URI_scheme) +because that is widely supported by many tools, +e.g. by SVG which is used by many tools for rendering BPMN. + +SVG icons with no fill are prefered. For pixel graphics prefer transparent PNGs. + +Since icons are relatively large, especially when not using vector graphics, +they should be reusable and placed in a central place in the XML serialization. + +The extension should allow attaching custom icons to any BPMN element, +i.e. icons cannot be embedded in elements like `bpmn:Interface` +because only some of the BPMN elements use that element. + +Unfortunately, neither the top-level `bpmn:definitions` not the `bpmndi:BPMNDiagram` +containers permit `extensionElements`. +Therefore, this extension uses a top-level `bpmn:relationship` as a container, e.g. + +```xml + + + + + Definitions + Definitions + +``` + +The relationship's `source` and `target` MUST point to the `id` of the `bpmn:definitions` root element. + +Icons are referenced from `BPMNDiagramElements` using `icon:iconRef`: + +```xml + +``` \ No newline at end of file diff --git a/example.bpmn b/example.bpmn new file mode 100644 index 0000000..80504a0 --- /dev/null +++ b/example.bpmn @@ -0,0 +1,24 @@ + + + + + + + + + + + + + + + + + Definitions + Definitions + + From 7085e199921cb93ca7dad187dd007672abe29b66 Mon Sep 17 00:00:00 2001 From: Falko Menge Date: Wed, 13 Dec 2023 18:25:33 +0100 Subject: [PATCH 2/9] Add XML schema validation --- .github/workflows/main.yml | 25 + BPMN/BPMN20.xsd | 37 + BPMN/BPMNDI.xsd | 100 +++ BPMN/DC.xsd | 29 + BPMN/DI.xsd | 100 +++ BPMN/Semantic.xsd | 1562 ++++++++++++++++++++++++++++++++++++ 6 files changed, 1853 insertions(+) create mode 100644 .github/workflows/main.yml create mode 100755 BPMN/BPMN20.xsd create mode 100755 BPMN/BPMNDI.xsd create mode 100755 BPMN/DC.xsd create mode 100755 BPMN/DI.xsd create mode 100755 BPMN/Semantic.xsd diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml new file mode 100644 index 0000000..c95fa29 --- /dev/null +++ b/.github/workflows/main.yml @@ -0,0 +1,25 @@ +name: CI + +on: + # Triggers the workflow on push or pull request events but only for the master branch + push: + branches: [ main ] + pull_request: + branches: [ main ] + + # Allows to run this workflow manually from the Actions tab + workflow_dispatch: + +jobs: + xmllint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Enable annotations for XML validation errors and warnings + uses: korelstar/xmllint-problem-matcher@v1 + - name: Validate example.bpmn using BPMN20.xsd + id: xmllint + uses: ChristophWurst/xmllint-action@v1.2 + with: + xml-file: example.bpmn + xml-schema-file: BPMN/BPMN20.xsd \ No newline at end of file diff --git a/BPMN/BPMN20.xsd b/BPMN/BPMN20.xsd new file mode 100755 index 0000000..463ef6e --- /dev/null +++ b/BPMN/BPMN20.xsd @@ -0,0 +1,37 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/BPMN/BPMNDI.xsd b/BPMN/BPMNDI.xsd new file mode 100755 index 0000000..615740f --- /dev/null +++ b/BPMN/BPMNDI.xsd @@ -0,0 +1,100 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/BPMN/DC.xsd b/BPMN/DC.xsd new file mode 100755 index 0000000..80e9fa8 --- /dev/null +++ b/BPMN/DC.xsd @@ -0,0 +1,29 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/BPMN/DI.xsd b/BPMN/DI.xsd new file mode 100755 index 0000000..4023d28 --- /dev/null +++ b/BPMN/DI.xsd @@ -0,0 +1,100 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/BPMN/Semantic.xsd b/BPMN/Semantic.xsd new file mode 100755 index 0000000..1c611da --- /dev/null +++ b/BPMN/Semantic.xsd @@ -0,0 +1,1562 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 79ea1a7874475185a0a664c2708358acf592231b Mon Sep 17 00:00:00 2001 From: Falko Menge Date: Wed, 13 Dec 2023 18:31:24 +0100 Subject: [PATCH 3/9] Add BPMN reference --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 0d49fe9..c0f5b5f 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,7 @@ Therefore, this extension uses a top-level `bpmn:relationship` as a container, e ``` The relationship's `source` and `target` MUST point to the `id` of the `bpmn:definitions` root element. +Note that the [relationship XML example in the BPMN specification text](https://www.omg.org/spec/BPMN/2.0/PDF?page=93) is not schema-valid. Icons are referenced from `BPMNDiagramElements` using `icon:iconRef`: From 09d1edaf9a355159dd426f3e17890c3d242bc8ad Mon Sep 17 00:00:00 2001 From: Falko Menge Date: Wed, 10 Jan 2024 17:20:02 +0100 Subject: [PATCH 4/9] Add XML schema --- bpmn-icon.xsd | 24 ++++++++++++++++++++++++ example.bpmn | 7 ++++++- 2 files changed, 30 insertions(+), 1 deletion(-) create mode 100644 bpmn-icon.xsd diff --git a/bpmn-icon.xsd b/bpmn-icon.xsd new file mode 100644 index 0000000..03614f7 --- /dev/null +++ b/bpmn-icon.xsd @@ -0,0 +1,24 @@ + + + + + + + + + + + + + + This attribute points to the id of the iconDefinition. + + + + + + diff --git a/example.bpmn b/example.bpmn index 80504a0..588e294 100644 --- a/example.bpmn +++ b/example.bpmn @@ -3,7 +3,12 @@ xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:icon="http://www.omg.org/spec/BPMN/non-normative/Icon" - id="Definitions" targetNamespace="http://example.org"> + id="Definitions" targetNamespace="http://example.org" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation=" + http://www.omg.org/spec/BPMN/non-normative/Icon + ./bpmn-icon.xsd + "> From 492a626b055e547e59b0df13b3eafd89ecb8c24f Mon Sep 17 00:00:00 2001 From: Falko Menge Date: Wed, 10 Jan 2024 20:34:31 +0100 Subject: [PATCH 5/9] Remove attribute group and add documentation --- bpmn-icon.xsd | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/bpmn-icon.xsd b/bpmn-icon.xsd index 03614f7..d0bdaa2 100644 --- a/bpmn-icon.xsd +++ b/bpmn-icon.xsd @@ -4,21 +4,26 @@ xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> - + + + + This element is meant to be placed inside + the bpmn:extensionElements of a bpmn:relation. + + + - - - - - This attribute points to the id of the iconDefinition. - - - - + + + + This attribute points to the id of the iconDefinition. + + + From af14a7802d243786108a1c141abcf34bd4a7d5d2 Mon Sep 17 00:00:00 2001 From: Falko Menge Date: Thu, 11 Jan 2024 00:35:13 +0100 Subject: [PATCH 6/9] Redefine BPMN & BPMNDI schemas to know icons --- .vscode/settings.json | 13 +++++++++++++ BPMN20-with-Icon.xsd | 22 ++++++++++++++++++++++ BPMNDI-with-iconRef.xsd | 22 ++++++++++++++++++++++ bpmn-icon.xsd | 2 +- example.bpmn | 21 ++++++++++++++------- 5 files changed, 72 insertions(+), 8 deletions(-) create mode 100644 .vscode/settings.json create mode 100644 BPMN20-with-Icon.xsd create mode 100644 BPMNDI-with-iconRef.xsd diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..c10c081 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,13 @@ +{ + "xml.references": [ + { + "pattern": "**/*.bpmn", + "expressions": [ + { + "from": "BPMNShape/@iconRef", + "to": "iconDefinition/@id" + } + ] + } + ] +} \ No newline at end of file diff --git a/BPMN20-with-Icon.xsd b/BPMN20-with-Icon.xsd new file mode 100644 index 0000000..28d8b02 --- /dev/null +++ b/BPMN20-with-Icon.xsd @@ -0,0 +1,22 @@ + + + + + + + + + + + diff --git a/BPMNDI-with-iconRef.xsd b/BPMNDI-with-iconRef.xsd new file mode 100644 index 0000000..5c5c49d --- /dev/null +++ b/BPMNDI-with-iconRef.xsd @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + + diff --git a/bpmn-icon.xsd b/bpmn-icon.xsd index d0bdaa2..538d8f4 100644 --- a/bpmn-icon.xsd +++ b/bpmn-icon.xsd @@ -8,7 +8,7 @@ This element is meant to be placed inside - the bpmn:extensionElements of a bpmn:relation. + the bpmn:extensionElements of a bpmn:relationship. diff --git a/example.bpmn b/example.bpmn index 588e294..6b80009 100644 --- a/example.bpmn +++ b/example.bpmn @@ -1,29 +1,36 @@ - - + - + - + - Definitions - Definitions + IconExample + IconExample From d4ed2755df0c7bb3b0fae677a8d61d4b7a4ca531 Mon Sep 17 00:00:00 2001 From: Falko Menge Date: Wed, 3 Jul 2024 18:35:00 +0200 Subject: [PATCH 7/9] Improve documentation --- README.md | 9 ++++++--- bpmn-icon.xsd | 15 +++++++++++++-- 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c0f5b5f..a7be282 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,9 @@ -# BPMN 2.0 Extension for Custom Icons +# BPMN Icon Extension (bpmn-icon) -This specification defines a BPMN 2.0 Extension for interchanging custom icons. +This specification defines an extension of BPMN 2.0 for interchanging custom icons. +It uses the [extension mechanism of BPMN](https://www.omg.org/spec/BPMN/2.0.2/PDF#page=72) +to transport additional markers, which are explicitly permitted in +[section 2.2.3 Visual Appearance](https://www.omg.org/spec/BPMN/2.0.2/PDF#page=38). ## Design considerations @@ -36,7 +39,7 @@ Therefore, this extension uses a top-level `bpmn:relationship` as a container, e ``` The relationship's `source` and `target` MUST point to the `id` of the `bpmn:definitions` root element. -Note that the [relationship XML example in the BPMN specification text](https://www.omg.org/spec/BPMN/2.0/PDF?page=93) is not schema-valid. +Note that the [relationship XML example in the BPMN specification text](https://www.omg.org/spec/BPMN/2.0/PDF#page=93) is not schema-valid. Icons are referenced from `BPMNDiagramElements` using `icon:iconRef`: diff --git a/bpmn-icon.xsd b/bpmn-icon.xsd index 538d8f4..0f317c6 100644 --- a/bpmn-icon.xsd +++ b/bpmn-icon.xsd @@ -4,10 +4,18 @@ xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified"> + + + This XML schema defines and documents an extension of BPMN 2.0 + for interchanging custom icons. + + + - This element is meant to be placed inside + This element defines a custom icon + and is meant to be placed inside the bpmn:extensionElements of a bpmn:relationship. @@ -21,7 +29,10 @@ - This attribute points to the id of the iconDefinition. + This attribute points to the id of the iconDefinition + and is meant to be placed inside the bpmndi:BPMNShape element. + It is of type xs:QName to allow for referencing iconDefinitions + that are imported from another BPMN file using bpmn:import. From 6c610bc715d9f8b648ae1e263ceaa693f26da361 Mon Sep 17 00:00:00 2001 From: Falko Menge Date: Wed, 4 Sep 2024 17:31:51 +0200 Subject: [PATCH 8/9] Adjust namespaces per OMG policy --- README.md | 17 ++++++++++------- bpmn-icon.xsd | 6 ++++-- example.bpmn | 37 ++++++++++++++----------------------- 3 files changed, 28 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index a7be282..06e89a9 100644 --- a/README.md +++ b/README.md @@ -29,13 +29,16 @@ containers permit `extensionElements`. Therefore, this extension uses a top-level `bpmn:relationship` as a container, e.g. ```xml - - - - - Definitions - Definitions - + + ... + + + + + IconExample + IconExample + + ``` The relationship's `source` and `target` MUST point to the `id` of the `bpmn:definitions` root element. diff --git a/bpmn-icon.xsd b/bpmn-icon.xsd index 0f317c6..2325698 100644 --- a/bpmn-icon.xsd +++ b/bpmn-icon.xsd @@ -1,6 +1,8 @@ diff --git a/example.bpmn b/example.bpmn index 6b80009..010dc14 100644 --- a/example.bpmn +++ b/example.bpmn @@ -1,24 +1,15 @@ - - - - + xmlns:icon="https://www.omg.org/spec/BPMN/non-normative/Icon" + > + + + @@ -26,11 +17,11 @@ - - + + - - IconExample - IconExample - - + + IconExample + IconExample + + From 686c762f336f70d0aa5949a9c71c26258ce6372e Mon Sep 17 00:00:00 2001 From: Falko Menge Date: Thu, 12 Dec 2024 09:18:26 +0000 Subject: [PATCH 9/9] Relax version number of xmllint-action --- .github/workflows/main.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index c95fa29..87d6693 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -19,7 +19,7 @@ jobs: uses: korelstar/xmllint-problem-matcher@v1 - name: Validate example.bpmn using BPMN20.xsd id: xmllint - uses: ChristophWurst/xmllint-action@v1.2 + uses: ChristophWurst/xmllint-action@v1 with: xml-file: example.bpmn xml-schema-file: BPMN/BPMN20.xsd \ No newline at end of file