From de3ecb2b83fcb608df16279c54d05e0ec43ef614 Mon Sep 17 00:00:00 2001 From: birgitboss Date: Tue, 4 Aug 2026 13:36:03 +0200 Subject: [PATCH 1/9] Examples BNF: numbered and added text to decribe rule --- .../annex/text-access-rule-examples.adoc | 106 ++++++++++++++++-- 1 file changed, 94 insertions(+), 12 deletions(-) diff --git a/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc b/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc index e6e99ff..88a25ee 100644 --- a/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc +++ b/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc @@ -13,7 +13,10 @@ Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, d = Examples of Access Rules in text serialization [[example-anonymous-complete-api]] -== Allow READ access for Anonymous to complete API +== EXAMPLE 1: Allow READ access for Anonymous + +For public (ANONYMOUS): +Allow READ via complete API. [source,bnf,linenums] ---- @@ -21,14 +24,22 @@ include::partial$examples/allow-read-complete-api.bnf[] ---- [[example-anonymous-semanticids]] -== Allow READ access for Anonymous to list of semanticIDs for submodels +== EXAMPLE 2: Allow READ access for Anonymous to list of semanticIDs for submodels + +For public (ANONYMOUS): + +Allow READ access via complete API but restricted to Submodels with semanticId "SemanticID-Nameplate" or "SemanticID-TechnicalData". [source,bnf,linenums] ---- include::partial$examples/allow-read-list-semanticids.bnf[] ---- -== Allow EXECUTE of API operations only if machine not-running +== EXAMPLE 3: Allow EXECUTE of API operations only if machine not-running + +For public (ANONYMOUS): + +Allow EXECUTE of API operations only if machine is not running (value of SubmodelElement with idShort "machineState" not equal to "not-running"). [source,bnf,linenums] ---- @@ -36,14 +47,22 @@ include::partial$examples/allow-read-list-semanticids-machinestate.bnf[] ---- [[example-authenticated-users]] -== Allow READ and UPDATE for specific authenticated users +== EXAMPLE 4: Allow READ and UPDATE for specific authenticated users + +For users authenticated via "email", "email" shall be "user1@company1.com" or "user2@company2.com": + +Allow READ and UPDATE of Submodels with semanticId "SemanticID-Nameplate" or "SemanticID-TechnicalData". [source,bnf,linenums] ---- include::partial$examples/allow-read-update-users.bnf[] ---- -== Allow READ and UPDATE for specific submodel "submodel1" +== EXAMPLE 5: Allow READ and UPDATE for specific Submodel "submodel1" + +For users authenticated via "email", "email" shall be "user1@company1.com": + +Allow READ and UPDATE for specific Submodel with "id" "https://submodel1.company1.com". [source,bnf,linenums] ---- @@ -51,7 +70,11 @@ include::partial$examples/allow-read-update-submodel.bnf[] ---- [[example-reuse-acl-object-formula]] -== Reuse of ACL, OBJECT and FORMULA +== EXAMPLE 6: Reuse of ACL, OBJECT and FORMULA + +For users authenticated via "email", "email" element of "allowSubjectGroup1", i.e. "user1@company1.com" or "user2@company2.com": + +Allow READ and UPDATE for all Properties as defined in "Properties", i.e. for Submodel with id "https://s1.com" the SubmodelElements p1 and p2 with IdShort-Path "https://s1.com.p1" or "https://s1.com.p2" are allowed to be read and updated. [source,bnf,linenums] ---- @@ -59,14 +82,27 @@ include::partial$examples/reuse-acl-object-formula.bnf[] ---- [[example-business-partner-number]] -== Example with BusinessPartnerNumber +== EXAMPLE 7:Example for authenticated users with a specific BusinessPartnerNumber + +For users authenticated via "BusinessPartnerNumber", "BusinessPartnerNumber" shall be "BPN1234": + +Allow READ via complete API. + + +==== +Note: Business Partner Numbers are defined in link:https://catenax-ev.github.io/docs/next/standards/CX-0010-BusinessPartnerNumber[CX-0010 of Catena-X]. +==== [source,bnf,linenums] ---- include::partial$examples/bpn.bnf[] ---- -== Allow READ for all authenticated users of a company for submodels Nameplate and TechnicalData +== EXAMPLE 8: Example for authenticated users of a company + +For users authenticated via "email", "email" shall belong to domain "@company.com": + +Allow READ of Submodels with semanticId "SemanticID-Nameplate" or "SemanticID-TechnicalData". [source,bnf,linenums] ---- @@ -75,14 +111,25 @@ include::partial$examples/allow-read-all-users-of-company-for-submodel.bnf[] [[allow-read-submodels-id-pattern]] [[example-time-based-submodel-id-pattern]] -== Allow READ to all Submodels with ID pattern for all authenticated users of a company for submodels with Nameplate and TechnicalData on weekdays from 09:00:00Z-17:00:00Z +== EXAMPLE 9: Example with access constraints + + +For users authenticated via "companyName", "companyName" shall be "company1-name": + +Allow READ of Submodels with semanticId "SemanticID-Nameplate" or "SemanticID-TechnicalData" if the Submodel/id starts with "https://company1.com/" but only at working days (Monday to Friday) between 9:00 and 17:00 Utc. + + [source,bnf,linenums] ---- include::partial$examples/allow-read-submodels-id-pattern.bnf[] ---- -== Allow only to add elements to the CertificateSet in any Submodel +== EXAMPLE 10: Example with allowing creation within Submodel + +For users authenticated with role "person with legitimate interest": + +Allow CREATE of SubmodelElements within Submodels with semanticId "CertificateSet". [source,bnf,linenums] ---- @@ -90,7 +137,30 @@ include::partial$examples/allow-create-only-specific.bnf[] ---- [[example-filter-statement]] -== Example with FILTER statement +== EXAMPLE 11: Example with FILTER statement + +For users authenticated via "BusinessPartnerNumber", "BusinessPartnerNumber" shall be "BPNL00000000000A": + +Allow READ of AssetAdministrationShellDescriptors containing the following specificAssetIds: + +* there exists a specificAssetId with name "manufacturerPartId" and value "99991" and externalSubjectId "PUBLIC_READABLE" +* there additionally exists a specificAssetId with name "customerPartId" and value "ACME001" + +Not all specificAssetIds of the AssetAdministrationShellDescriptors fulfilling theses constraints are returned but only + +* the two specificAssetIds above used for selecting the AssetAdministrationShellDescriptors +* and additionally all those specificAssetIds that are public, i.e. with externalSubjectId equal to "PUBLIC_READABLE" +* and all specificAssetIds related to the autenticated user, i.e. those with externalSubjectId equal to the BusinessPartnerNumber" of the user +* and all specificAssetIds with name "partInstanceid" + + +==== +Note: the value "PUBLIC_READABLE" is not standardized in IDTA-01001. +==== + +==== +Note: This is a typical example for an access rule as defined in link:https://catenax-ev.github.io/docs/next/standards/CX-0127-IndustryCorePartInstance#214-digital-twins-and-specific-asset-ids[Catena-X]. +==== [source,bnf,linenums] ---- @@ -98,7 +168,19 @@ include::partial$examples/filter.bnf[] ---- [[example-reference-machine-state-filter]] -== Example with Reference Attribute and state-dependent filtering +== EXAMPLE 12: Example with Reference Attribute and state-dependent filtering + +For users authenticated with role "maintenance": + +Allow READ of maintenance documents within Submodel with id "SubmodelID-Maintenance" +(the SubmodelElement with idShort-path "SubmodelID-Maintenance.maintenanceDocuments") +but only if machine is running (value of SubmodelElement with idShort-Path "SubmodelID-OperationalData.machineState" not equal to "running" +within the Submodel with id "SubmodelID-OperationalData"). + +Not all maintenance documents are returned but only the maintenance document for the required machine state "running" (i.e. maintenanceDocuments[].requiredMachineState "running") + +In case the machine is not running all maintenance documents are returned (no FILTER defined). + [source,bnf,linenums] ---- From 2c5255affd4bad0c8f3395fa9eae89b778933a6d Mon Sep 17 00:00:00 2001 From: birgitboss Date: Tue, 4 Aug 2026 13:42:29 +0200 Subject: [PATCH 2/9] Align numbering of examples of json with BNF --- .../annex/json-access-rule-examples.adoc | 34 +++++++++++-------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/documentation/IDTA-01004/modules/ROOT/pages/annex/json-access-rule-examples.adoc b/documentation/IDTA-01004/modules/ROOT/pages/annex/json-access-rule-examples.adoc index 91d9ac8..4a145b2 100644 --- a/documentation/IDTA-01004/modules/ROOT/pages/annex/json-access-rule-examples.adoc +++ b/documentation/IDTA-01004/modules/ROOT/pages/annex/json-access-rule-examples.adoc @@ -12,86 +12,90 @@ Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, d = Examples of Access Rules in JSON serialization -== Allow READ access for Anonymous to complete API +For explanation of examples see xref:Annex/text-access-rule-examples.adoc[Examples in text BNF]. + +== EXAMPLE 1: Allow READ access for Anonymous [source,json,linenums] ---- include::partial$examples/allow-read-complete-api.json[] ---- -== Allow READ access for Anonymous to list of semanticIDs for submodels +== EXAMPLE 2: Allow READ access for Anonymous to list of semanticIDs for submodels [source,json,linenums] ---- include::partial$examples/allow-read-list-semanticids.json[] ---- -== Allow EXECUTE of API operations only if machine not-running +== EXAMPLE 3: Allow EXECUTE of API operations only if machine not-running [source,json,linenums] ---- include::partial$examples/allow-read-list-semanticids-machinestate.json[] ---- -== Allow READ and UPDATE for specific authenticated users +== EXAMPLE 4: Allow READ and UPDATE for specific authenticated users [source,json,linenums] ---- include::partial$examples/allow-read-update-users.json[] ---- -== Allow READ and UPDATE for specific submodel "submodel1" +== EXAMPLE 5: Allow READ and UPDATE for specific Submodel "submodel1" [source,json,linenums] ---- include::partial$examples/allow-read-update-submodel.json[] ---- -== Reuse of ACL, OBJECT and FORMULA +== EXAMPLE 6: Reuse of ACL, OBJECT and FORMULA [source,json,linenums] ---- include::partial$examples/reuse-acl-object-formula.json[] ---- -== Example with BusinessPartnerNumber +== EXAMPLE 7:Example for authenticated users with a specific BusinessPartnerNumber [source,json,linenums] ---- include::partial$examples/bpn.json[] ---- -== Allow READ for all authenticated users of a company for submodels Nameplate and TechnicalData +== EXAMPLE 8: Example for authenticated users of a company [source,json,linenums] ---- include::partial$examples/allow-read-all-users-of-company-for-submodel.json[] ---- -== Allow READ to all Submodels with ID pattern for all authenticated users of a company for submodels with Nameplate and TechnicalData on weekdays from 09:00:00Z-17:00:00Z +== EXAMPLE 9: Example with access constraints [source,json,linenums] ---- include::partial$examples/allow-read-submodels-id-pattern.json[] ---- -== Example with FILTER statement +== EXAMPLE 10: Example with allowing creation within Submodel [source,json,linenums] ---- -include::partial$examples/filter.json[] +include::partial$examples/allow-create-only-specific.json[] ---- -== Example with Reference Attribute and state-dependent filtering +== EXAMPLE 11: Example with FILTER statement [source,json,linenums] ---- -include::partial$examples/reference-machine-state-filter.json[] +include::partial$examples/filter.json[] ---- -== Allow only to add elements to the CertificateSet in any Submodel +== EXAMPLE 12: Example with Reference Attribute and state-dependent filtering [source,json,linenums] ---- -include::partial$examples/allow-create-only-specific.json[] +include::partial$examples/reference-machine-state-filter.json[] ---- + + From 9e415a1ccaa9dd6daa2d6a87e2e66cdba2620935 Mon Sep 17 00:00:00 2001 From: Martin Stemmer <52048213+Martin187187@users.noreply.github.com> Date: Tue, 18 Aug 2026 15:32:20 +0200 Subject: [PATCH 3/9] Fix link reference in JSON access rule examples --- .../modules/ROOT/pages/annex/json-access-rule-examples.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/IDTA-01004/modules/ROOT/pages/annex/json-access-rule-examples.adoc b/documentation/IDTA-01004/modules/ROOT/pages/annex/json-access-rule-examples.adoc index 4a145b2..cce5f37 100644 --- a/documentation/IDTA-01004/modules/ROOT/pages/annex/json-access-rule-examples.adoc +++ b/documentation/IDTA-01004/modules/ROOT/pages/annex/json-access-rule-examples.adoc @@ -12,7 +12,7 @@ Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, d = Examples of Access Rules in JSON serialization -For explanation of examples see xref:Annex/text-access-rule-examples.adoc[Examples in text BNF]. +For explanation of examples see xref:text-access-rule-examples.adoc[Examples in text BNF].. == EXAMPLE 1: Allow READ access for Anonymous From 4c9ee6223ef3ab3b2536a8b841aa8e7d22f157d0 Mon Sep 17 00:00:00 2001 From: Martin Stemmer <52048213+Martin187187@users.noreply.github.com> Date: Wed, 19 Aug 2026 08:45:42 +0200 Subject: [PATCH 4/9] fix link --- .../modules/ROOT/pages/annex/json-access-rule-examples.adoc | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/documentation/IDTA-01004/modules/ROOT/pages/annex/json-access-rule-examples.adoc b/documentation/IDTA-01004/modules/ROOT/pages/annex/json-access-rule-examples.adoc index cce5f37..ac6f1c9 100644 --- a/documentation/IDTA-01004/modules/ROOT/pages/annex/json-access-rule-examples.adoc +++ b/documentation/IDTA-01004/modules/ROOT/pages/annex/json-access-rule-examples.adoc @@ -12,7 +12,7 @@ Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, d = Examples of Access Rules in JSON serialization -For explanation of examples see xref:text-access-rule-examples.adoc[Examples in text BNF].. +For an explanation of the examples, see xref:annex/text-access-rule-examples.adoc[Examples in text BNF]. == EXAMPLE 1: Allow READ access for Anonymous @@ -98,4 +98,3 @@ include::partial$examples/filter.json[] include::partial$examples/reference-machine-state-filter.json[] ---- - From b19a29c603c8ee7a007cc378e3a429f87d22e046 Mon Sep 17 00:00:00 2001 From: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com> Date: Wed, 19 Aug 2026 09:46:37 +0200 Subject: [PATCH 5/9] Apply suggestions from code review Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com> --- .../modules/ROOT/pages/annex/text-access-rule-examples.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc b/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc index 88a25ee..5311a61 100644 --- a/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc +++ b/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc @@ -150,8 +150,8 @@ Not all specificAssetIds of the AssetAdministrationShellDescriptors fulfilling t * the two specificAssetIds above used for selecting the AssetAdministrationShellDescriptors * and additionally all those specificAssetIds that are public, i.e. with externalSubjectId equal to "PUBLIC_READABLE" -* and all specificAssetIds related to the autenticated user, i.e. those with externalSubjectId equal to the BusinessPartnerNumber" of the user -* and all specificAssetIds with name "partInstanceid" +* and all specificAssetIds related to the authenticated user, i.e. those with externalSubjectId equal to the BusinessPartnerNumber" of the user +* and all specificAssetIds with name "partInstanceId" ==== From c26ec3eb4414cbb3e1502638caec23cf78fcaa57 Mon Sep 17 00:00:00 2001 From: birgitboss Date: Wed, 19 Aug 2026 11:52:02 +0200 Subject: [PATCH 6/9] Fix example 10 for creation of CertificateSet within existing SM --- .../ROOT/pages/annex/text-access-rule-examples.adoc | 2 +- .../partials/examples/allow-create-only-specific.bnf | 8 +++++--- .../examples/allow-create-only-specific.json | 12 +++++++++++- 3 files changed, 17 insertions(+), 5 deletions(-) diff --git a/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc b/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc index 88a25ee..9794e58 100644 --- a/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc +++ b/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc @@ -129,7 +129,7 @@ include::partial$examples/allow-read-submodels-id-pattern.bnf[] For users authenticated with role "person with legitimate interest": -Allow CREATE of SubmodelElements within Submodels with semanticId "CertificateSet". +Allow CREATE of SubmodelElements with semanticId "CertificateSet" within Submodels with semanticId "semanticId-Circularity". [source,bnf,linenums] ---- diff --git a/documentation/IDTA-01004/modules/ROOT/partials/examples/allow-create-only-specific.bnf b/documentation/IDTA-01004/modules/ROOT/partials/examples/allow-create-only-specific.bnf index a837325..4fbae17 100644 --- a/documentation/IDTA-01004/modules/ROOT/partials/examples/allow-create-only-specific.bnf +++ b/documentation/IDTA-01004/modules/ROOT/partials/examples/allow-create-only-specific.bnf @@ -4,9 +4,11 @@ ACCESSRULE: RIGHTS: CREATE ACCESS: ALLOW OBJECTS: - IDENTIFIABLE $sm("*") + ROUTE /submodels/*/submodel-elements FORMULA: $and( CLAIM("Role") $eq "person with legitimate interest", - $sme#semanticId $eq "CertificateSet" - ) + $sme#semanticId $eq "CertificateSet", + $sm#semanticId $eq "semanticId-Circularity" + + ) \ No newline at end of file diff --git a/documentation/IDTA-01004/modules/ROOT/partials/examples/allow-create-only-specific.json b/documentation/IDTA-01004/modules/ROOT/partials/examples/allow-create-only-specific.json index 56889ce..b376bf0 100644 --- a/documentation/IDTA-01004/modules/ROOT/partials/examples/allow-create-only-specific.json +++ b/documentation/IDTA-01004/modules/ROOT/partials/examples/allow-create-only-specific.json @@ -15,7 +15,7 @@ }, "OBJECTS": [ { - "IDENTIFIABLE": "$sm(\"*\")" + "ROUTE": "/submodels/*/submodel-elements" } ], "FORMULA": { @@ -42,6 +42,16 @@ } ] } + { + "$eq": [ + { + "$field": "$sm#semanticId" + }, + { + "$strVal": "semanticId-Ciruclarity" + } + ] + } ] } } From 4e6c13b1889922f1267c0a63dc6c3733d3202363 Mon Sep 17 00:00:00 2001 From: birgitboss Date: Wed, 19 Aug 2026 11:58:39 +0200 Subject: [PATCH 7/9] example 10: add note that DPP relevant --- .../modules/ROOT/pages/annex/text-access-rule-examples.adoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc b/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc index 2449b5f..14ad40a 100644 --- a/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc +++ b/documentation/IDTA-01004/modules/ROOT/pages/annex/text-access-rule-examples.adoc @@ -131,6 +131,10 @@ For users authenticated with role "person with legitimate interest": Allow CREATE of SubmodelElements with semanticId "CertificateSet" within Submodels with semanticId "semanticId-Circularity". +==== +Note: This is a typical example for an access rule for digital product passport related updates by recyclers. +==== + [source,bnf,linenums] ---- include::partial$examples/allow-create-only-specific.bnf[] From 3f27c63f23c44b60054916cfa12cac65abfeae8a Mon Sep 17 00:00:00 2001 From: birgitboss Date: Wed, 19 Aug 2026 12:01:56 +0200 Subject: [PATCH 8/9] update changelog --- documentation/IDTA-01004/modules/ROOT/pages/changelog.adoc | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/documentation/IDTA-01004/modules/ROOT/pages/changelog.adoc b/documentation/IDTA-01004/modules/ROOT/pages/changelog.adoc index 3a916af..243eb41 100644 --- a/documentation/IDTA-01004/modules/ROOT/pages/changelog.adoc +++ b/documentation/IDTA-01004/modules/ROOT/pages/changelog.adoc @@ -11,6 +11,13 @@ SPDX-License-Identifier: CC-BY-4.0 [[change-notes]] = Change Notes +== Changes w.r.t. V3.2 vs. V3.1 + +Minor Changes: + +* Improved documentation of access rule examples +* new access rule examples for DPP related rules, access rule 10 updated to better reflect the purpose + == Changes w.r.t. V3.1 vs. V3.0.2 Major Changes: From 5129fa5ebb06e32ada03bb99d6e4dcdb708d3532 Mon Sep 17 00:00:00 2001 From: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com> Date: Mon, 24 Aug 2026 09:33:08 +0200 Subject: [PATCH 9/9] Apply suggestions from code review Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com> --- .../ROOT/partials/examples/allow-create-only-specific.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/IDTA-01004/modules/ROOT/partials/examples/allow-create-only-specific.json b/documentation/IDTA-01004/modules/ROOT/partials/examples/allow-create-only-specific.json index b376bf0..ef16b2b 100644 --- a/documentation/IDTA-01004/modules/ROOT/partials/examples/allow-create-only-specific.json +++ b/documentation/IDTA-01004/modules/ROOT/partials/examples/allow-create-only-specific.json @@ -41,14 +41,14 @@ "$strVal": "CertificateSet" } ] - } + }, { "$eq": [ { "$field": "$sm#semanticId" }, { - "$strVal": "semanticId-Ciruclarity" + "$strVal": "semanticId-Circularity" } ] }