Skip to content

catalog.protocol.md

Latest commit

 

History

History
161 lines (116 loc) · 10 KB

catalog.protocol.md

File metadata and controls

161 lines (116 loc) · 10 KB

Catalog Protocol {#catalog-protocol}

Introduction

The [=Catalog Protocol=] defines how a [=Catalog=] is requested from a [=Catalog Service=] by a [=Consumer=] using an abstract Message exchange format. The concrete Message exchange wire format is defined in the binding.

The [=Catalog Protocol=] reuses properties from the DCAT and ODRL vocabularies with restrictions defined in this specification. This is done implicitly by the use of the JSON schemas and JSON-LD-contexts that are part of the [=Dataspace Protocol=]. Servers MAY process properties that are not part of the schemas.

Message Types

Catalog Request Message
Sent by [=Consumer=]
Resulting state TERMINATED
Response ACK or ERROR
Schema JSON Schema
Example Message
Properties

The Catalog Request Message is sent by a [=Consumer=] to a [=Catalog Service=]. The [=Catalog Service=] MUST respond with a Catalog that adheres to the schema linked above.

  • The message 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 protocol binding, e.g., Catalog HTTPS Binding. Similarly, pagination MAY be defined in the protocol binding.

Dataset Request Message
Sent by [=Consumer=]
Resulting state TERMINATED
Response ACK or ERROR
Schema JSON Schema
Example Message
Properties

The Dataset Request Message is sent by a [=Consumer=] to a [=Catalog Service=]. The [=Catalog Service=] MUST respond with a Dataset that adheres to the schema linked above.

  • The message MUST have a dataset property which contains the identifier of the [=Dataset=].

  • The [=Catalog Service=] MAY require an authorization token. Details for including that token can be found in the protocol binding, e.g., Catalog HTTPS Binding.

Response Types

The ACK and ERROR response types are mapped onto a protocol such as HTTPS. A description of an error MAY be provided in protocol-dependent forms, e.g., for an HTTPS binding in the request or response body.

ACK - Catalog
Sent by [=Provider=]
Schema JSON Schema
Example Catalog Example
Properties

  • A [=Catalog=] MUST have zero to many [=Datasets=]. (NOTE: Since a Catalog MAY be dynamically generated for a request based on the requesting [=Participant=]'s credentials, it is possible for it to contain 0 matching [=Datasets=].)

  • A [=Catalog=] MUST have one to many [=Data Services=] that reference a [=Connector=] where [=Datasets=] MAY be obtained.

ACK - Dataset
Sent by [=Provider=]
Schema JSON Schema
Example Dataset Example
Properties

  • A [=Dataset=] MUST have at least one hasPolicy attribute that contains an [=Offer=] defining the [=Policy=] associated with the [=Dataset=].

  • A [=Dataset=] MUST hold at least one Distribution object in the distribution attribute.

  • Each DataService object MUST have at least one DataService which specifies where the distribution is obtained. Specifically, a DataService specifies the endpoint for initiating a [=Contract Negotiation=] and [=Transfer Process=].

  • A DataService.endpointURL property contains the URL of the service the [=Contract Negotiation=] endpoints extend. The endpoint's [=Dataspace Protocol=] version MUST be consistent with the version the Catalog object was served through.

An [=Offer=] contains the following attributes:

  • An [=Offer=] MUST have an @id that is a unique identifier.

  • An [=Offer=] MUST be unique to a [=Dataset=] since the target of the [=Offer=] is derived from its enclosing context.

  • [=Offers=] MAY contain any target attributes. The value of the target attribute MUST be the [=Dataset=] identifier. (NOTE: If the [=Offer=] is used in an enclosing [=Catalog=] or [=Dataset=], there MUST NOT be any target attribute set.)

ERROR - Catalog Error
Sent by [=Consumer=], [=Provider=]
Schema JSON Schema
Example Error
Properties

A Catalog Error is used when an error occurred after a Catalog Request Message or a Dataset Request Message and the [=Provider=] cannot provide its [=Catalog=] to the requester.

Technical Considerations

Queries and Filter Expressions

A [=Catalog Service=] MAY support [=Catalog=] queries or filter expressions as an implementation-specific feature. However, query capabilities by the [=Consumer=] MUST be implemented against the results of a Catalog Request Message. Client-side querying can be scaled by periodically crawling the [=Provider=]'s [=Catalog Services=], caching the results, and executing queries against the locally-stored [=Catalogs=].

Replication Protocol

The [=Catalog Protocol=] is designed to be used by federated services without the need for a replication protocol. Each [=Consumer=] is responsible for issuing requests to 1..N [=Catalog Services=], and managing the results. It follows that a specific replication protocol is not needed, or more precisely, each [=Consumer=] replicates data from [=Catalog Services=] by issuing Catalog Request Messages.

The discovery protocol adopted by a particular [=Dataspace=] defines how a [=Consumer=] discovers [=Catalog Services=].

Security

[=Catalog Services=] SHOULD implement access control. A [=Catalog=] as well as individual [=Datasets=] MAY be restricted to trusted parties. Therefore, the [=Catalog Service=] MAY require [=Consumers=] to include a security token along with a Catalog Request Message. The specifics of how this is done can be found in the relevant protocol binding, e.g., Catalog HTTPS Binding. The semantics of such tokens are not part of this specification.

The Proof Metadata Endpoint

If a [=Catalog=] contains protected [=Datasets=], the [=Provider=] has two options: include all [=Datasets=] in the [=Catalog=] response and restrict access when a [=Policy=] is negotiated; or, require one or more proofs when the Catalog Request is made and filter the [=Datasets=] accordingly. The latter option requires a mechanism for clients to discover the type of proofs that MAY be presented at request time. The specifics of proof types and presenting a proof during a [=Catalog=] request is outside the scope of the [=Dataspace Protocol=]. However, [=Catalog Protocol=] bindings SHOULD define a proof data endpoint for obtaining this information.

Catalog Brokers

A [=Dataspace=] MAY include Catalog Brokers. A Catalog Broker is a [=Consumer=] that has trusted access to 1..N upstream [=Catalog Services=] and advertises their respective [=Catalogs=] as a single [=Catalog Service=]. The Catalog Broker SHOULD honor upstream access control requirements ([=Policies=]).