Skip to content

Commit

Permalink
feat: add message schemas and shapes (International-Data-Spaces-Assoc…
Browse files Browse the repository at this point in the history
…iation#3)

* feat: add message schemes for contract negotiation

* feat: add message schemes for cataloging

* feat: add message schemes for transfer process

* refactor: replace JSON schema keyword "pattern" with better fitting "const"

* fix: revert not discussed changes

* fix: resolve broken links and typos

* refactor: clean up file structure

* fix: broken link to the negotiation error diagram

---------

Co-authored-by: Julia Pampus <[email protected]>
  • Loading branch information
sebbader-sap and juliapampus authored Feb 22, 2023
1 parent 83ea179 commit 15be6d2
Show file tree
Hide file tree
Showing 117 changed files with 2,429 additions and 169 deletions.
74 changes: 37 additions & 37 deletions SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,46 +26,46 @@
* [README.md](./README.md)
* [SUMMARY.md](./SUMMARY.md)
* [Section 1 Terminology and Section 2 Concepts](./model/information.model.md)
* [Figure: Entities and Relationships in Data Space](./model/im.dataspace.relationships.png)
* [Figure (source): Entities and Relationships in Data Space](./model/im.dataspace.relationships.puml)
* [Figure: Entites and relationships to DCAT and ODRL](./model/im.participant.entities.png)
* [Figure (source): Entites and relationships to DCAT and ODRL](./model/im.participant.entities.drawio)
* [Figure: Entities and Relationships in Data Space](./model/m.dataspace.relationships.png)
* [Figure (source): Entities and Relationships in Data Space](./model/m.dataspace.relationships.puml)
* [Figure: Entities and relationships to DCAT and ODRL](./model/m.participant.entities.png)
* [Figure (source): Entities and relationships to DCAT and ODRL](./model/m.participant.entities.drawio)
* [Section 3 Catalog protocol](./catalog/catalog.protocol.md)
* [Catalog HTTPS Binding](./catalog/catalog.binding.https.md)
* [Example: DCAT Distribtion (json)](./catalog/example/dcat.distribution.example.json)
* [Example: DCAT Distribtion option 1 (json)](./catalog/example/dcat.distribution.example.option1.json)
* [Example: DCAT Distribtion option 2 (json)](./catalog/example/dcat.distribution.example.option2.json)
* [Catalog Error Message (json)](./catalog/message/catalog.error.message.json)
* [Catalog Message (json)](./catalog/message/catalog.message.json)
* [Catalog Request Message (json)](./catalog/message/catalog.request.message.json)
* [Example: DCAT Distribution (json)](./catalog/message/example/dcat.distribution.example.json)
* [Example: DCAT Distribution option 1 (json)](./catalog/message/example/dcat.distribution.example.option1.json)
* [Example: DCAT Distribution option 2 (json)](./catalog/message/example/dcat.distribution.example.option2.json)
* [Catalog Error Message (json)](./catalog/message/catalog-error-message.json)
* [Catalog Message (json)](./catalog/message/catalog.json)
* [Catalog Request Message (json)](./catalog/message/catalog-request-message.json)
* [Section 4 Contract Negotiation](./negotiation/contract.negotiation.protocol.md)
* [Contract Negotiaton HTTPS Binding](./negotiation/contract.negotiation.binding.https.md)
* [Figure: Contract Negotation State Machine](./negotiation/contract.negotiation.state.machine.png)
* [Figure (Source): Contract Negotation State Machine](./negotiation/contract.negotiation.state.machine.puml)
* [Contract Agreement Message (json)](./negotiation/message/contract.agreement.message.json)
* [Contract Agreement Verification Message (json)](./negotiation/message/contract.agreement.verification.message.json)
* [Contract Negotiation Error Message (json)](./negotiation/message/contract.negotiation.error.json)
* [Contract Negotiation Event Message (json)](./negotiation/message/contract.negotiation.event.message.json)
* [Contract Negotation Message (json)](./negotiation/message/contract.negotiation.json)
* [Contract Negotiation Termination Message (json)](./negotiation/message/contract.negotiation.termination.message.json)
* [Contract Offer Message (json)](./negotiation/message/contract.offer.message.json)
* [Contract Request Message (json)](./negotiation/message/contract.request.message.json)
* [Contract Negotiation HTTPS Binding](./negotiation/contract.negotiation.binding.https.md)
* [Figure: Contract Negotiation State Machine](./negotiation/contract.negotiation.state.machine.png)
* [Figure (Source): Contract Negotiation State Machine](./negotiation/contract.negotiation.state.machine.puml)
* [Contract Agreement Message (json)](./negotiation/message/contract-agreement-message.json)
* [Contract Agreement Verification Message (json)](./negotiation/message/contract-agreement-verification-message.json)
* [Contract Negotiation Error Message (json)](./negotiation/message/contract-negotiation.json)
* [Contract Negotiation Event Message (json)](./negotiation/message/contract-negotiation-event-message.json)
* [Contract Negotiation Message (json)](./negotiation/message/contract-negotiation.json)
* [Contract Negotiation Termination Message (json)](./negotiation/message/contract-negotiation-termination-message.json)
* [Contract Offer Message (json)](./negotiation/message/contract-offer-message.json)
* [Contract Request Message (json)](./negotiation/message/contract-request-message.json)
* [Example: Contract Agreement Message HTTP](./negotiation/message/example/contract.agreement.message.http.transfer.json)
* [Section 5 Transfer process](./transfer/transfer.process.protocol.md)
* [Transfer process HTTPS Binding](./transfer/transfer.process.binding.https.md)
* [Figure: Transfer Process State Machine](./transfer/transfer.process.state.machine.png)
* [Figure (source): Transfer Process State Machine](./transfer/transfer.process.state.machine.puml)
* [Transfer Completition Message (json)](./transfer/message/transfer.completion.message.json)
* [Transfer Error Message (json)](./transfer/message/transfer.error.json)
* [Transfer Process Message (json)](./transfer/message/transfer.process.json)
* [Transfer Request Message (json)](./transfer/message/transfer.request.message.json)
* [Transfer Start Message (json)](./transfer/message/transfer.start.message.json)
* [Transfer Suspension Message (json)](./transfer/message/transfer.suspension.message.json)
* [Transfer Termination Message (json)](./transfer/message/transfer.termination.message.json)
* [Common Schema (json)](./common/definitions.schema.json)
* [Shape: Contract Agreement Message (ttl)](./schemas/contract-agreement-message-shape.ttl)
* [Shape: Contract Agreement Verification message (ttl)](./schemas/contract-agreement-verification-message-shape.ttl)
* [Shape: Contract Negotation Event Message (ttl)](./schemas/contract-negotiation-event-message-shape.ttl)
* [Shape: Contract Negotation Termination Message (ttl)](./schemas/contract-negotiation-termination-message-shape.ttl)
* [Shape: Contract Request Message (ttl)](./schemas/contract-request-message-shape.ttl)
* [diagram.styles.puml](./diagrams/diagram.styles.puml)
* [Figure: Transfer Process State Machine](./transfer/transfer-process-state-machine.png)
* [Figure (source): Transfer Process State Machine](./transfer/transfer-process-state-machine.puml)
* [Transfer Completion Message (json)](./transfer/message/transfer-completion-message.json)
* [Transfer Error Message (json)](./transfer/message/transfer-error.json)
* [Transfer Process Message (json)](./transfer/message/transfer-process.json)
* [Transfer Request Message (json)](./transfer/message/transfer-request-message.json)
* [Transfer Start Message (json)](./transfer/message/transfer-start-message.json)
* [Transfer Suspension Message (json)](./transfer/message/transfer-suspension-message.json)
* [Transfer Termination Message (json)](./transfer/message/transfer-termination-message.json)
* [Common Schema (json)](./common/schema/definitions.schema.json)
* [Shape: Contract Agreement Message (ttl)](./negotiation/message/shape/contract-agreement-message-shape.ttl)
* [Shape: Contract Agreement Verification message (ttl)](./negotiation/message/shape/contract-agreement-verification-message-shape.ttl)
* [Shape: Contract Negotiation Event Message (ttl)](./negotiation/message/shape/contract-negotiation-event-message-shape.ttl)
* [Shape: Contract Negotiation Termination Message (ttl)](./negotiation/message/shape/contract-negotiation-termination-message-shape.ttl)
* [Shape: Contract Request Message (ttl)](./negotiation/message/shape/contract-request-message-shape.ttl)
* [diagram.styles.puml](./common/style/diagram.styles.puml)
2 changes: 1 addition & 1 deletion catalog/catalog.binding.https.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ request.

#### 2.3.2 OK (200) Response

If the request is successful, the catalog service must return a response body containing a [CatalogMessage](./message/catalog.message.json) which is a profiled DCAT Catalog type
If the request is successful, the catalog service must return a response body containing a [Catalog](./message/catalog.json) which is a profiled DCAT Catalog type
described by the [Catalog Protocol Specification](catalog.protocol.md).

## 3 Technical Considerations
Expand Down
57 changes: 44 additions & 13 deletions catalog/catalog.protocol.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,32 +20,63 @@ Future IDS specifications may define additional optional serialization formats.

### 2.1 CatalogRequestMessage

**Sent by**: Consumer
![](./message/diagram/catalog-request-message.png)

**Example**:
**Sent by**: Consumer

```
{
"@context": "https://w3id.org/idsa/v5/context.json",
"@type": "ids:CatalogRequest"
"ids:filter": {}
}
```
**Example**: [CatalogRequestMessage](./message/catalog-request-message.json)

**Response**: [CatalogMessage](./message/catalog.message.json) containing the [DCAT catalog](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog).
**Response**: [Catalog](#22-catalog) containing the [DCAT catalog](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog).

**Schema**: (xx)[]
**Schema**: [CatalogRequestMessageShape](./message/shape/catalog-request-message-shape.ttl) and the [CatalogRequestMessage JSON Schema](./message/schema/catalog-request-message-schema.json)

#### Description

The `CatalogRequestMessage` is message sent by a consumer to a catalog service. The catalog service must respond with a `CatalogMessage,` which is a
valid [DCAT Catalog](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog).
The `CatalogRequestMessage` is message sent by a consumer to a catalog service. The catalog service must respond with a `Catalog,` which is a
valid instance of a [DCAT Catalog](https://www.w3.org/TR/vocab-dcat-3/#Class:Catalog).

The `CatalogRequestMessage` may have a `filter` property which contains an implementation-specific query or filter expression type supported by the catalog service.

The catalog service may require an authorization token. Details for including that token can be found in the relevant catalog binding specification. Similarly, pagination may
be defined in the relevant catalog binding specification.


### 2.2 Catalog

![](./message/diagram/catalog.png)

**Sent by**: Provider

**Example**: [Catalog](./message/catalog.json)


**Response**: OK or ERROR

**Schema**: [CatalogShape](./message/shape/catalog-shape.ttl) and the [Catalog JSON Schema](./message/schema/catalog-schema.json)

#### Description

The catalog contains all [Asset Entries](#31-asset-entry) which the requester shall see.


### 2.3 Catalog Error Message

![](./message/diagram/catalog-error-message.png)

**Sent by**: Consumer or Provider

**Example**: [CatalogErrorMessage](./message/catalog-error-message.json)

**Response**: OK or ERROR

**Schema**: [CatalogErrorMessageShape](./message/shape/catalog-error-message-shape.ttl) and the [CatalogErrorMessage JSON Schema](./message/schema/catalog-error-message-schema.json)

#### Description

A Catalog Error Message is used when an error occured after a CatalogRequestMessage and the provider can not provide its catalog to the requester.



## 3 DCAT Vocabulary Mapping

This section describes how the IDS Information Model maps to DCAT resources.
Expand Down
9 changes: 9 additions & 0 deletions catalog/message/catalog-error-message.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"@context": "https://w3id.org/idsa/v5/context.json",
"@type": "ids:CatalogErrorMessage",
"ids:code": "123:A",
"ids:reason": [
{ "@value": "Catalog not provisioned for this requester.", "@language": "en" },
{ "some": "other reason"}
]
}
9 changes: 0 additions & 9 deletions catalog/message/catalog.error.message.json

This file was deleted.

File renamed without changes.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
16 changes: 16 additions & 0 deletions catalog/message/diagram/catalog-error-message.puml
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
@startuml "catalog-error-message"
!pragma layout smetana

!include ../../../common/style/diagram.styles.puml

hide empty description


class "ids:CatalogErrorMessage" {
@context : "https://w3id.org/idsa/v5/context.json"
@type : "ids:CatalogErrorMessage"
ids:code : String
ids:reason : Array
}

@enduml
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
15 changes: 15 additions & 0 deletions catalog/message/diagram/catalog-request-message.puml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
@startuml "catalog-request-message"
!pragma layout smetana

!include ../../../common/style/diagram.styles.puml

hide empty description


class "ids:CatalogRequestMessage" {
@context : "https://w3id.org/idsa/v5/context.json"
@type : ids:CatalogRequestMessage
ids:filter : Object
}

@enduml
Binary file added catalog/message/diagram/catalog.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
14 changes: 14 additions & 0 deletions catalog/message/diagram/catalog.puml
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
@startuml "catalog"
!pragma layout smetana

!include ../../../common/style/diagram.styles.puml

hide empty description


class dcat:Catalog {
@type : "dcat:Catalog",
...
}

@enduml
28 changes: 28 additions & 0 deletions catalog/message/schema/catalog-error-message-schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"title": "CatalogErrorMessageSchema",
"type": "object",
"allOf": [
{
"$ref": "#/definitions/CatalogErrorMessage"
}
],
"$id": "https://w3id.org/idsa/schemas/v5/CatalogErrorMessageSchema",
"definitions": {
"CatalogErrorMessage": {
"type": "object",
"properties": {
"@context": {
"type": "string",
"const": "https://w3id.org/idsa/v5/context.json",
"required": true
},
"@type": {
"type": "string",
"const": "ids:CatalogErrorMessage",
"required": true
}
}
}
}
}
34 changes: 34 additions & 0 deletions catalog/message/schema/catalog-message-schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"title": "CatalogMessageSchema",
"type": "object",
"allOf": [
{
"$ref": "#/definitions/CatalogMessage"
}
],
"$id": "https://w3id.org/idsa/schemas/v5/CatalogMessageSchema",
"definitions": {
"CatalogMessage": {
"type": "object",
"properties": {
"@context": {
"type": "string",
"const": "https://w3id.org/idsa/v5/context.json",
"required": true
},
"@type": {
"type": "string",
"const": "ids:CatalogMessage",
"required": true
},
"ids:catalog": {
"type": "array",
"items": {
"$ref": "https://w3id.org/idsa/schemas/v5/CatalogSchema#definitions/Catalog"
}
}
}
}
}
}
35 changes: 35 additions & 0 deletions catalog/message/schema/catalog-request-message-schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"title": "CatalogRequestMessageSchema",
"type": "object",
"allOf": [
{
"$ref": "#/definitions/CatalogRequestMessage"
}
],
"$id": "https://w3id.org/idsa/schemas/v5/CatalogRequestMessageSchema",
"definitions": {
"CatalogRequestMessage": {
"type": "object",
"properties": {
"@context": {
"type": "string",
"const": "https://w3id.org/idsa/v5/context.json",
"required": true
},
"@type": {
"type": "string",
"const": "ids:CatalogRequestMessage",
"required": true
},
"ids:filter": {
"type": "array",
"items": {
"@type": "string",
"const": "ids:Filter"
}
}
}
}
}
}
39 changes: 39 additions & 0 deletions catalog/message/schema/catalog-schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"title": "CatalogSchema",
"type": "object",
"allOf": [
{
"$ref": "#/definitions/Catalog"
}
],
"$id": "https://w3id.org/idsa/schemas/v5/CatalogSchema",
"definitions": {
"Catalog": {
"type": "object",
"properties": {
"@context": {
"type": "string",
"const": "https://w3id.org/idsa/v5/context.json",
"required": true
},
"@type": {
"type": "string",
"const": "dcat:Catalog",
"required": true
},
"dcat:dataset": {
"type": "array",
"items": {
"@type": {
"type": "string",
"const": "dcat:Dataset"
}
},
"minItems": 1,
"required": false
}
}
}
}
}
Loading

0 comments on commit 15be6d2

Please sign in to comment.