From 7638233602211fef65e0f03feabde743c446d9b3 Mon Sep 17 00:00:00 2001 From: birgitboss Date: Tue, 18 Aug 2026 15:33:30 +0200 Subject: [PATCH 1/4] Add Example 13 for DPP access --- .../annex/text-access-rule-examples.adoc | 127 ++++++++++++++++-- .../examples/dpp-allow-datapoints.bnf | 50 +++++++ 2 files changed, 165 insertions(+), 12 deletions(-) create mode 100644 documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf 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..59ceccd 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,9 +168,42 @@ 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] ---- include::partial$examples/reference-machine-state-filter.bnf[] ---- + + +[[example-dpp]] +== EXAMPLE 13: Example for access of DPP data points + +Delegated acts for digital product passport distinguish between different access roles. +For the Battery Passport there are for example "public", "persons with legitimite interest", "Notified bodies, market surveillance authorities and the Commission" or "persons with a legitimate interest and the Commission" (see BatteryPassport-ready DataAttribute Longlist V1.3). + +"public" has the same semantics as "ANONYMOUS" in AAS. +The "battery category" or "battery mass" for example are allowed to be accessed by the public. + +In contrast "DateOfPuttingIntoService" is not made available to the public but only to persons with legitimite interest. +Of course a person with legitimate interest can also access public data. + +The example proposes to add access rules per Submodel because it cannot be guaranteed that the idShort of properties are unique across different Submodels. + +[source,bnf,linenums] +---- +include::partial$examples/dpp-allow-datapoints.bnf[] +---- + diff --git a/documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf b/documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf new file mode 100644 index 0000000..7dfca3d --- /dev/null +++ b/documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf @@ -0,0 +1,50 @@ + +DEFOBJECTS "BatteryPassport-TechnicalData-Public-DataPoints" + REFERABLE $sme(*).BatteryCategory + REFERABLE $sme(*).BatteryMass + ... + +DEFOBJECTS "BatteryPassport-TechnicalData-LegitimiteInterest-DataPoints" + USEOBJECTS "BatteryPassport-TechnicalData-Public-DataPoints" + ... + +DEFOBJECTS "BatteryPassport-Nameplate-LegitimiteInterest-DataPoints-Update" + ... + +DEFOBJECTS "BatteryPassport-Nameplate-LegitimiteInterest-DataPoints" + USEOBJECTS "BatteryPassport-Nameplate-Public-DataPoints" + USEOBJECTS "BatteryPassport-Nameplate-LegitimiteInterest-DataPoints-Update" + REFERABLE $sme(*).DateOfPuttingIntoService + ... + +ACCESSRULE: + ATTRIBUTES: + GLOBAL(ANONYMOUS) + RIGHTS: READ + ACCESS: ALLOW + OBJECTS: + USEOBJECTS "BatteryPassport-TechnicalData-Public-DataPoints" + FORMULA: + $sm#semanticId $eq "semanticId-BatteryTechnicalData" + +ACCESSRULE: + ATTRIBUTES: + CLAIM("PersonsWithLegitimiteInterest") + RIGHTS: READ + ACCESS: ALLOW + OBJECTS: + USEOBJECTS "BatteryPassport-Nameplate-LegitimiteInterest-DataPoints" + FORMULA: + $sm#semanticId $eq "semanticId-BatteryNameplate" + + +ACCESSRULE: + ATTRIBUTES: + CLAIM("PersonsWithLegitimiteInterest") + RIGHTS: READ UPDATE + ACCESS: ALLOW + OBJECTS: + USEOBJECTS "BatteryPassport-Nameplate-LegitimiteInterest-DataPoints-Update" + FORMULA: + $sm#semanticId $eq "semanticId-BatteryNameplate" + From 09a21dd31fdb2cd32e26e1d5ecadc3462258aba4 Mon Sep 17 00:00:00 2001 From: birgitboss Date: Wed, 19 Aug 2026 09:53:39 +0200 Subject: [PATCH 2/4] DPP example access rule: use claim Role instead of claim person with legitimate interest --- .../partials/examples/dpp-allow-datapoints.bnf | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf b/documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf index 7dfca3d..41be815 100644 --- a/documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf +++ b/documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf @@ -29,22 +29,29 @@ ACCESSRULE: ACCESSRULE: ATTRIBUTES: - CLAIM("PersonsWithLegitimiteInterest") + CLAIM("Role") RIGHTS: READ ACCESS: ALLOW OBJECTS: USEOBJECTS "BatteryPassport-Nameplate-LegitimiteInterest-DataPoints" FORMULA: - $sm#semanticId $eq "semanticId-BatteryNameplate" - + $and( + CLAIM("Role") $eq "person with legitimate interest", + $sm#semanticId $eq "semanticId-BatteryNameplate" + ) ACCESSRULE: ATTRIBUTES: - CLAIM("PersonsWithLegitimiteInterest") + CLAIM("Role") RIGHTS: READ UPDATE ACCESS: ALLOW OBJECTS: USEOBJECTS "BatteryPassport-Nameplate-LegitimiteInterest-DataPoints-Update" FORMULA: - $sm#semanticId $eq "semanticId-BatteryNameplate" + $and( + CLAIM("Role") $eq "person with legitimate interest", + $sm#semanticId $eq "semanticId-BatteryNameplate" + ) + + From f667d7d24f7d3b95b865017ffbea5e7e5dec1efa Mon Sep 17 00:00:00 2001 From: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com> Date: Tue, 25 Aug 2026 14:05:45 +0200 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: Martin Stemmer <52048213+Martin187187@users.noreply.github.com> Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com> --- .../pages/annex/text-access-rule-examples.adoc | 14 +++++++------- .../partials/examples/dpp-allow-datapoints.bnf | 10 +++++----- 2 files changed, 12 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 59ceccd..af03f08 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 @@ -39,7 +39,7 @@ include::partial$examples/allow-read-list-semanticids.bnf[] 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"). +Allow EXECUTE of API operations only if machine is not running (value of SubmodelElement with idShort "machineState" equal to "not-running"). [source,bnf,linenums] ---- @@ -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" ==== @@ -174,8 +174,8 @@ 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"). +but only if machine is running (value of SubmodelElement with idShort-Path "SubmodelID-OperationalData.machineState" 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") @@ -192,12 +192,12 @@ include::partial$examples/reference-machine-state-filter.bnf[] == EXAMPLE 13: Example for access of DPP data points Delegated acts for digital product passport distinguish between different access roles. -For the Battery Passport there are for example "public", "persons with legitimite interest", "Notified bodies, market surveillance authorities and the Commission" or "persons with a legitimate interest and the Commission" (see BatteryPassport-ready DataAttribute Longlist V1.3). +For the Battery Passport there are for example "public", "persons with legitimate interest", "Notified bodies, market surveillance authorities and the Commission" or "persons with a legitimate interest and the Commission" (see BatteryPassport-ready DataAttribute Longlist V1.3). "public" has the same semantics as "ANONYMOUS" in AAS. The "battery category" or "battery mass" for example are allowed to be accessed by the public. -In contrast "DateOfPuttingIntoService" is not made available to the public but only to persons with legitimite interest. +In contrast "DateOfPuttingIntoService" is not made available to the public but only to persons with legitimate interest. Of course a person with legitimate interest can also access public data. The example proposes to add access rules per Submodel because it cannot be guaranteed that the idShort of properties are unique across different Submodels. diff --git a/documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf b/documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf index 41be815..18a09de 100644 --- a/documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf +++ b/documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf @@ -1,10 +1,10 @@ DEFOBJECTS "BatteryPassport-TechnicalData-Public-DataPoints" REFERABLE $sme(*).BatteryCategory - REFERABLE $sme(*).BatteryMass + REFERABLE $sme("*").BatteryMass ... -DEFOBJECTS "BatteryPassport-TechnicalData-LegitimiteInterest-DataPoints" +DEFOBJECTS "BatteryPassport-TechnicalData-LegitimateInterest-DataPoints" USEOBJECTS "BatteryPassport-TechnicalData-Public-DataPoints" ... @@ -14,7 +14,7 @@ DEFOBJECTS "BatteryPassport-Nameplate-LegitimiteInterest-DataPoints-Update" DEFOBJECTS "BatteryPassport-Nameplate-LegitimiteInterest-DataPoints" USEOBJECTS "BatteryPassport-Nameplate-Public-DataPoints" USEOBJECTS "BatteryPassport-Nameplate-LegitimiteInterest-DataPoints-Update" - REFERABLE $sme(*).DateOfPuttingIntoService + REFERABLE $sme("*").DateOfPuttingIntoService ... ACCESSRULE: @@ -33,7 +33,7 @@ ACCESSRULE: RIGHTS: READ ACCESS: ALLOW OBJECTS: - USEOBJECTS "BatteryPassport-Nameplate-LegitimiteInterest-DataPoints" + USEOBJECTS "BatteryPassport-Nameplate-LegitimateInterest-DataPoints" FORMULA: $and( CLAIM("Role") $eq "person with legitimate interest", @@ -46,7 +46,7 @@ ACCESSRULE: RIGHTS: READ UPDATE ACCESS: ALLOW OBJECTS: - USEOBJECTS "BatteryPassport-Nameplate-LegitimiteInterest-DataPoints-Update" + USEOBJECTS "BatteryPassport-Nameplate-LegitimateInterest-DataPoints-Update" FORMULA: $and( CLAIM("Role") $eq "person with legitimate interest", From 33509049371bd0c912371e87ff7bfb9ee9147f8d Mon Sep 17 00:00:00 2001 From: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com> Date: Tue, 25 Aug 2026 14:09:33 +0200 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Birgit Boss <59824205+BirgitBoss@users.noreply.github.com> --- .../modules/ROOT/partials/examples/dpp-allow-datapoints.bnf | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf b/documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf index 18a09de..f0a13da 100644 --- a/documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf +++ b/documentation/IDTA-01004/modules/ROOT/partials/examples/dpp-allow-datapoints.bnf @@ -8,10 +8,10 @@ DEFOBJECTS "BatteryPassport-TechnicalData-LegitimateInterest-DataPoints" USEOBJECTS "BatteryPassport-TechnicalData-Public-DataPoints" ... -DEFOBJECTS "BatteryPassport-Nameplate-LegitimiteInterest-DataPoints-Update" +DEFOBJECTS "BatteryPassport-Nameplate-LegitimateInterest-DataPoints-Update" ... -DEFOBJECTS "BatteryPassport-Nameplate-LegitimiteInterest-DataPoints" +DEFOBJECTS "BatteryPassport-Nameplate-LegitimateInterest-DataPoints" USEOBJECTS "BatteryPassport-Nameplate-Public-DataPoints" USEOBJECTS "BatteryPassport-Nameplate-LegitimiteInterest-DataPoints-Update" REFERABLE $sme("*").DateOfPuttingIntoService