Skip to content

feat: make versioning optional #165

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

feat: make versioning optional #165

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,9 @@ <h1 id="title">Dataspace Protocol 2025-1-RC2</h1>
<section data-include="specifications/transfer/transfer.process.binding.https.md" data-include-format="markdown">
</section>

<section data-include="specifications/common/versioning.md" data-include-format="markdown">
</section>

<section id='conformance'></section>

<section id="lower-level-types" class="appendix" data-include="specifications/common/type.definitions.md" data-include-format="markdown">
Expand Down
34 changes: 1 addition & 33 deletions specifications/common/common.protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,36 +13,4 @@ provides a JSON-LD context to serialize data structures and [=Message=] types as
JSON-LD context is designed to produce [=Message=] serializations using compaction that validate against the Json Schema
for the given [=Message=] type. This allows implementations to choose whether to process [=Messages=] as plain JSON or
as JSON-LD and maintain interoperability between those approaches. Extensions that use JSON-LD are encouraged to provide
similar contexts that facilitate this approach to interoperability.

## Exposure of Versions {#exposure-of-dataspace-protocol-versions}

[=Connectors=] implementing the [=Dataspace Protocol=] may operate on different versions and bindings. Therefore, it is
necessary that they can discover such information reliably and unambiguously. Each [=Connector=]
must provide the version metadata endpoint using the `dspace-version` Well-Known Uniform Resource Identifier [[rfc8615]]
at the top of the path hierarchy. Example: `<host>/.well-known/dspace-version`

A [=Connector=] must respond to a respective HTTPS request by returning a [`VersionResponse`](#VersionResponse-table)
with at least one item. The item connects the version tag (`version` attribute) with a path to the endpoint.
The semantics of the `path` property are specified by each protocol binding.

This data object must comply to the [JSON Schema](message/schema/protocol-version-schema.json). The requesting
[=Connector=] may select from the endpoints in the response. If the [=Connector=] can't identify a matching Dataspace
Protocol version, it must terminate the communication. The version endpoint MUST be unversioned and unauthenticated.

### HTTPS Binding

When using the DSP HTTPS binding, the `path` property is an absolute URL path segment to be appended to the domain for
all endpoints of this version.

The following example demonstrates that a [=Connector=] offers the HTTPS binding from version `2024-1` at
`<host>/some/path/2024-1`, the `2025-1` endpoints at`<host>/some/path/2025-1` and another [=Connector=] on the same host
under `<host>/different/path/2025-1` - some of which signal the relevant authentication protocol overlay, determined by
`protocol`, `version` and the `profile` array.

<aside class="example" title="well-known version endpoint (HTTPS)">
<pre class="http">GET https://provider.com/.well-known/dspace-version
</pre>
<pre class="json" data-include="message/example/protocol-version.json">
</pre>
</aside>
similar contexts that facilitate this approach to interoperability.
27 changes: 27 additions & 0 deletions specifications/common/versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Exposure of Versions {#exposure-of-dataspace-protocol-versions}

The adoption of versioning to implementations that comply with this specification is optional.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The adoption of versioning to implementations that comply with this specification is optional.
Implementations may choose to support the discovery of versioning metadata. If version metadata is supported, an implementation must comply with the normative statements in this section.


## Introduction

[=Connectors=] implementing the [=Dataspace Protocol=] may operate on different versions and bindings. Such information should be discoverable reliably and unambiguously. If a [=Dataspace=] requires [=Connectors=] to expose supported versions, each [=Connector=] _MUST_ provide the version metadata endpoint using the `dspace-version` Well-Known Uniform Resource Identifier [[rfc8615]] at the top of the path hierarchy. Example: `<host>/.well-known/dspace-version`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[=Connectors=] implementing the [=Dataspace Protocol=] may operate on different versions and bindings. Such information should be discoverable reliably and unambiguously. If a [=Dataspace=] requires [=Connectors=] to expose supported versions, each [=Connector=] _MUST_ provide the version metadata endpoint using the `dspace-version` Well-Known Uniform Resource Identifier [[rfc8615]] at the top of the path hierarchy. Example: `<host>/.well-known/dspace-version`
[=Connectors=] implementing the [=Dataspace Protocol=] may support different versions and bindings. Such information should be discoverable reliably and unambiguously. If a [=Dataspace=] requires [=Connectors=] to expose supported versions, each [=Connector=] must provide the version metadata endpoint using the `dspace-version` Well-Known Uniform Resource Identifier [[rfc8615]] at the top of the path hierarchy. For example: `<host>/.well-known/dspace-version`


A [=Connector=] _MUST_ respond to a respective HTTPS request by returning a [`VersionResponse`](#VersionResponse-table)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A [=Connector=] _MUST_ respond to a respective HTTPS request by returning a [`VersionResponse`](#VersionResponse-table)
A [=Connector=] must respond to the HTTPS request by returning a [`VersionResponse`](#VersionResponse-table)

with at least one item. The item connects the version tag (`version` attribute) with a path to the endpoint.
The semantics of the `path` property are specified by each protocol binding.

This data object _MUST_ comply to the [JSON Schema](message/schema/protocol-version-schema.json). The requesting [=Connector=] _MAY_ select from the endpoints in the response. If the [=Connector=] cannot identify a matching [=Dataspace Protocol=] version, it _MUST_ terminate the communication. The version endpoint _MUST_ be unversioned and unauthenticated.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This data object _MUST_ comply to the [JSON Schema](message/schema/protocol-version-schema.json). The requesting [=Connector=] _MAY_ select from the endpoints in the response. If the [=Connector=] cannot identify a matching [=Dataspace Protocol=] version, it _MUST_ terminate the communication. The version endpoint _MUST_ be unversioned and unauthenticated.
This data object must comply with the [JSON Schema](message/schema/protocol-version-schema.json). The requesting [=Connector=] may select from the endpoints in the response. If the [=Connector=] cannot identify a matching [=Dataspace Protocol=] version, it must terminate the communication. The version endpoint must be unversioned and unauthenticated.


## HTTPS Binding

When using the DSP HTTPS binding, the `path` property is an absolute URL path segment to be appended to the domain for all endpoints of this version.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When using the DSP HTTPS binding, the `path` property is an absolute URL path segment to be appended to the domain for all endpoints of this version.
When using the DSP HTTPS binding, the `path` property is a URL path segment to be appended to the domain for all endpoints of this version.


Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is confusing. I think it woul be easier to read if it was in bullet form. For example:

The following example demonstrates a Connector that:

  • Offers the HTTPS binding supporting version 2024-1 at...
  • Offers the HTTPS binding supporting version 2025-1 at...
  • .... etc

The following example demonstrates that a [=Connector=] offers the HTTPS binding from version `2024-1` at
`<host>/some/path/2024-1`, the `2025-1` endpoints at`<host>/some/path/2025-1` and another [=Connector=] on the same host under `<host>/different/path/2025-1` - some of which signal the relevant authentication protocol overlay, determined by `protocol`, `version`, and the `profile` array.

<aside class="example" title="well-known version endpoint (HTTPS)">
<pre class="http">GET https://provider.com/.well-known/dspace-version
</pre>
<pre class="json" data-include="message/example/protocol-version.json">
</pre>
</aside>
Loading