From 19e00450514d81a614588fb6a11f3a72c0bc0d68 Mon Sep 17 00:00:00 2001 From: arnoweiss Date: Mon, 25 Mar 2024 17:09:24 +0100 Subject: [PATCH 01/15] docs(conn): add general section on policies --- .../Adoption View/working-with-policies.md | 290 ++++++++++++++++++ sidebarsDocsKits.js | 15 +- 2 files changed, 304 insertions(+), 1 deletion(-) create mode 100644 docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md diff --git a/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md new file mode 100644 index 00000000000..a96c84a804b --- /dev/null +++ b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md @@ -0,0 +1,290 @@ +--- +sidebar_position: 2 +description: 'Guidance on best practices' +title: Working with Policies +id: connector_kit_adoption_view_policies +--- + +## Working with Policies + +Policies are a formalization of the terms under which a Provider extends an offer to the Dataspace. The format is given +by the Dataspace Protocol Specification: The [Open Digital Rights Language (ODRL)](https://www.w3.org/TR/odrl-model/). + +Like all payloads that get exchanged between connectors, ODRL is an RDF-based description language that is on exchange +serialized as JSON-LD. JSON-LD is namespace-aware JSON with a couple of twists that one should be aware of when working +with it (like "Structures may be semantically equivalent even though, schematically, they are clearly not"). ODRL +enables a Provider to be very specific when it comes to the usage of data: What may a consumer do with it? What +obligations does a consumer incur when accepting the offer? + +The first time the Consumer encounters a Policy is when evaluating a Provider's [Catalog](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol/catalog/catalog.protocol), as displayed below. +This specific Catalog contains one single `dcat:Dataset`, called "json-1-paper". It is the only entry in the top-level +`dcat:dataset` property. To access this Dataset, the Consumer can choose between four Offers (see the `odrl:hasPolicy` +property): + +- "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtNA==:anNvbi0xLXBhcGVy:Y2JhMGFmM2QtZTIwYi00ZjExLThlZmQtM2FhMzcyZmI1Nzhh" +- "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMg==:anNvbi0xLXBhcGVy:ZDA4ZDM5OTgtOGY5ZS00MzBmLThjZDEtZmYwOWQxMmQxYzk5" +- "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMw==:anNvbi0xLXBhcGVy:NDQ1ZWRlZDMtNjNlMy00ZDg0LTkxMmUtYWFjZWM0MjdkMDQ4" +- "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMQ==:anNvbi0xLXBhcGVy:ODFkMDI2MWYtNDNlNi00ZTIxLWJkMWYtZmFmZTI3MWQwYzhj" + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "tx": "https://w3id.org/tractusx/v0.0.1/ns/", + "dcat": "http://www.w3.org/ns/dcat#", + "dct": "https://purl.org/dc/terms/", + "odrl": "http://www.w3.org/ns/odrl/2/", + "dspace": "https://w3id.org/dspace/v0.8/" + }, + "@id": "693e9b66-04f2-4bfb-b3cd-daf5857b47c9", + "@type": "dcat:Catalog", + "dcat:dataset": [ + { + "@id": "json-1-paper", + "@type": "dcat:Dataset", + "odrl:hasPolicy": [ + { + "@id": "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtNA==:anNvbi0xLXBhcGVy:Y2JhMGFmM2QtZTIwYi00ZjExLThlZmQtM2FhMzcyZmI1Nzhh", + "@type": "odrl:Set", + "odrl:permission": { + "odrl:action": { + "odrl:type": "http://www.w3.org/ns/odrl/2/use" + }, + "odrl:constraint": { + "odrl:and": [ + { + "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/FrameworkAgreement", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "traceability:v1.0" + }, + { + "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/ContractReference", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "contract-123456789" + }, + { + "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/UsagePurpose", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "ID 3.1 Trace" + }, + { + "odrl:leftOperand": "https://w3id.org/edc/v0.0.1/ns/AgreetoWhatever", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "Yes" + } + ] + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + }, + { + "@id": "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMg==:anNvbi0xLXBhcGVy:ZDA4ZDM5OTgtOGY5ZS00MzBmLThjZDEtZmYwOWQxMmQxYzk5", + "@type": "odrl:Set", + "odrl:permission": { + "odrl:action": { + "odrl:type": "http://www.w3.org/ns/odrl/2/use" + }, + "odrl:constraint": { + "odrl:and": [ + { + "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/FrameworkAgreement", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "traceability:v1.0" + }, + { + "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/UsagePurpose", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "ID 3.1 Trace" + } + ] + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + }, + { + "@id": "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMw==:anNvbi0xLXBhcGVy:NDQ1ZWRlZDMtNjNlMy00ZDg0LTkxMmUtYWFjZWM0MjdkMDQ4", + "@type": "odrl:Set", + "odrl:permission": { + "odrl:action": { + "odrl:type": "http://www.w3.org/ns/odrl/2/use" + }, + "odrl:constraint": { + "odrl:and": { + "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/FrameworkAgreement", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "traceability:v1.0" + } + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + }, + { + "@id": "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMQ==:anNvbi0xLXBhcGVy:ODFkMDI2MWYtNDNlNi00ZTIxLWJkMWYtZmFmZTI3MWQwYzhj", + "@type": "odrl:Set", + "odrl:permission": { + "odrl:action": { + "odrl:type": "http://www.w3.org/ns/odrl/2/use" + }, + "odrl:constraint": { + "odrl:and": [ + { + "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/FrameworkAgreement", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "traceability:v1.0" + }, + { + "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/ContractReference", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "contract-123456789" + }, + { + "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/UsagePurpose", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "ID 3.1 Trace" + } + ] + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + } + ], + "dcat:distribution": [ + { + "@type": "dcat:Distribution", + "dct:format": { + "@id": "HttpData-PULL" + }, + "dcat:accessService": "911f5da0-c9ee-4259-9a95-39428d08f767" + } + ], + "version": 1.0, + "content-type": "application/json", + "name": "json-1-paper", + "description": "Asset json-1-paper for test purposes", + "id": "json-1-paper" + } + ], + "dcat:service": { + "@id": "911f5da0-c9ee-4259-9a95-39428d08f767", + "@type": "dcat:DataService", + "dct:terms": "connector", + "dct:endpointUrl": "https://provider-dsp-end.point/api/v1/dsp" + }, + "participantId": "PROVIDER-BPNL" +} + +``` + +These four Offers are of `@type` either `odrl:Offer` or one of its subclasses. More interesting however are the +`odrl:permission`, `odrl:prohibition` and `odrl:obligation` properties. They contain `odrl:Rules` that have to be +satisfied by the Consumer. There's two ways that can happen. + +### Consumer-side: `odrl:Offer` in a `ContractRequestMessage` + +Firstly, when transmitting a [`ContractRequestMessage`](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol/contract-negotiation/contract.negotiation.protocol#id-2.1-contract-request-message) +(for example triggered via the EDC's [contract-negotiations API](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/docs/usage/management-api-walkthrough/05_contractnegotiations.md)), the +Consumer must signify consent to the Offer by including it in the Request and adding the `odrl:target` property on the +level of an `odrl:Offer`. It is a very, very bad idea to simply copy the next-best Offer from the Catalog and replay it +to the Provider. Instead, Consumers must perform internal checks which (if any) Offer proposes terms that they want to +agree to. It is possible (though not usual) to encode pricing information in an `odrl:Offer`. Sending a +`ContractRequestMessage` echoing the pricing information would represent a legally binding agreement in accordance to +the conditions proposed by the Provider's Offer. Thus, selecting an offer extended by a Provider company should thus be +handled with appropriate care. + +The Provider will usually accept the ContractRequest only if the extended Offer is semantically equivalent to his own +as distributed via the Catalog. + +### Provider-side: Checking a Consumer's Verifiable Presentation + +In addition to checking the Offer's structure, Providers have the chance to query the Consumer's Verifiable Presentation. +There, they may find additional information if a Consumer is eligible to pass a certain `odrl:Constraint`. If, for +example, the Consumer tries to negotiate for an Offer that is extended only to interested parties from civil society +(like an NGO), simply pretending to be an NGO shouldn't be enough. It has to be verified. + +For that, verifiable credentials (VCs) are issued during the onboarding process according to the role a Participant +assumes in the Dataspace. These VCs are presented by Consumers to Providers when initiating data exchange in the form +of verifiable presentations (VPs). For more on this, refer to standards CX-0018 and CX-0149. + +#### Example + +A offer containing a `odrl:Use` permission with a `odrl:Constraint` could (in a hypothetical scenario) look like this: + +```json +{ + "@context": { + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "@id": "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtNA==:anNvbi0xLXBhcGVy:Y2JhMGFmM2QtZTIwYi00ZjExLThlZmQtM2FhMzcyZmI1Nzhh", + "@type": "odrl:Set", + "odrl:permission": { + "odrl:action": { + "odrl:type": "http://www.w3.org/ns/odrl/2/use" + }, + "odrl:constraint": { + "odrl:and": [ + { + "odrl:leftOperand": "https://w3id.org/some-dataspace/role", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "NGO" + } + ] + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] +} +``` + +There could now be a credential with a property `https://w3id.org/some-dataspace/role` in the `credentialSubject` +object. + +```json +{ + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://w3id.org/mydataspace/credentials/v1.0.0" + ], + "id": "1f36af58-0fc0-4b24-9b1c-e37d59668089", + "type": [ + "VerifiableCredential" + ], + "issuer": "did:web:com.example.issuer", + "issuanceDate": "2021-06-16T18:56:59Z", + "expirationDate": "2022-06-16T18:56:59Z", + "credentialSubject": { + "id": "did:web:com.example.participant", + "holderIdentifier": "BPNL000000001", + "https://w3id.org/some-dataspace/role": "NGO" + } +} +``` + +A Provider Connector would have to have appropriate logic implemented to link the `odrl:Constraint` to the relevant data +expected in the verifiable credential. diff --git a/sidebarsDocsKits.js b/sidebarsDocsKits.js index d8f4f663487..e87987149fa 100644 --- a/sidebarsDocsKits.js +++ b/sidebarsDocsKits.js @@ -243,7 +243,20 @@ const sidebars = { collapsed: true, items: [ 'kits/Connector Kit/page_changelog', - 'kits/Connector Kit/Adoption View/connector_kit_adoption_view', + { + type: 'category', + label: 'Adoption View', + link: { + type: 'doc', + id: 'kits/Connector Kit/Adoption View/connector_kit_adoption_view' + }, + items: [ + { + type: 'autogenerated', + dirName: 'kits/Connector Kit/Adoption View', + }, + ] + }, { type: 'category', label: 'Development View', From 44bb76beed2ab9eb7a0e0a3c2b7d7cef9229094a Mon Sep 17 00:00:00 2001 From: arnoweiss Date: Mon, 25 Mar 2024 21:34:26 +0100 Subject: [PATCH 02/15] docs(conn): add skeleton for catena-specific policy regulations --- .../Adoption View/policies-in-catena.md | 31 +++++++++++++++++++ .../Adoption View/working-with-policies.md | 4 +-- 2 files changed, 32 insertions(+), 3 deletions(-) create mode 100644 docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md diff --git a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md new file mode 100644 index 00000000000..83048197619 --- /dev/null +++ b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md @@ -0,0 +1,31 @@ +--- +sidebar_position: 3 +description: 'Conventions and behavior specific to Catena' +title: Policies in Catena-X +id: connector_kit_adoption_view_policies_cx +--- + +## Data Sovereignty in Catena-X + +In Catena-X, there's a set of conventions with regard to how Providers structure their `odrl:Offer`s. They are however +also relevant for Enablement Service Providers building components enabling connectivity to the Dataspace (as specified +in CX-0018). + +As mentioned in the primer on policies, Providers and Consumers must have a common +understanding of the meaning and consequences of `odrl:Offers` and, on a more granular level, their `odrl:Constraints`. +That's why there is a set of predefined `odrl:Constraints` - all of which have to be [accepted explicitly](working-with-policies.md#consumer-side-odrloffer-in-a-contractrequestmessage) +and some [checked against a Consumer's VP](working-with-policies.md#provider-side-checking-a-consumers-verifiable-presentation) additionally. +They are formalized in the Catena-X ODRL profile (to be published soon) which extends the regular [ODRL vocabulary](https://www.w3.org/TR/odrl-vocab/). + +Here's a non-normative overview: + +### Framework Agreements + +Framework Agreements are references to legally binding documents which a Participant commits to during Onboarding. They +are roughly structured along the lines of business scenarios under which a set of business partners want to exchange +data. + +### Usage Purposes + + +### Contract References diff --git a/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md index a96c84a804b..ffb5abc6259 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md +++ b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md @@ -1,6 +1,6 @@ --- sidebar_position: 2 -description: 'Guidance on best practices' +description: 'General Information on EDC Policies' title: Working with Policies id: connector_kit_adoption_view_policies --- @@ -230,8 +230,6 @@ For that, verifiable credentials (VCs) are issued during the onboarding process assumes in the Dataspace. These VCs are presented by Consumers to Providers when initiating data exchange in the form of verifiable presentations (VPs). For more on this, refer to standards CX-0018 and CX-0149. -#### Example - A offer containing a `odrl:Use` permission with a `odrl:Constraint` could (in a hypothetical scenario) look like this: ```json From 0e30869e4d9523d5cdf1331b0f9b23ad8c6db233 Mon Sep 17 00:00:00 2001 From: arnoweiss Date: Thu, 28 Mar 2024 14:06:05 +0100 Subject: [PATCH 03/15] docs(conn): incorporate review, elaborate on cx specific constraints, DEPENDENCIES --- DEPENDENCIES | 2 +- .../Adoption View/policies-in-catena.md | 219 +++++++++++++++- .../Adoption View/working-with-policies.md | 234 +++--------------- 3 files changed, 239 insertions(+), 216 deletions(-) diff --git a/DEPENDENCIES b/DEPENDENCIES index 9c5511cacc9..264f2084b19 100644 --- a/DEPENDENCIES +++ b/DEPENDENCIES @@ -1284,7 +1284,7 @@ npm/npmjs/@types/parse-json/4.0.0, MIT, approved, clearlydefined npm/npmjs/@types/parse5/5.0.3, MIT, approved, clearlydefined npm/npmjs/@types/parse5/6.0.3, MIT, approved, clearlydefined npm/npmjs/@types/prop-types/15.7.5, MIT, approved, clearlydefined -npm/npmjs/@types/qs/6.9.7, MIT, approved, clearlydefined +npm/npmjs/@types/qs/6.9.7, MIT, approved, #13991 npm/npmjs/@types/range-parser/1.2.4, MIT, approved, #10795 npm/npmjs/@types/react-is/17.0.3, MIT, approved, #8424 npm/npmjs/@types/react-redux/7.1.25, MIT, approved, #10970 diff --git a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md index 83048197619..d7caf6afe38 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md +++ b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md @@ -1,6 +1,6 @@ --- sidebar_position: 3 -description: 'Conventions and behavior specific to Catena' +description: 'Conventions and behavior specific to Catena-X' title: Policies in Catena-X id: connector_kit_adoption_view_policies_cx --- @@ -9,23 +9,222 @@ id: connector_kit_adoption_view_policies_cx In Catena-X, there's a set of conventions with regard to how Providers structure their `odrl:Offer`s. They are however also relevant for Enablement Service Providers building components enabling connectivity to the Dataspace (as specified -in CX-0018). +in CX-0018). The authoritative resource for schemas is +the [Catena-X ODRL Profile](https://github.com/catenax-eV/cx-odrl-profile). As mentioned in the primer on policies, Providers and Consumers must have a common understanding of the meaning and consequences of `odrl:Offers` and, on a more granular level, their `odrl:Constraints`. -That's why there is a set of predefined `odrl:Constraints` - all of which have to be [accepted explicitly](working-with-policies.md#consumer-side-odrloffer-in-a-contractrequestmessage) -and some [checked against a Consumer's VP](working-with-policies.md#provider-side-checking-a-consumers-verifiable-presentation) additionally. -They are formalized in the Catena-X ODRL profile (to be published soon) which extends the regular [ODRL vocabulary](https://www.w3.org/TR/odrl-vocab/). +That's why there is a set of predefined `odrl:Constraints` - all of which have to +be [accepted explicitly](working-with-policies.md#consumer-side-odrloffer-in-a-contractrequestmessage) +and +some [checked against a Consumer's VP](working-with-policies.md#provider-side-checking-a-consumers-verifiable-presentation) +additionally. They are formalized in the [Catena-X ODRL profile](https://github.com/catenax-eV/cx-odrl-profile) +which extends the regular [ODRL vocabulary](https://www.w3.org/TR/odrl-vocab/). -Here's a non-normative overview: +Here's a non-normative overview of these extensions: -### Framework Agreements +### Framework Agreement Constraints -Framework Agreements are references to legally binding documents which a Participant commits to during Onboarding. They -are roughly structured along the lines of business scenarios under which a set of business partners want to exchange -data. +Framework Agreement Constraints are references to legally binding documents setup by the Catena-X association. They +govern the _"who, with whom, what, where from and where to, why, how, and when"_ of Data Sharing in Catena-X Use-Cases +([Source](https://catena-x.net/en/catena-x-introduce-implement/governance-framework-for-data-space-operations)). +Framework Agreements are roughly structured along the lines of business scenarios under which a set of business partners +want to exchange data. + +Each Participant commits to a set of Framework Agreements during Onboarding. They are +granted a set of VCs as proof of that commitment. Consequently, Framework Agreement Constraints belong to the kind +of `odrl:Constraint`s that have to +be [checked against a VP](working-with-policies.md#provider-side-checking-a-consumers-verifiable-presentation). +The complete set is listed in the most current version of +standard [CX-0050 Framework Credential](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0050-FrameworkAgreementCredential-v.1.0.0.pdf) ( +link opens pdf). +Framework Agreements are referred to in a machine-readable way in a Provider's Offers. When a Consumer starts the +negotiation for said offer, not only will the Policy in the `ContractRequestMessage` be checked but also his +Credentials. Here's an example of an `odrl:Constraint` referencing a Framework Agreement and invoking the VC-check: + +```json +{ + "@context": { + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "odrl:leftOperand": "https://w3id.org/catenax/policy/FrameworkAgreement", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "traceability:1.0" +} +``` ### Usage Purposes +Purposes are usually part of a Framework Agreement and restrict the purpose the Consumer is privileged to use the +obtained data for. Unlike a Framework Agreement Constraint, the purposes are NOT checked against VCs, thus necessary +for a successful negotiation mechanism is +only [the Consumer's consent to the Offer](working-with-policies.md#consumer-side-odrloffer-in-a-contractrequestmessage). +Here's an example from +the [Framework Agreement Traceability](https://catena-x.net/fileadmin/user_upload/04_Einfuehren_und_umsetzen/Governance_Framework/231016_Catena-X_Use_Case_Framework_Traceability.pdf) +(link opens pdf): + +| Predefined Policy | Typically used where? | Predefined Purpose | +|------------------------------------|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `purpose.trace.v1.qualityanalysis` | Notification API | The data can be used for quality analysis to identify and select affected components and to send quality notifications to affected customers or suppliers | + +A `odrl:Constraint` referencing this purpose looks like this: + +```json +{ + "@context": { + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "odrl:leftOperand": "https://w3id.org/catenax/policy/UsagePurpose", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "purpose.trace.v1.qualityanalysis" +} +``` ### Contract References + +Contract References by default aren't checked against credentials either. They are a vehicle to refer to contracts that +are not governed by the Catena-X association - for instance bilaterally. Referencing such a contract's identifier can +be achieved via an `odrl:Constraint` like this: + +```json +{ + "@context": { + "odrl": "http://www.w3.org/ns/odrl/2/" + }, + "odrl:leftOperand": "https://w3id.org/catenax/policy/ContractReference", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "contract-123456789" +} +``` + +### Chaining Constraints + +If a Policy is supposed to hold multiple constraints, Data Providers may chain them via a logical AND. This can be +achieved via an `odrl:and` object encapsulating multiple other `odrl:Constraint`s or entering a list of them +into the `odrl:constraint` property. The example below contains both versions. + +Constraints that are supposed to be checked with a logical OR should be published as separate Data Offers. + +## Example + +This specific Catalog contains one single `dcat:Dataset`, called "json-1-paper". It is the only entry in the top-level +`dcat:dataset` property. To access this Dataset, the Consumer can choose between four Offers (see the `odrl:hasPolicy` +property): + +- `"Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMg==:anNvbi0xLXBhcGVy:ZDA4ZDM5OTgtOGY5ZS00MzBmLThjZDEtZmYwOWQxMmQxYzk5"` +- `"Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMQ==:anNvbi0xLXBhcGVy:ODFkMDI2MWYtNDNlNi00ZTIxLWJkMWYtZmFmZTI3MWQwYzhj"` + +```json +{ + "@context": { + "@vocab": "https://w3id.org/edc/v0.0.1/ns/", + "edc": "https://w3id.org/edc/v0.0.1/ns/", + "tx": "https://w3id.org/tractusx/v0.0.1/ns/", + "dcat": "http://www.w3.org/ns/dcat#", + "dct": "https://purl.org/dc/terms/", + "odrl": "http://www.w3.org/ns/odrl/2/", + "dspace": "https://w3id.org/dspace/v0.8/" + }, + "@id": "693e9b66-04f2-4bfb-b3cd-daf5857b47c9", + "@type": "dcat:Catalog", + "dcat:dataset": [ + { + "@id": "json-1-paper", + "@type": "dcat:Dataset", + "odrl:hasPolicy": [ + { + "@id": "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMg==:anNvbi0xLXBhcGVy:ZDA4ZDM5OTgtOGY5ZS00MzBmLThjZDEtZmYwOWQxMmQxYzk5", + "@type": "odrl:Set", + "odrl:permission": { + "odrl:action": { + "odrl:type": "http://www.w3.org/ns/odrl/2/use" + }, + "odrl:constraint": { + "odrl:and": [ + { + "odrl:leftOperand": "https://w3id.org/catenax/policy/FrameworkAgreement", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "traceability:1.0" + }, + { + "odrl:leftOperand": "https://w3id.org/catenax/policy/UsagePurpose", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "ID 3.1 Trace" + } + ] + } + }, + "odrl:prohibition": [], + "odrl:obligation": [] + }, + { + "@id": "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMQ==:anNvbi0xLXBhcGVy:ODFkMDI2MWYtNDNlNi00ZTIxLWJkMWYtZmFmZTI3MWQwYzhj", + "@type": "odrl:Set", + "odrl:permission": { + "odrl:action": { + "odrl:type": "http://www.w3.org/ns/odrl/2/use" + }, + "odrl:constraint": [ + { + "odrl:leftOperand": "https://w3id.org/catenax/policy/FrameworkAgreement", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "traceability:1.0" + }, + { + "odrl:leftOperand": "https://w3id.org/catenax/policy/ContractReference", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "contract-123456789" + }, + { + "odrl:leftOperand": "https://w3id.org/catenax/policy/UsagePurpose", + "odrl:operator": { + "@id": "odrl:eq" + }, + "odrl:rightOperand": "ID 3.1 Trace" + } + ] + }, + "odrl:prohibition": [], + "odrl:obligation": [] + } + ], + "dcat:distribution": [ + { + "@type": "dcat:Distribution", + "dct:format": { + "@id": "HttpData-PULL" + }, + "dcat:accessService": "911f5da0-c9ee-4259-9a95-39428d08f767" + } + ], + "version": 1.0, + "content-type": "application/json", + "name": "json-1-paper", + "description": "Asset json-1-paper for test purposes", + "id": "json-1-paper" + } + ], + "dcat:service": { + "@id": "911f5da0-c9ee-4259-9a95-39428d08f767", + "@type": "dcat:DataService", + "dct:terms": "connector", + "dct:endpointUrl": "https://provider-dsp-end.point/api/v1/dsp" + }, + "participantId": "PROVIDER-BPNL" +} + +``` diff --git a/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md index ffb5abc6259..3f39ecdc4cd 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md +++ b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md @@ -7,201 +7,25 @@ id: connector_kit_adoption_view_policies ## Working with Policies -Policies are a formalization of the terms under which a Provider extends an offer to the Dataspace. The format is given -by the Dataspace Protocol Specification: The [Open Digital Rights Language (ODRL)](https://www.w3.org/TR/odrl-model/). - -Like all payloads that get exchanged between connectors, ODRL is an RDF-based description language that is on exchange +Policies are a formalization of the terms under which a Provider extends an offer to the Dataspace. The [Dataspace +Protocol Specification](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol) +has selected the [Open Digital Rights Language (ODRL)](https://www.w3.org/TR/odrl-model/) as a formalism and vocabulary to describe such offers. +This site (and its [specialization for Catena-X](policies-in-catena.md)) exclusively cover the topic of Policies in the +sense of the Dataspace Protocol. The EDC also uses ODRL-Policies to restrict visibility on Catalog-Entries - calling +them "Access Policies". Selecting the right Access Policies is a matter of the individual Data Provider and not +regulated by the Dataspace. Doing it properly however is essential to comply with fundamental anti-trust and information +security requirements. + +Like all payloads that get passed between connectors, ODRL is an RDF-based description language that is on the wire serialized as JSON-LD. JSON-LD is namespace-aware JSON with a couple of twists that one should be aware of when working with it (like "Structures may be semantically equivalent even though, schematically, they are clearly not"). ODRL enables a Provider to be very specific when it comes to the usage of data: What may a consumer do with it? What obligations does a consumer incur when accepting the offer? -The first time the Consumer encounters a Policy is when evaluating a Provider's [Catalog](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol/catalog/catalog.protocol), as displayed below. -This specific Catalog contains one single `dcat:Dataset`, called "json-1-paper". It is the only entry in the top-level -`dcat:dataset` property. To access this Dataset, the Consumer can choose between four Offers (see the `odrl:hasPolicy` -property): - -- "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtNA==:anNvbi0xLXBhcGVy:Y2JhMGFmM2QtZTIwYi00ZjExLThlZmQtM2FhMzcyZmI1Nzhh" -- "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMg==:anNvbi0xLXBhcGVy:ZDA4ZDM5OTgtOGY5ZS00MzBmLThjZDEtZmYwOWQxMmQxYzk5" -- "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMw==:anNvbi0xLXBhcGVy:NDQ1ZWRlZDMtNjNlMy00ZDg0LTkxMmUtYWFjZWM0MjdkMDQ4" -- "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMQ==:anNvbi0xLXBhcGVy:ODFkMDI2MWYtNDNlNi00ZTIxLWJkMWYtZmFmZTI3MWQwYzhj" - -```json -{ - "@context": { - "@vocab": "https://w3id.org/edc/v0.0.1/ns/", - "edc": "https://w3id.org/edc/v0.0.1/ns/", - "tx": "https://w3id.org/tractusx/v0.0.1/ns/", - "dcat": "http://www.w3.org/ns/dcat#", - "dct": "https://purl.org/dc/terms/", - "odrl": "http://www.w3.org/ns/odrl/2/", - "dspace": "https://w3id.org/dspace/v0.8/" - }, - "@id": "693e9b66-04f2-4bfb-b3cd-daf5857b47c9", - "@type": "dcat:Catalog", - "dcat:dataset": [ - { - "@id": "json-1-paper", - "@type": "dcat:Dataset", - "odrl:hasPolicy": [ - { - "@id": "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtNA==:anNvbi0xLXBhcGVy:Y2JhMGFmM2QtZTIwYi00ZjExLThlZmQtM2FhMzcyZmI1Nzhh", - "@type": "odrl:Set", - "odrl:permission": { - "odrl:action": { - "odrl:type": "http://www.w3.org/ns/odrl/2/use" - }, - "odrl:constraint": { - "odrl:and": [ - { - "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/FrameworkAgreement", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "traceability:v1.0" - }, - { - "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/ContractReference", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "contract-123456789" - }, - { - "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/UsagePurpose", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "ID 3.1 Trace" - }, - { - "odrl:leftOperand": "https://w3id.org/edc/v0.0.1/ns/AgreetoWhatever", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "Yes" - } - ] - } - }, - "odrl:prohibition": [], - "odrl:obligation": [] - }, - { - "@id": "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMg==:anNvbi0xLXBhcGVy:ZDA4ZDM5OTgtOGY5ZS00MzBmLThjZDEtZmYwOWQxMmQxYzk5", - "@type": "odrl:Set", - "odrl:permission": { - "odrl:action": { - "odrl:type": "http://www.w3.org/ns/odrl/2/use" - }, - "odrl:constraint": { - "odrl:and": [ - { - "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/FrameworkAgreement", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "traceability:v1.0" - }, - { - "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/UsagePurpose", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "ID 3.1 Trace" - } - ] - } - }, - "odrl:prohibition": [], - "odrl:obligation": [] - }, - { - "@id": "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMw==:anNvbi0xLXBhcGVy:NDQ1ZWRlZDMtNjNlMy00ZDg0LTkxMmUtYWFjZWM0MjdkMDQ4", - "@type": "odrl:Set", - "odrl:permission": { - "odrl:action": { - "odrl:type": "http://www.w3.org/ns/odrl/2/use" - }, - "odrl:constraint": { - "odrl:and": { - "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/FrameworkAgreement", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "traceability:v1.0" - } - } - }, - "odrl:prohibition": [], - "odrl:obligation": [] - }, - { - "@id": "Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMQ==:anNvbi0xLXBhcGVy:ODFkMDI2MWYtNDNlNi00ZTIxLWJkMWYtZmFmZTI3MWQwYzhj", - "@type": "odrl:Set", - "odrl:permission": { - "odrl:action": { - "odrl:type": "http://www.w3.org/ns/odrl/2/use" - }, - "odrl:constraint": { - "odrl:and": [ - { - "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/FrameworkAgreement", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "traceability:v1.0" - }, - { - "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/ContractReference", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "contract-123456789" - }, - { - "odrl:leftOperand": "https://w3id.org/catenax/policy/v1.0.0/UsagePurpose", - "odrl:operator": { - "@id": "odrl:eq" - }, - "odrl:rightOperand": "ID 3.1 Trace" - } - ] - } - }, - "odrl:prohibition": [], - "odrl:obligation": [] - } - ], - "dcat:distribution": [ - { - "@type": "dcat:Distribution", - "dct:format": { - "@id": "HttpData-PULL" - }, - "dcat:accessService": "911f5da0-c9ee-4259-9a95-39428d08f767" - } - ], - "version": 1.0, - "content-type": "application/json", - "name": "json-1-paper", - "description": "Asset json-1-paper for test purposes", - "id": "json-1-paper" - } - ], - "dcat:service": { - "@id": "911f5da0-c9ee-4259-9a95-39428d08f767", - "@type": "dcat:DataService", - "dct:terms": "connector", - "dct:endpointUrl": "https://provider-dsp-end.point/api/v1/dsp" - }, - "participantId": "PROVIDER-BPNL" -} - -``` - -These four Offers are of `@type` either `odrl:Offer` or one of its subclasses. More interesting however are the -`odrl:permission`, `odrl:prohibition` and `odrl:obligation` properties. They contain `odrl:Rules` that have to be +The first time the Consumer encounters a Policy is when evaluating a Provider's [Catalog](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol/catalog/catalog.protocol). These four Offers are +of `@type` `odrl:Set` which is a [subclass](https://www.w3.org/TR/odrl-model/#policy-set) of `odrl:Policy`. +All terms can be used interchangeably, Offer is most common. Their content is contained in the +`odrl:permission`, `odrl:prohibition` and `odrl:obligation` properties. They hold `odrl:Rules` that have to be satisfied by the Consumer. There's two ways that can happen. ### Consumer-side: `odrl:Offer` in a `ContractRequestMessage` @@ -221,14 +45,16 @@ as distributed via the Catalog. ### Provider-side: Checking a Consumer's Verifiable Presentation -In addition to checking the Offer's structure, Providers have the chance to query the Consumer's Verifiable Presentation. -There, they may find additional information if a Consumer is eligible to pass a certain `odrl:Constraint`. If, for -example, the Consumer tries to negotiate for an Offer that is extended only to interested parties from civil society -(like an NGO), simply pretending to be an NGO shouldn't be enough. It has to be verified. +In addition to checking the Offer's structure (as above), Providers' Connectors have the chance to query the Consumer's +Verifiable Presentation (VP). A VP is a set of Verifiable Credentials (VCs) that a Consumer may have been issued by a +trusted third party. In this PR, a Provider may find additional information if a Consumer is eligible to pass a certain +`odrl:Constraint`. -For that, verifiable credentials (VCs) are issued during the onboarding process according to the role a Participant -assumes in the Dataspace. These VCs are presented by Consumers to Providers when initiating data exchange in the form -of verifiable presentations (VPs). For more on this, refer to standards CX-0018 and CX-0149. +If, for example, the Consumer tries to negotiate for an Offer that is extended only to interested +parties from civil society (like an NGO), simply pretending to be an NGO shouldn't be enough. It has to be verified and +can be verified with help of the VP. For that, a "NonGovernmentalOrganizationCredential" could be issued during the +onboarding process according to the role a Participant assumes in the Dataspace. For more on the interrelation between +Credentials and Constraints, refer to standards CX-0018 and CX-0149. A offer containing a `odrl:Use` permission with a `odrl:Constraint` could (in a hypothetical scenario) look like this: @@ -260,8 +86,9 @@ A offer containing a `odrl:Use` permission with a `odrl:Constraint` could (in a } ``` -There could now be a credential with a property `https://w3id.org/some-dataspace/role` in the `credentialSubject` -object. +The Constraint would in that case be checked against the `"type"` property, attesting the information that the presented +VC does in fact attest that the holder is a Non-Governmental Organization. A Provider Connector would have to have +appropriate logic implemented to extract relevant information from the VP to satisfy the `odrl:Constraint`. ```json { @@ -271,18 +98,15 @@ object. ], "id": "1f36af58-0fc0-4b24-9b1c-e37d59668089", "type": [ - "VerifiableCredential" + "VerifiableCredential", + "NonGovernmentalOrganizationCredential" ], "issuer": "did:web:com.example.issuer", "issuanceDate": "2021-06-16T18:56:59Z", "expirationDate": "2022-06-16T18:56:59Z", "credentialSubject": { "id": "did:web:com.example.participant", - "holderIdentifier": "BPNL000000001", - "https://w3id.org/some-dataspace/role": "NGO" + "holderIdentifier": "BPNL000000001" } } ``` - -A Provider Connector would have to have appropriate logic implemented to link the `odrl:Constraint` to the relevant data -expected in the verifiable credential. From 5db25b2e99f053a44d9fa2a7fe0e536431ff4f9f Mon Sep 17 00:00:00 2001 From: arnoweiss Date: Thu, 28 Mar 2024 14:20:56 +0100 Subject: [PATCH 04/15] docs(conn): remove deprecated purposes, link to edc-docs --- .../kits/Connector Kit/Adoption View/policies-in-catena.md | 4 ++-- .../kits/Connector Kit/Adoption View/working-with-policies.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md index d7caf6afe38..3265e139c3e 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md +++ b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md @@ -159,7 +159,7 @@ property): "odrl:operator": { "@id": "odrl:eq" }, - "odrl:rightOperand": "ID 3.1 Trace" + "odrl:rightOperand": "purpose.trace.v1.aspects" } ] } @@ -194,7 +194,7 @@ property): "odrl:operator": { "@id": "odrl:eq" }, - "odrl:rightOperand": "ID 3.1 Trace" + "odrl:rightOperand": "purpose.trace.v1.aspects" } ] }, diff --git a/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md index 3f39ecdc4cd..af5aa8e89e5 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md +++ b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md @@ -12,7 +12,7 @@ Protocol Specification](https://docs.internationaldataspaces.org/ids-knowledgeba has selected the [Open Digital Rights Language (ODRL)](https://www.w3.org/TR/odrl-model/) as a formalism and vocabulary to describe such offers. This site (and its [specialization for Catena-X](policies-in-catena.md)) exclusively cover the topic of Policies in the sense of the Dataspace Protocol. The EDC also uses ODRL-Policies to restrict visibility on Catalog-Entries - calling -them "Access Policies". Selecting the right Access Policies is a matter of the individual Data Provider and not +them [Access Policies](https://github.com/eclipse-tractusx/tractusx-edc/blob/main/docs/usage/management-api-walkthrough/02_policies.md#access--usage-policies). Selecting the right Access Policies is a matter of the individual Data Provider and not regulated by the Dataspace. Doing it properly however is essential to comply with fundamental anti-trust and information security requirements. From f52b6e0df771c8dd8571c2be66f78c3b15938273 Mon Sep 17 00:00:00 2001 From: arnoweiss Date: Thu, 28 Mar 2024 15:15:41 +0100 Subject: [PATCH 05/15] docs(conn): add and edit copyright notice --- .../kits/Connector Kit/Adoption View/adoption-view.md | 2 +- .../Connector Kit/Adoption View/policies-in-catena.md | 8 ++++++++ .../Connector Kit/Adoption View/working-with-policies.md | 8 ++++++++ .../kits/Connector Kit/Development View/architecture.md | 2 +- .../kits/Connector Kit/Development View/specifications.md | 2 +- 5 files changed, 19 insertions(+), 3 deletions(-) diff --git a/docs-kits/kits/Connector Kit/Adoption View/adoption-view.md b/docs-kits/kits/Connector Kit/Adoption View/adoption-view.md index 474ef7c682f..e0c64e23092 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/adoption-view.md +++ b/docs-kits/kits/Connector Kit/Adoption View/adoption-view.md @@ -203,7 +203,7 @@ This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses - SPDX-FileCopyrightText: 2023 msg systems AG - SPDX-FileCopyrightText: 2023 Mercedes-Benz Group AG - SPDX-FileCopyrightText: 2023 Contributors of the Eclipse Foundation -- Source URL: [https://github.com/eclipse-tractusx/tractusx-edc](https://github.com/eclipse-tractusx/tractusx-edc) +- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) [edc-url]: https://github.com/eclipse-edc/Connector diff --git a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md index 3265e139c3e..fa92c177a4e 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md +++ b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md @@ -228,3 +228,11 @@ property): } ``` + +## Notice + +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: 2023 Contributors of the Eclipse Foundation +- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md index af5aa8e89e5..82db191f2dd 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md +++ b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md @@ -110,3 +110,11 @@ appropriate logic implemented to extract relevant information from the VP to sat } } ``` + +## Notice + +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: 2023 Contributors of the Eclipse Foundation +- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs-kits/kits/Connector Kit/Development View/architecture.md b/docs-kits/kits/Connector Kit/Development View/architecture.md index 635d6be55f6..c6d3b8ce7cd 100644 --- a/docs-kits/kits/Connector Kit/Development View/architecture.md +++ b/docs-kits/kits/Connector Kit/Development View/architecture.md @@ -67,4 +67,4 @@ This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses - SPDX-License-Identifier: CC-BY-4.0 - SPDX-FileCopyrightText: 2023 Contributors of the Eclipse Foundation -- Source URL: [https://github.com/eclipse-tractusx/tractusx-edc](https://github.com/eclipse-tractusx/tractusx-edc) +- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs-kits/kits/Connector Kit/Development View/specifications.md b/docs-kits/kits/Connector Kit/Development View/specifications.md index 6cb5ea80191..9c8d490a236 100644 --- a/docs-kits/kits/Connector Kit/Development View/specifications.md +++ b/docs-kits/kits/Connector Kit/Development View/specifications.md @@ -35,4 +35,4 @@ This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses - SPDX-License-Identifier: CC-BY-4.0 - SPDX-FileCopyrightText: 2023 Contributors of the Eclipse Foundation -- Source URL: [https://github.com/eclipse-tractusx/tractusx-edc](https://github.com/eclipse-tractusx/tractusx-edc) +- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) From 1c03dd4bd27b80b88b4d5ba5d49a83ef221f5223 Mon Sep 17 00:00:00 2001 From: arnoweiss Date: Thu, 28 Mar 2024 15:23:13 +0100 Subject: [PATCH 06/15] docs(conn): add carved-out text from IC Kit draft to Connector Kit --- .../Adoption View/policies-in-catena.md | 41 +++++++++---------- 1 file changed, 20 insertions(+), 21 deletions(-) diff --git a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md index fa92c177a4e..dd791a59d7b 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md +++ b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md @@ -7,19 +7,22 @@ id: connector_kit_adoption_view_policies_cx ## Data Sovereignty in Catena-X -In Catena-X, there's a set of conventions with regard to how Providers structure their `odrl:Offer`s. They are however -also relevant for Enablement Service Providers building components enabling connectivity to the Dataspace (as specified -in CX-0018). The authoritative resource for schemas is -the [Catena-X ODRL Profile](https://github.com/catenax-eV/cx-odrl-profile). +In Catena-X, there's a set of conventions with regard to how Providers structure their `odrl:Offer`s. + +A general recommendation is to focus on `permission` property to further specify the contracts' details. In general, +every data provider can decide on his or her own under which conditions their data datasets (assets) are shared in the +network. In practice, this works as long as both parties, Provider and Consumer, have the same understanding of its +legal meaning. Therefore, standardized such `Constraint`s with their `leftOperand`s and `rightOperand`s are key for automation. Still, individual freedom of contract is a very high good and is still possible. + +This guidance is however also relevant for Enablement Service Providers building components enabling connectivity to the +Dataspace (as specified in CX-0018). The authoritative resource for schemas is the [Catena-X ODRL Profile](https://github.com/catenax-eV/cx-odrl-profile). As mentioned in the primer on policies, Providers and Consumers must have a common understanding of the meaning and consequences of `odrl:Offers` and, on a more granular level, their `odrl:Constraints`. -That's why there is a set of predefined `odrl:Constraints` - all of which have to -be [accepted explicitly](working-with-policies.md#consumer-side-odrloffer-in-a-contractrequestmessage) -and -some [checked against a Consumer's VP](working-with-policies.md#provider-side-checking-a-consumers-verifiable-presentation) -additionally. They are formalized in the [Catena-X ODRL profile](https://github.com/catenax-eV/cx-odrl-profile) -which extends the regular [ODRL vocabulary](https://www.w3.org/TR/odrl-vocab/). +That's why there is a set of predefined `odrl:Constraints` - all of which have to be [accepted explicitly](working-with-policies.md#consumer-side-odrloffer-in-a-contractrequestmessage) and +some [checked against a Consumer's VP](working-with-policies.md#provider-side-checking-a-consumers-verifiable-presentation) additionally. They are formalized in the [Catena-X ODRL profile](https://github.com/catenax-eV/cx-odrl-profile) +which extends the regular [ODRL vocabulary](https://www.w3.org/TR/odrl-vocab/). Since usage or contract policies are highly dependent on the use case, +they are described by them in their associated KITs and only general elements are explained in the following. Here's a non-normative overview of these extensions: @@ -31,13 +34,10 @@ govern the _"who, with whom, what, where from and where to, why, how, and when"_ Framework Agreements are roughly structured along the lines of business scenarios under which a set of business partners want to exchange data. -Each Participant commits to a set of Framework Agreements during Onboarding. They are -granted a set of VCs as proof of that commitment. Consequently, Framework Agreement Constraints belong to the kind -of `odrl:Constraint`s that have to -be [checked against a VP](working-with-policies.md#provider-side-checking-a-consumers-verifiable-presentation). -The complete set is listed in the most current version of -standard [CX-0050 Framework Credential](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0050-FrameworkAgreementCredential-v.1.0.0.pdf) ( -link opens pdf). +Each Participant commits to a set of Framework Agreements during Onboarding. They are granted a set of VCs as proof of +that commitment. Consequently, Framework Agreement Constraints belong to the kind of `odrl:Constraint`s that have to be +[checked against a VP](working-with-policies.md#provider-side-checking-a-consumers-verifiable-presentation). The complete set is listed in the most current version of standard +[CX-0050 Framework Credential](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0050-FrameworkAgreementCredential-v.1.0.0.pdf) (link opens pdf). Framework Agreements are referred to in a machine-readable way in a Provider's Offers. When a Consumer starts the negotiation for said offer, not only will the Policy in the `ContractRequestMessage` be checked but also his Credentials. Here's an example of an `odrl:Constraint` referencing a Framework Agreement and invoking the VC-check: @@ -59,10 +59,9 @@ Credentials. Here's an example of an `odrl:Constraint` referencing a Framework A Purposes are usually part of a Framework Agreement and restrict the purpose the Consumer is privileged to use the obtained data for. Unlike a Framework Agreement Constraint, the purposes are NOT checked against VCs, thus necessary -for a successful negotiation mechanism is -only [the Consumer's consent to the Offer](working-with-policies.md#consumer-side-odrloffer-in-a-contractrequestmessage). -Here's an example from -the [Framework Agreement Traceability](https://catena-x.net/fileadmin/user_upload/04_Einfuehren_und_umsetzen/Governance_Framework/231016_Catena-X_Use_Case_Framework_Traceability.pdf) +for a successful negotiation mechanism is only [the Consumer's consent to the Offer](working-with-policies.md#consumer-side-odrloffer-in-a-contractrequestmessage). +Versions for UsagePurpose `rightOperand`s are typically 1-digit. +Here's an example from the [Framework Agreement Traceability](https://catena-x.net/fileadmin/user_upload/04_Einfuehren_und_umsetzen/Governance_Framework/231016_Catena-X_Use_Case_Framework_Traceability.pdf) (link opens pdf): | Predefined Policy | Typically used where? | Predefined Purpose | From 32b1f12441f9fa5b62fbe79c0a1bacfae4c11c89 Mon Sep 17 00:00:00 2001 From: arnoweiss Date: Thu, 28 Mar 2024 15:45:29 +0100 Subject: [PATCH 07/15] docs(conn): replace outdated values for purposes --- .../Adoption View/policies-in-catena.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md index dd791a59d7b..1649980df0c 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md +++ b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md @@ -66,7 +66,7 @@ Here's an example from the [Framework Agreement Traceability](https://catena-x.n | Predefined Policy | Typically used where? | Predefined Purpose | |------------------------------------|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| -| `purpose.trace.v1.qualityanalysis` | Notification API | The data can be used for quality analysis to identify and select affected components and to send quality notifications to affected customers or suppliers | +| `cx.core.qualityNotifications:1` | Notification API | The data can be used for quality analysis to identify and select affected components and to send quality notifications to affected customers or suppliers | A `odrl:Constraint` referencing this purpose looks like this: @@ -79,7 +79,7 @@ A `odrl:Constraint` referencing this purpose looks like this: "odrl:operator": { "@id": "odrl:eq" }, - "odrl:rightOperand": "purpose.trace.v1.qualityanalysis" + "odrl:rightOperand": "cx.core.qualityNotifications:1" } ``` @@ -142,7 +142,7 @@ property): "@type": "odrl:Set", "odrl:permission": { "odrl:action": { - "odrl:type": "http://www.w3.org/ns/odrl/2/use" + "@id": "http://www.w3.org/ns/odrl/2/use" }, "odrl:constraint": { "odrl:and": [ @@ -158,7 +158,7 @@ property): "odrl:operator": { "@id": "odrl:eq" }, - "odrl:rightOperand": "purpose.trace.v1.aspects" + "odrl:rightOperand": "cx.core.industrycore:1" } ] } @@ -171,7 +171,7 @@ property): "@type": "odrl:Set", "odrl:permission": { "odrl:action": { - "odrl:type": "http://www.w3.org/ns/odrl/2/use" + "@id": "http://www.w3.org/ns/odrl/2/use" }, "odrl:constraint": [ { @@ -193,7 +193,7 @@ property): "odrl:operator": { "@id": "odrl:eq" }, - "odrl:rightOperand": "purpose.trace.v1.aspects" + "odrl:rightOperand": "cx.core.industrycore:1" } ] }, @@ -225,7 +225,6 @@ property): }, "participantId": "PROVIDER-BPNL" } - ``` ## Notice From d92c002db6109da8ff81864cf75383ee29b08001 Mon Sep 17 00:00:00 2001 From: arnoweiss Date: Wed, 17 Apr 2024 13:59:37 +0200 Subject: [PATCH 08/15] fix(conn): incorporate minor review comments --- .../Adoption View/policies-in-catena.md | 59 +++++++++++-------- .../Adoption View/working-with-policies.md | 16 ++--- 2 files changed, 44 insertions(+), 31 deletions(-) diff --git a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md index 1649980df0c..a9a325d962a 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md +++ b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md @@ -12,35 +12,42 @@ In Catena-X, there's a set of conventions with regard to how Providers structure A general recommendation is to focus on `permission` property to further specify the contracts' details. In general, every data provider can decide on his or her own under which conditions their data datasets (assets) are shared in the network. In practice, this works as long as both parties, Provider and Consumer, have the same understanding of its -legal meaning. Therefore, standardized such `Constraint`s with their `leftOperand`s and `rightOperand`s are key for automation. Still, individual freedom of contract is a very high good and is still possible. +legal meaning. Therefore, standardized such `Constraint`s with their `leftOperand`s and `rightOperand`s are key for +automation. Still, individual freedom of contract is a very high good and is still possible. This guidance is however also relevant for Enablement Service Providers building components enabling connectivity to the -Dataspace (as specified in CX-0018). The authoritative resource for schemas is the [Catena-X ODRL Profile](https://github.com/catenax-eV/cx-odrl-profile). +Dataspace (as specified in CX-0018). The authoritative resource for schemas is +the [Catena-X ODRL Profile](https://github.com/catenax-eV/cx-odrl-profile). As mentioned in the primer on policies, Providers and Consumers must have a common understanding of the meaning and consequences of `odrl:Offers` and, on a more granular level, their `odrl:Constraints`. -That's why there is a set of predefined `odrl:Constraints` - all of which have to be [accepted explicitly](working-with-policies.md#consumer-side-odrloffer-in-a-contractrequestmessage) and -some [checked against a Consumer's VP](working-with-policies.md#provider-side-checking-a-consumers-verifiable-presentation) additionally. They are formalized in the [Catena-X ODRL profile](https://github.com/catenax-eV/cx-odrl-profile) -which extends the regular [ODRL vocabulary](https://www.w3.org/TR/odrl-vocab/). Since usage or contract policies are highly dependent on the use case, +That's why there is a set of predefined `odrl:Constraints` - all of which have to +be [accepted explicitly](working-with-policies.md#consumer-side-odrloffer-in-a-contractrequestmessage) and +some [checked against a Consumer's VP](working-with-policies.md#provider-side-checking-a-consumers-verifiable-presentation) +additionally. They are formalized in the [Catena-X ODRL profile](https://github.com/catenax-eV/cx-odrl-profile) +which extends the regular [ODRL vocabulary](https://www.w3.org/TR/odrl-vocab/). Since usage or contract policies are +highly dependent on the use case, they are described by them in their associated KITs and only general elements are explained in the following. Here's a non-normative overview of these extensions: -### Framework Agreement Constraints +### Use Case Framework Constraints -Framework Agreement Constraints are references to legally binding documents setup by the Catena-X association. They +Use Case Framework Constraints are references to legally binding documents set up by the Catena-X association. They govern the _"who, with whom, what, where from and where to, why, how, and when"_ of Data Sharing in Catena-X Use-Cases ([Source](https://catena-x.net/en/catena-x-introduce-implement/governance-framework-for-data-space-operations)). -Framework Agreements are roughly structured along the lines of business scenarios under which a set of business partners +Use Case Frameworks are roughly structured along the lines of business scenarios under which a set of business partners want to exchange data. -Each Participant commits to a set of Framework Agreements during Onboarding. They are granted a set of VCs as proof of -that commitment. Consequently, Framework Agreement Constraints belong to the kind of `odrl:Constraint`s that have to be -[checked against a VP](working-with-policies.md#provider-side-checking-a-consumers-verifiable-presentation). The complete set is listed in the most current version of standard -[CX-0050 Framework Credential](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0050-FrameworkAgreementCredential-v.1.0.0.pdf) (link opens pdf). -Framework Agreements are referred to in a machine-readable way in a Provider's Offers. When a Consumer starts the +Each Participant commits to a set of Use Case Frameworks during Onboarding. They are granted a set of VCs as proof of +that commitment. Consequently, Use Case Framework Constraints belong to the kind of `odrl:Constraint`s that have to be +[checked against a VP](working-with-policies.md#provider-side-checking-a-consumers-verifiable-presentation). The +complete set is listed in the most current version of standard +[CX-0050 Framework Credential](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0050-FrameworkAgreementCredential-v.1.0.0.pdf) ( +link opens pdf). +Use Case Frameworks are referred to in a machine-readable way in a Provider's Offers. When a Consumer starts the negotiation for said offer, not only will the Policy in the `ContractRequestMessage` be checked but also his -Credentials. Here's an example of an `odrl:Constraint` referencing a Framework Agreement and invoking the VC-check: +Credentials. Here's an example of an `odrl:Constraint` referencing a Use Case Framework and invoking the VC-check: ```json { @@ -57,15 +64,18 @@ Credentials. Here's an example of an `odrl:Constraint` referencing a Framework A ### Usage Purposes -Purposes are usually part of a Framework Agreement and restrict the purpose the Consumer is privileged to use the -obtained data for. Unlike a Framework Agreement Constraint, the purposes are NOT checked against VCs, thus necessary -for a successful negotiation mechanism is only [the Consumer's consent to the Offer](working-with-policies.md#consumer-side-odrloffer-in-a-contractrequestmessage). -Versions for UsagePurpose `rightOperand`s are typically 1-digit. -Here's an example from the [Framework Agreement Traceability](https://catena-x.net/fileadmin/user_upload/04_Einfuehren_und_umsetzen/Governance_Framework/231016_Catena-X_Use_Case_Framework_Traceability.pdf) -(link opens pdf): - -| Predefined Policy | Typically used where? | Predefined Purpose | -|------------------------------------|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| +Purposes are usually part of a Use Case Framework and restrict the purpose the Consumer is privileged to use the +obtained data for. Unlike a Use Case Framework Constraint, the purposes are NOT checked against VCs, thus necessary +for a successful negotiation mechanism is +only [the Consumer's consent to the Offer](working-with-policies.md#consumer-side-odrloffer-in-a-contractrequestmessage). +Versions for UsagePurpose `rightOperand`s are typically 1-digit. The complete list of usage purposes in Catena-X is +publicly available in the [CX ODRL Profile](https://github.com/catenax-eV/cx-odrl-profile). The corresponding documents +are linked on +the [Catena-X e.V. homepage](https://catena-x.net/en/catena-x-introduce-implement/governance-framework-for-data-space-operations). +Here's an example from the Use Case Framework Traceability: + +| Predefined Policy | Typically used where? | Predefined Purpose | +|----------------------------------|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| | `cx.core.qualityNotifications:1` | Notification API | The data can be used for quality analysis to identify and select affected components and to send quality notifications to affected customers or suppliers | A `odrl:Constraint` referencing this purpose looks like this: @@ -233,4 +243,5 @@ This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses - SPDX-License-Identifier: CC-BY-4.0 - SPDX-FileCopyrightText: 2023 Contributors of the Eclipse Foundation -- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) +- Source + URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md index 82db191f2dd..17c51760fb2 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md +++ b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md @@ -22,7 +22,7 @@ with it (like "Structures may be semantically equivalent even though, schematica enables a Provider to be very specific when it comes to the usage of data: What may a consumer do with it? What obligations does a consumer incur when accepting the offer? -The first time the Consumer encounters a Policy is when evaluating a Provider's [Catalog](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol/catalog/catalog.protocol). These four Offers are +The first time the Consumer encounters a Policy is when evaluating a Provider's [Catalog](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol/catalog/catalog.protocol). It contains Offers are of `@type` `odrl:Set` which is a [subclass](https://www.w3.org/TR/odrl-model/#policy-set) of `odrl:Policy`. All terms can be used interchangeably, Offer is most common. Their content is contained in the `odrl:permission`, `odrl:prohibition` and `odrl:obligation` properties. They hold `odrl:Rules` that have to be @@ -35,10 +35,10 @@ Firstly, when transmitting a [`ContractRequestMessage`](https://docs.internation Consumer must signify consent to the Offer by including it in the Request and adding the `odrl:target` property on the level of an `odrl:Offer`. It is a very, very bad idea to simply copy the next-best Offer from the Catalog and replay it to the Provider. Instead, Consumers must perform internal checks which (if any) Offer proposes terms that they want to -agree to. It is possible (though not usual) to encode pricing information in an `odrl:Offer`. Sending a -`ContractRequestMessage` echoing the pricing information would represent a legally binding agreement in accordance to -the conditions proposed by the Provider's Offer. Thus, selecting an offer extended by a Provider company should thus be -handled with appropriate care. +agree to. It is possible (though not usual) to encode obligations in the in an `odrl:Offer` that a Consumer must +satisfy. Returning a `ContractRequestMessage` to the Provider, echoing the pricing information, would represent a +legally binding agreement in accordance to the conditions proposed by the Provider's Offer. Thus, selecting an offer +extended by a Provider company should thus be handled with appropriate care. The Provider will usually accept the ContractRequest only if the extended Offer is semantically equivalent to his own as distributed via the Catalog. @@ -47,7 +47,7 @@ as distributed via the Catalog. In addition to checking the Offer's structure (as above), Providers' Connectors have the chance to query the Consumer's Verifiable Presentation (VP). A VP is a set of Verifiable Credentials (VCs) that a Consumer may have been issued by a -trusted third party. In this PR, a Provider may find additional information if a Consumer is eligible to pass a certain +trusted third party. In this VC, a Provider may find additional information if a Consumer is eligible to pass a certain `odrl:Constraint`. If, for example, the Consumer tries to negotiate for an Offer that is extended only to interested @@ -67,7 +67,9 @@ A offer containing a `odrl:Use` permission with a `odrl:Constraint` could (in a "@type": "odrl:Set", "odrl:permission": { "odrl:action": { - "odrl:type": "http://www.w3.org/ns/odrl/2/use" + "odrl:type": { + "@id": "http://www.w3.org/ns/odrl/2/use" + } }, "odrl:constraint": { "odrl:and": [ From 025f547cde7a3539d692af1316fe992cfbfffd4d Mon Sep 17 00:00:00 2001 From: arnoweiss Date: Thu, 25 Apr 2024 18:43:52 +0200 Subject: [PATCH 09/15] docs(conn): add section on policy hub --- .../Connector Kit/Adoption View/policies-in-catena.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md index a9a325d962a..5af7dd8e580 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md +++ b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md @@ -17,7 +17,11 @@ automation. Still, individual freedom of contract is a very high good and is sti This guidance is however also relevant for Enablement Service Providers building components enabling connectivity to the Dataspace (as specified in CX-0018). The authoritative resource for schemas is -the [Catena-X ODRL Profile](https://github.com/catenax-eV/cx-odrl-profile). +the [Catena-X ODRL Profile](https://github.com/catenax-eV/cx-odrl-profile). It is also available via the [Policy Hub](https://github.com/eclipse-tractusx/policy-hub/blob/main/docs/technical-documentation/requests/example-requests.md) +that is operated centrally. The API is documented in this Repository and can be accessed with an access token to the +Portal. It's a convenience feature for the negotiating parties to check if a given offer matches the policy constraints +agreed by the Catena-X association - for instance by keeping a definite list of valid `rightOperands` to a particular +`leftOperand` in a `Constraint`. As mentioned in the primer on policies, Providers and Consumers must have a common understanding of the meaning and consequences of `odrl:Offers` and, on a more granular level, their `odrl:Constraints`. @@ -123,7 +127,7 @@ Constraints that are supposed to be checked with a logical OR should be publishe ## Example This specific Catalog contains one single `dcat:Dataset`, called "json-1-paper". It is the only entry in the top-level -`dcat:dataset` property. To access this Dataset, the Consumer can choose between four Offers (see the `odrl:hasPolicy` +`dcat:dataset` property. To access this Dataset, the Consumer can choose between two Offers (see the `odrl:hasPolicy` property): - `"Y29udHJhY3QtYmlsYXRlcmFsLXBhcGVyLWV4YW1wbGUtMg==:anNvbi0xLXBhcGVy:ZDA4ZDM5OTgtOGY5ZS00MzBmLThjZDEtZmYwOWQxMmQxYzk5"` From 0ed167523a9050ec5feb8868dba3865d8798bcfb Mon Sep 17 00:00:00 2001 From: arnoweiss Date: Thu, 25 Apr 2024 19:33:33 +0200 Subject: [PATCH 10/15] docs(conn): more clearly separate generic and CX-specific sections. --- .../Connector Kit/Adoption View/working-with-policies.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md index 17c51760fb2..7afeda6d56b 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md +++ b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md @@ -7,6 +7,9 @@ id: connector_kit_adoption_view_policies ## Working with Policies +This section includes some general remarks on the concept of `Policies` and how they are treated in the EDC. The entire +page is independent of the conventions in the Catena-X Dataspace. For that, please check [Policies in Catena-X](policies-in-catena.md). + Policies are a formalization of the terms under which a Provider extends an offer to the Dataspace. The [Dataspace Protocol Specification](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol) has selected the [Open Digital Rights Language (ODRL)](https://www.w3.org/TR/odrl-model/) as a formalism and vocabulary to describe such offers. @@ -22,7 +25,7 @@ with it (like "Structures may be semantically equivalent even though, schematica enables a Provider to be very specific when it comes to the usage of data: What may a consumer do with it? What obligations does a consumer incur when accepting the offer? -The first time the Consumer encounters a Policy is when evaluating a Provider's [Catalog](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol/catalog/catalog.protocol). It contains Offers are +The first time the Consumer encounters a Policy is when evaluating a Provider's [Catalog](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol/catalog/catalog.protocol). It contains Offers of `@type` `odrl:Set` which is a [subclass](https://www.w3.org/TR/odrl-model/#policy-set) of `odrl:Policy`. All terms can be used interchangeably, Offer is most common. Their content is contained in the `odrl:permission`, `odrl:prohibition` and `odrl:obligation` properties. They hold `odrl:Rules` that have to be @@ -48,7 +51,8 @@ as distributed via the Catalog. In addition to checking the Offer's structure (as above), Providers' Connectors have the chance to query the Consumer's Verifiable Presentation (VP). A VP is a set of Verifiable Credentials (VCs) that a Consumer may have been issued by a trusted third party. In this VC, a Provider may find additional information if a Consumer is eligible to pass a certain -`odrl:Constraint`. +`odrl:Constraint`. Transfer of VPs is handled automatically between the Participants' Identity Wallets by means of the +[IATP VPP](https://github.com/eclipse-tractusx/identity-trust/blob/main/specifications/verifiable.presentation.protocol.md). If, for example, the Consumer tries to negotiate for an Offer that is extended only to interested parties from civil society (like an NGO), simply pretending to be an NGO shouldn't be enough. It has to be verified and From d4b82f24efe6cf897e948a36dab7d5c88ea44cad Mon Sep 17 00:00:00 2001 From: arnoweiss Date: Thu, 25 Apr 2024 19:55:56 +0200 Subject: [PATCH 11/15] fix(conn): spelling --- .../kits/Connector Kit/Adoption View/policies-in-catena.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md index 5af7dd8e580..567183957ca 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md +++ b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md @@ -7,9 +7,11 @@ id: connector_kit_adoption_view_policies_cx ## Data Sovereignty in Catena-X -In Catena-X, there's a set of conventions with regard to how Providers structure their `odrl:Offer`s. +This page extends on the previous section's fundamentals and introduces conventions specific to the Catena-X Dataspace. +It assumes basic knowledge on `Policies` and their processing. Please go back to [the fundamentals](working-with-policies.md) +if that's unfamiliar. -A general recommendation is to focus on `permission` property to further specify the contracts' details. In general, +Catena-X recommends to focus on `permission` property to further specify the contracts' details. In general, every data provider can decide on his or her own under which conditions their data datasets (assets) are shared in the network. In practice, this works as long as both parties, Provider and Consumer, have the same understanding of its legal meaning. Therefore, standardized such `Constraint`s with their `leftOperand`s and `rightOperand`s are key for From 8d2c9cf2c15d1c0609d0d434b7922d50aa4b9e19 Mon Sep 17 00:00:00 2001 From: arnoweiss Date: Wed, 15 May 2024 17:40:46 +0200 Subject: [PATCH 12/15] chore(conn): update copyright, add changelog section --- .../Connector Kit/Adoption View/adoption-view.md | 8 +++----- .../Adoption View/policies-in-catena.md | 2 +- .../Adoption View/working-with-policies.md | 5 +++-- .../Connector Kit/Development View/architecture.md | 5 +++-- .../Development View/specifications.md | 5 +++-- .../Connector Kit/Operation View/operation-view.md | 5 +++-- docs-kits/kits/Connector Kit/page_changelog.md | 14 ++++++++++++++ 7 files changed, 30 insertions(+), 14 deletions(-) diff --git a/docs-kits/kits/Connector Kit/Adoption View/adoption-view.md b/docs-kits/kits/Connector Kit/Adoption View/adoption-view.md index e0c64e23092..1dff3819c7e 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/adoption-view.md +++ b/docs-kits/kits/Connector Kit/Adoption View/adoption-view.md @@ -199,11 +199,9 @@ inherently asynchronous, so the `TransferProcess` objects are stored in a backin This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2023 sovity GmbH -- SPDX-FileCopyrightText: 2023 msg systems AG -- SPDX-FileCopyrightText: 2023 Mercedes-Benz Group AG -- SPDX-FileCopyrightText: 2023 Contributors of the Eclipse Foundation -- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) +- SPDX-FileCopyrightText: 2024 Contributors of the Eclipse Foundation +- Source + URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) [edc-url]: https://github.com/eclipse-edc/Connector diff --git a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md index 567183957ca..f4902759d41 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md +++ b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md @@ -248,6 +248,6 @@ property): This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2023 Contributors of the Eclipse Foundation +- SPDX-FileCopyrightText: 2024 Contributors of the Eclipse Foundation - Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md index 7afeda6d56b..65bad9916bc 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md +++ b/docs-kits/kits/Connector Kit/Adoption View/working-with-policies.md @@ -122,5 +122,6 @@ appropriate logic implemented to extract relevant information from the VP to sat This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2023 Contributors of the Eclipse Foundation -- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) +- SPDX-FileCopyrightText: 2024 Contributors of the Eclipse Foundation +- Source + URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs-kits/kits/Connector Kit/Development View/architecture.md b/docs-kits/kits/Connector Kit/Development View/architecture.md index c6d3b8ce7cd..9c5a06e2ba1 100644 --- a/docs-kits/kits/Connector Kit/Development View/architecture.md +++ b/docs-kits/kits/Connector Kit/Development View/architecture.md @@ -66,5 +66,6 @@ Contact with the Catena X Portal is necessary to register as a participant and o This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2023 Contributors of the Eclipse Foundation -- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) +- SPDX-FileCopyrightText: 2024 Contributors of the Eclipse Foundation +- Source + URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs-kits/kits/Connector Kit/Development View/specifications.md b/docs-kits/kits/Connector Kit/Development View/specifications.md index 9c8d490a236..71b3abe90e6 100644 --- a/docs-kits/kits/Connector Kit/Development View/specifications.md +++ b/docs-kits/kits/Connector Kit/Development View/specifications.md @@ -34,5 +34,6 @@ In particular, Framework Agreement CX-0018 describes the Eclipse Dataspace Conne This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2023 Contributors of the Eclipse Foundation -- Source URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) +- SPDX-FileCopyrightText: 2024 Contributors of the Eclipse Foundation +- Source + URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs-kits/kits/Connector Kit/Operation View/operation-view.md b/docs-kits/kits/Connector Kit/Operation View/operation-view.md index a5d255d122d..3b30eaef34a 100644 --- a/docs-kits/kits/Connector Kit/Operation View/operation-view.md +++ b/docs-kits/kits/Connector Kit/Operation View/operation-view.md @@ -45,5 +45,6 @@ Specific configuration details are described more closely in the This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). - SPDX-License-Identifier: CC-BY-4.0 -- SPDX-FileCopyrightText: 2023 Contributors of the Eclipse Foundation -- Source URL: [https://github.com/eclipse-tractusx/tractusx-edc](https://github.com/eclipse-tractusx/tractusx-edc) +- SPDX-FileCopyrightText: 2024 Contributors of the Eclipse Foundation +- Source + URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) diff --git a/docs-kits/kits/Connector Kit/page_changelog.md b/docs-kits/kits/Connector Kit/page_changelog.md index 79563940738..733e11a76fb 100644 --- a/docs-kits/kits/Connector Kit/page_changelog.md +++ b/docs-kits/kits/Connector Kit/page_changelog.md @@ -6,6 +6,11 @@ All notable changes to this Kit will be documented in this file. +## [2.1.0] - 2024-05-29 + +- Added new page on policies in general +- Added new page on policies in Catena-X + ## [2.0.0] - 2024-02-01 - Removed automatic pipeline from eclipse-tractusx/tracutsx-edc @@ -62,3 +67,12 @@ All notable changes to this Kit will be documented in this file.

