feat: Add explanations when to use odrl:target (#201)

* add explanations on usage of odrl:target * adjust schemas * adjust readmes for the catalog and negotiation sections * fix typos in catalog.md section 2.2.1 * add explanation for usage of target inside catalog/datasets * correct descriptions on targets inside catalogs
International-Data-Spaces-Association · Jan 25, 2024 · e464d64 · e464d64
1 parent 3a2f88b
commit e464d64
Show file tree

Hide file tree

Showing 7 changed files with 42 additions and 10 deletions.
diff --git a/catalog/catalog.protocol.md b/catalog/catalog.protocol.md
@@ -58,6 +58,10 @@ be defined in the relevant Catalog Binding Specification.
 
 The [Catalog](../model/terminology.md#catalog) contains all [Datasets](#31-dataset) which the requester shall see.
 
+#### 2.2.1 odrl:hasPolicy
+
+A [Catalog](../model/terminology.md#catalog) may have `hasPolicy` attributes that contain an [ODRL `Offer`](https://www.w3.org/TR/odrl-vocab/#term-Offer) defining the [Usage Policy](../model/terminology.md#policy) associated with the [Catalog](../model/terminology.md#catalog). Offers must NOT contain any
+explicit `target` attributes. The `target` of an [Offer](../model/terminology.md#offer) is the associated [Catalog](../model/terminology.md#catalog). This is in line with the semantics of `hasPolicy` as defined in the [ODRL Information Model](https://www.w3.org/TR/odrl-model/#policy-has), explaining that the subject (here the Catalog) is automatically the `target` of each Rule. To prevent conflicts, the `target` attribute must not be set explicitely, for example, in the Offer or Rules. 
 
 ### 2.3 CatalogError
 
@@ -119,9 +123,9 @@ A [Dataset](../model/terminology.md#dataset) is a [DCAT Dataset](https://www.w3.
 #### 3.1.1 odrl:hasPolicy
 
 A [Dataset](../model/terminology.md#dataset) must have 1..N `hasPolicy` attributes that contain an [ODRL `Offer`](https://www.w3.org/TR/odrl-vocab/#term-Offer) defining the [Usage Policy](../model/terminology.md#policy) associated with the [Dataset](../model/terminology.md#dataset). Offers must NOT contain any
-target attributes. The target of an [Offer](../model/terminology.md#offer) is the associated [Dataset](../model/terminology.md#dataset).
+explicit `target` attributes. The `target` of an [Offer](../model/terminology.md#offer) is the associated [Dataset](../model/terminology.md#dataset). This is in line with the semantics of `hasPolicy` as defined in the [ODRL Information Model](https://www.w3.org/TR/odrl-model/#policy-has), explaining that the subject (here the Dataset) is automatically the `target` of each Rule. To prevent conflicts, the `target` attribute must not be set explicitely, neither in the Offer itself or in its Rules. 
 
-> Note: As `odrl:hasPolicy rdfs:domain odrl:Asset`, each [Dataset](../model/terminology.md#dataset) is also an `odrl:Asset` from an ODRL perspective.
+> Note: As ODRL defines that `odrl:hasPolicy rdfs:domain odrl:Asset`, each [Dataset](../model/terminology.md#dataset) is also an `odrl:Asset` from an ODRL perspective.
 
 ### 3.2 Distributions
 

diff --git a/catalog/message/schema/catalog-schema.json b/catalog/message/schema/catalog-schema.json
@@ -174,7 +174,7 @@
                 "odrl:hasPolicy": {
                     "type": "array",
                     "items": {
-                        "$ref": "https://raw.githubusercontent.com/International-Data-Spaces-Association/ids-specification/dcat-catalog-schema-and-shape/negotiation/message/schema/contract-schema.json#/definitions/Policy"
+                        "$ref": "https://raw.githubusercontent.com/International-Data-Spaces-Association/ids-specification/dcat-catalog-schema-and-shape/negotiation/message/schema/contract-schema.json#/definitions/Offer"
                     },
                     "minItems": 1
                 }
@@ -263,7 +263,7 @@
                 "odrl:hasPolicy": {
                     "type": "array",
                     "items": {
-                        "$ref": "https://raw.githubusercontent.com/International-Data-Spaces-Association/ids-specification/dcat-catalog-schema-and-shape/negotiation/message/schema/contract-schema.json#/definitions/Policy"
+                        "$ref": "https://raw.githubusercontent.com/International-Data-Spaces-Association/ids-specification/dcat-catalog-schema-and-shape/negotiation/message/schema/contract-schema.json#/definitions/Offer"
                     },
                     "minItems": 1
                 }

diff --git a/model/model.md b/model/model.md
@@ -66,7 +66,7 @@ A [Dataset](./terminology.md#dataset) is a [DCAT Dataset](https://www.w3.org/TR/
 An [Offer](./terminology.md#offer) is an [ODRL Offer](https://www.w3.org/TR/odrl-model/#policy-offer) with the following attributes:
 
 - An ODRL `uid` is represented as an "@id" that is a unique UUID. (ODRL PROFILE)
-- A `target` attribute that is the dataset id. 
+- A `target` attribute that is the dataset id. Except if the Offer is used in an enclosing Catalog or Dataset, then the there must not be any `target` attribute set.
 
 ## 2.2.4 Agreement
 

diff --git a/negotiation/contract.negotiation.protocol.md b/negotiation/contract.negotiation.protocol.md
@@ -81,6 +81,8 @@ The `ContractRequestMessage` is sent by a consumer to initiate a [Contract Negot
 - `callbackAddress` is a URL indicating where messages to the consumer should be sent in asynchronous settings. If the address is not understood, the provider MUST return an
   UNRECOVERABLE error.
 
+- Different to a [Catalog](../catalog/catalog.protocol.md#221-odrlhaspolicy) or [Dataset](../catalog/catalog.protocol.md#311-odrlhaspolicy), the Offer inside a ContractRequestMessage must have an `odrl:target` attribute. However, it's contained Rules must not have any `odrl:target` attributes to prevent inconsistencies with the [ODRL inferencing rules for compact policies](https://www.w3.org/TR/odrl-model/#composition-compact).
+
 
 ### 2. ContractOfferMessage
 
@@ -102,9 +104,11 @@ The `ContractOfferMessage` is sent by a provider to initiate a [Contract Negotia
 
 ### Notes
 
-If the message includes a `consumerPid` property, the request will be associated with an existing [Contract Negotiation](../model/terminology.md#contract-negotiation). If the message does not include a `consumerPid`, a new [Contract Negotiation](../model/terminology.md#contract-negotiation)
+- If the message includes a `consumerPid` property, the request will be associated with an existing [Contract Negotiation](../model/terminology.md#contract-negotiation). If the message does not include a `consumerPid`, a new [Contract Negotiation](../model/terminology.md#contract-negotiation)
 will be created on consumer side and the consumer selects an appropriate `consumerPid`.
 
+- Different to a [Catalog](../catalog/catalog.protocol.md#221-odrlhaspolicy) or [Dataset](../catalog/catalog.protocol.md#311-odrlhaspolicy), the Offer inside a ContractOfferMessage must have an `odrl:target` attribute. However, it's contained Rules must not have any `odrl:target` attributes to prevent inconsistencies with the [ODRL inferencing rules for compact policies](https://www.w3.org/TR/odrl-model/#composition-compact).
+
 #### Notes
 
 - The [Dataset](../model/terminology.md#dataset) id is not required but can be included when the provider initiates a [Contract Negotiation](../model/terminology.md#contract-negotiation).
@@ -138,6 +142,9 @@ properties are a [Dataspace](../model/terminology.md#dataspace)-specific unique
 identifiers are not necessarily the same as the identifiers of the [Participant Agents](../model/terminology.md#participant-agent) negotiating the
 contract (i.e. the [Connectors](../model/terminology.md#connector--data-service-)).
 
+
+An [Agreement](../model/terminology.md#agreement) must contain a `odrl:target` property. None of its Rules, however, must have any `odrl:target` attributes to prevent inconsistencies with the [ODRL inferencing rules for compact policies](https://www.w3.org/TR/odrl-model/#composition-compact).
+
 ### 4. ContractAgreementVerificationMessage
 
 

diff --git a/negotiation/message/schema/contract-offer-message-schema.json b/negotiation/message/schema/contract-offer-message-schema.json
@@ -27,7 +27,7 @@
 					"type": "string"
 				},
 				"odrl:offer": {
-					"$ref": "https://w3id.org/dspace/schemas/v0.8/contract-schema.json#/definitions/Offer"
+					"$ref": "https://w3id.org/dspace/schemas/v0.8/contract-schema.json#/definitions/MessageOffer"
 				},
 				"dspace:callbackAddress": {
 					"type" : "string"

diff --git a/negotiation/message/schema/contract-request-message-schema.json b/negotiation/message/schema/contract-request-message-schema.json
@@ -27,7 +27,7 @@
 					"type": "string"
 				},
 				"odrl:offer": {
-					"$ref": "https://w3id.org/dspace/schemas/v0.8/contract-schema.json#/definitions/Offer"
+					"$ref": "https://w3id.org/dspace/schemas/v0.8/contract-schema.json#/definitions/MessageOffer"
 				},
 				"dspace:callbackAddress": {
 					"type" : "string"

diff --git a/negotiation/message/schema/contract-schema.json b/negotiation/message/schema/contract-schema.json
@@ -11,6 +11,9 @@
     "definitions": {
         "Policy": {
             "oneOf": [
+                {
+                    "$ref": "#/definitions/MessageOffer"
+                },
                 {
                     "$ref": "#/definitions/Offer"
                 },
@@ -65,9 +68,10 @@
                 "dspace:consumerId": {
                     "type": "string"
                 }
-            }
+            },
+            "not": { "required": [ "odrl:target" ] }
         },
-        "Offer": {
+        "MessageOffer": {
             "type": "object",
             "allOf": [
                 {
@@ -101,6 +105,15 @@
                 "dspace:providerId"
             ]
         },
+        "#/definitions/Offer": {
+            "type": "object",
+            "allOf": [
+                {
+                    "$ref": "#/definitions/MessageOffer"
+                }
+            ],
+            "not": { "required": [ "odrl:target" ] }
+        },
         "Agreement": {
             "type": "object",
             "allOf": [
@@ -113,6 +126,12 @@
                             "type": "string",
                             "const": "odrl:Agreement"
                         },
+                        "@id": {
+                            "type": "string"
+                        },
+                        "odrl:target": {
+                            "type": "string"
+                        },
                         "dspace:timestamp": {
                     "type": "string",
                     "pattern": "-?([1-9][0-9]{3,}|0[0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T(([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](\\.[0-9]+)?|(24:00:00(\\.0+)?))(Z|(\\+|-)((0[0-9]|1[0-3]):[0-5][0-9]|14:00))?" 
@@ -136,6 +155,8 @@
             ],
             "required": [
                 "@type",
+                "@id",
+                "@target",
                 "dspace:providerId",
                 "dspace:consumerId", 
                 "dspace:timestamp"