Removed

- ./. + +## Notice + +This work is licensed under the [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/legalcode). + +- SPDX-License-Identifier: CC-BY-4.0 +- SPDX-FileCopyrightText: 2024 Contributors of the Eclipse Foundation +- Source + URL: [https://github.com/eclipse-tractusx/eclipse-tractusx.github.io](https://github.com/eclipse-tractusx/eclipse-tractusx.github.io) From 78a6208d9fae5793a092693fb5e7c1dc8852c708 Mon Sep 17 00:00:00 2001 From: arnoweiss Date: Wed, 15 May 2024 17:44:02 +0200 Subject: [PATCH 13/15] chore(conn): update link to standard-lib --- .../kits/Connector Kit/Adoption View/policies-in-catena.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md index f4902759d41..302bf04117a 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md +++ b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md @@ -49,8 +49,7 @@ Each Participant commits to a set of Use Case Frameworks during Onboarding. They that commitment. Consequently, Use Case Framework Constraints belong to the kind of `odrl:Constraint`s that have to be [checked against a VP](working-with-policies.md#provider-side-checking-a-consumers-verifiable-presentation). The complete set is listed in the most current version of standard -[CX-0050 Framework Credential](https://catena-x.net/fileadmin/user_upload/Standard-Bibliothek/Update_September23/CX-0050-FrameworkAgreementCredential-v.1.0.0.pdf) ( -link opens pdf). +[CX-0050 Framework Credential](https://catena-x.net/de/standard-library). Use Case Frameworks are referred to in a machine-readable way in a Provider's Offers. When a Consumer starts the negotiation for said offer, not only will the Policy in the `ContractRequestMessage` be checked but also his Credentials. Here's an example of an `odrl:Constraint` referencing a Use Case Framework and invoking the VC-check: From 8760d36fb04a1eb48ae6e005f0a3f3d1f5f23893 Mon Sep 17 00:00:00 2001 From: arnoweiss Date: Wed, 15 May 2024 18:20:28 +0200 Subject: [PATCH 14/15] chore(deps): DEPENDENCIES --- DEPENDENCIES | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/DEPENDENCIES b/DEPENDENCIES index 264f2084b19..04d344180a3 100644 --- a/DEPENDENCIES +++ b/DEPENDENCIES @@ -641,7 +641,7 @@ npm/npmjs/-/path-to-regexp/1.8.0, MIT, approved, clearlydefined npm/npmjs/-/path-to-regexp/2.2.1, MIT, approved, clearlydefined npm/npmjs/-/path-type/4.0.0, MIT, approved, clearlydefined npm/npmjs/-/path/0.12.7, MIT, approved, clearlydefined -npm/npmjs/-/picocolors/1.0.0, ISC, approved, clearlydefined +npm/npmjs/-/picocolors/1.0.0, ISC, approved, #14718 npm/npmjs/-/picomatch/2.3.1, MIT, approved, clearlydefined npm/npmjs/-/pirates/4.0.5, MIT, approved, #680 npm/npmjs/-/pkg-dir/4.2.0, MIT, approved, clearlydefined From 4944034b713db0df1fe60ee28b969d828f48b986 Mon Sep 17 00:00:00 2001 From: arnoweiss Date: Thu, 16 May 2024 08:36:04 +0200 Subject: [PATCH 15/15] chore(deps): empty commit --- .../kits/Connector Kit/Adoption View/policies-in-catena.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md index 302bf04117a..53b9cfa4768 100644 --- a/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md +++ b/docs-kits/kits/Connector Kit/Adoption View/policies-in-catena.md @@ -222,7 +222,7 @@ property): "dct:format": { "@id": "HttpData-PULL" }, - "dcat:accessService": "911f5da0-c9ee-4259-9a95-39428d08f767" + "dcat:accessService": "911f5da0-c9ee-4259-9a95-39428d08f777" } ], "version": 1.0, @@ -233,7 +233,7 @@ property): } ], "dcat:service": { - "@id": "911f5da0-c9ee-4259-9a95-39428d08f767", + "@id": "911f5da0-c9ee-4259-9a95-39428d08f777", "@type": "dcat:DataService", "dct:terms": "connector", "dct:endpointUrl": "https://provider-dsp-end.point/api/v1/dsp"