Skip to content

Commit 1694012

Browse files
arnoweissarnoweiss
authored
feat: upgrade version endpoint (#138)
feat: add auth and binding to version endpoint
1 parent c8ff8c2 commit 1694012

File tree

5 files changed

+194
-79
lines changed

5 files changed

+194
-79
lines changed

‎artifacts/src/main/resources/common/example/protocol-version.json

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,34 @@
11
{
22
"protocolVersions": [
33
{
4-
"version": "1.0",
5-
"path": "/some/path/v1"
4+
"version": "2025-1",
5+
"path": "/some/path/2025-1",
6+
"binding": "HTTPS"
7+
},
8+
{
9+
"version": "2024-1",
10+
"path": "/some/path/2024-1",
11+
"binding": "HTTPS",
12+
"auth": {
13+
"protocol": "OAuth",
14+
"version": "2",
15+
"profile": [
16+
"authorization_code",
17+
"refresh_token"
18+
]
19+
}
20+
},
21+
{
22+
"version": "2025-1",
23+
"path": "/different/path/2025-1",
24+
"binding": "HTTPS",
25+
"auth": {
26+
"protocol": "DCP",
27+
"version": "1.0",
28+
"profile": [
29+
"vc11-sl2021/jwt"
30+
]
31+
}
632
}
733
]
8-
}
34+
}

‎artifacts/src/main/resources/common/protocol-version-schema.json

Lines changed: 66 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,72 @@
11
{
2-
"$schema": "https://json-schema.org/draft/2019-09/schema",
3-
"title": "VersionSchema",
4-
"type": "object",
5-
"allOf": [
6-
{
2+
"$schema": "https://json-schema.org/draft/2019-09/schema",
3+
"title": "VersionSchema",
4+
"type": "object",
5+
"allOf": [
6+
{
7+
"$ref": "#/definitions/Version"
8+
}
9+
],
10+
"$id": "https://w3id.org/dspace/2025/1/common/protocol-version-schema.json",
11+
"definitions": {
12+
"VersionResponse": {
13+
"type": "object",
14+
"properties": {
15+
"protocolVersions": {
16+
"type": "array",
17+
"items": {
718
"$ref": "#/definitions/Version"
19+
},
20+
"minItems": 1
21+
}
22+
},
23+
"required": [
24+
"protocolVersions"
25+
]
26+
},
27+
"Version": {
28+
"type": "object",
29+
"properties": {
30+
"version": {
31+
"type": "string"
32+
},
33+
"path": {
34+
"type": "string"
35+
},
36+
"binding": {
37+
"type": "string",
38+
"enum": [
39+
"HTTPS"
40+
]
41+
},
42+
"auth": {
43+
"$ref": "#/definitions/Auth"
844
}
9-
],
10-
"$id": "https://w3id.org/dspace/2025/1/common/protocol-version-schema.json",
11-
"definitions": {
12-
"Version": {
13-
"type": "object",
14-
"properties": {
15-
"protocolVersions": {
16-
"type": "array",
17-
"items": {
18-
"type": "object",
19-
"properties": {
20-
"version": {
21-
"type": "string"
22-
},
23-
"path": {
24-
"type": "string"
25-
}
26-
},
27-
"required": ["version", "path"]
28-
},
29-
"minItems": 1
30-
}
31-
},
32-
"required": ["protocolVersions"]
45+
},
46+
"required": [
47+
"version",
48+
"path",
49+
"binding"
50+
]
51+
},
52+
"Auth": {
53+
"type": "object",
54+
"properties": {
55+
"protocol": {
56+
"type": "string"
57+
},
58+
"version": {
59+
"type": "string"
60+
},
61+
"profile": {
62+
"type": "array",
63+
"items": "string"
3364
}
65+
},
66+
"required": [
67+
"protocol",
68+
"version"
69+
]
3470
}
71+
}
3572
}

‎artifacts/src/test/java/org/eclipse/dsp/schema/common/InvalidVersionSchemaTest.java

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,11 @@ void verifyInvalidCases() throws IOException {
3131
assertThat(schema.validate(INVALID_EMPTY_VERSIONS, JSON).iterator().next().getType()).isEqualTo(MIN_ITEMS);
3232
assertThat(schema.validate(INVALID_NO_VERSION, JSON).iterator().next().getType()).isEqualTo(REQUIRED);
3333
assertThat(schema.validate(INVALID_NO_PATH, JSON).iterator().next().getType()).isEqualTo(REQUIRED);
34+
assertThat(schema.validate(INVALID_NO_BINDING, JSON).iterator().next().getType()).isEqualTo(REQUIRED);
35+
assertThat(schema.validate(INVALID_BINDING_NOT_IN_ENUM, JSON).iterator().next().getType()).isEqualTo(ENUM);
36+
assertThat(schema.validate(INVALID_AUTH_A_STRING, JSON).iterator().next().getType()).isEqualTo(TYPE);
37+
assertThat(schema.validate(INVALID_AUTH_MISSING_PROTOCOL, JSON).iterator().next().getType()).isEqualTo(REQUIRED);
38+
assertThat(schema.validate(INVALID_AUTH_NOT_AN_ARRAY, JSON).iterator().next().getType()).isEqualTo(TYPE);
3439
}
3540

3641
@BeforeEach
@@ -67,4 +72,72 @@ void setUp() {
6772
]
6873
}
6974
""";
75+
76+
private static final String INVALID_NO_BINDING = """
77+
{
78+
"protocolVersions": [
79+
{
80+
"version": "1.0",
81+
"path": "some/path/v1"
82+
}
83+
]
84+
}
85+
""";
86+
87+
private static final String INVALID_BINDING_NOT_IN_ENUM = """
88+
{
89+
"protocolVersions": [
90+
{
91+
"version": "1.0",
92+
"path": "mqtts://mycorp.com/some/path/v1",
93+
"binding": "MQTT",
94+
"auth": "auth-protocol"
95+
}
96+
]
97+
}
98+
""";
99+
100+
private static final String INVALID_AUTH_A_STRING = """
101+
{
102+
"protocolVersions": [
103+
{
104+
"version": "1.0",
105+
"path": "/some/path/v1",
106+
"binding": "HTTPS",
107+
"auth": "auth-protocol"
108+
}
109+
]
110+
}
111+
""";
112+
113+
private static final String INVALID_AUTH_MISSING_PROTOCOL = """
114+
{
115+
"protocolVersions": [
116+
{
117+
"version": "1.0",
118+
"path": "/some/path/v1",
119+
"binding": "HTTPS",
120+
"auth": {
121+
"version": "a.b.c",
122+
"profile": ["someprofile"]
123+
}
124+
}
125+
]
126+
}
127+
""";
128+
private static final String INVALID_AUTH_NOT_AN_ARRAY = """
129+
{
130+
"protocolVersions": [
131+
{
132+
"version": "1.0",
133+
"path": "/some/path/v1",
134+
"binding": "HTTPS",
135+
"auth": {
136+
"version": "a.b.c",
137+
"profile": "someprofile"
138+
}
139+
}
140+
]
141+
}
142+
""";
70143
}

‎specifications/common/common.protocol.md

Lines changed: 20 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -17,52 +17,32 @@ similar contexts that facilitate this approach to interoperability.
1717

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

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

22-
[=Connectors=] implementing the [=Dataspace Protocol=] may operate on different versions. Therefore, it is necessary
23-
that they can discover the supported versions of each other reliably and unambiguously. Each [=Connector=] must expose
24-
information of at least one Dataspace Protocol version it supports. The specifics of how this information is obtained
25-
its defined by specific protocol bindings.
26-
27-
A [=Connector=] must respond to a respective request by providing a JSON object containing an array of supported
28-
versions with at least one item. The item connects the version tag (`version` attribute) with the absolute URL path
29-
segment of the domain-only path for all endpoints of this version. The following example specifies that
30-
this [=Connector=] offers version `2024-1` endpoints at `<host>/some/path/2024-1`, the `2025-1` endpoints at
31-
`<host>/some/path/2025-1` and another [=Connector=] on the same host under `<host>/different/path/2025-1`.
32-
33-
```json
34-
{
35-
"protocolVersions": [
36-
{
37-
"version": "2024-1",
38-
"path": "/some/path/2024-1"
39-
},
40-
{
41-
"version": "2025-1",
42-
"path": "/some/path/2025-1"
43-
},
44-
{
45-
"version": "2025-1",
46-
"path": "/different/path/2025-1"
47-
}
48-
]
49-
}
50-
```
25+
A [=Connector=] must respond to a respective HTTPS request by returning a [`VersionResponse`](#VersionResponse-table)
26+
with at least one item. The item connects the version tag (`version` attribute) with a path to the endpoint.
27+
The semantics of the `path` property are specified by each protocol binding.
5128

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

5633
### HTTPS Binding
5734

58-
#### The Well-Known Version Metadata Endpoint
59-
60-
Each implementation must provide the version metadata endpoint, which must use the `dspace-version` Well-Known Uniform
61-
Resource Identifier [[rfc8615]] at the top of the path hierarchy:
35+
When using the DSP HTTPS binding, the `path` property is an absolute URL path segment to be appended to the domain for
36+
all endpoints of this version.
6237

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

67-
The contents of the response is a JSON object defined in section [[[#exposure-of-dataspace-protocol-versions]]]. The
68-
version endpoint MUST be unversioned and unauthenticated.
43+
<aside class="example" title="well-known version endpoint (HTTPS)">
44+
<pre class="http">GET https://provider.com/.well-known/dspace-version
45+
</pre>
46+
<pre class="json" data-include="message/example/protocol-version.json">
47+
</pre>
48+
</aside>

‎specifications/common/type.definitions.md

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,11 +3,12 @@
33
<p data-include="message/table/action.html" data-include-format="html">
44
</p>
55

6+
<p data-include="message/table/auth.html" data-include-format="html">
7+
</p>
68

79
<p data-include="message/table/constraint.html" data-include-format="html">
810
</p>
911

10-
1112
<p data-include="message/table/catalog.html" data-include-format="html">
1213
</p>
1314

@@ -17,28 +18,26 @@
1718
<p data-include="message/table/distribution.html" data-include-format="html">
1819
</p>
1920

20-
2121
<p data-include="message/table/duty.html" data-include-format="html">
2222
</p>
2323

24-
2524
<p data-include="message/table/dataservice.html" data-include-format="html">
2625
</p>
2726

28-
2927
<p data-include="message/table/endpointproperty.html" data-include-format="html">
3028
</p>
3129

32-
3330
<p data-include="message/table/messageoffer.html" data-include-format="html">
3431
</p>
3532

36-
3733
<p data-include="message/table/offer.html" data-include-format="html">
3834
</p>
3935

40-
4136
<p data-include="message/table/permission.html" data-include-format="html">
4237
</p>
4338

39+
<p data-include="message/table/versionresponse.html" data-include-format="html">
40+
</p>
4441

42+
<p data-include="message/table/version.html" data-include-format="html">
43+
</p>

0 commit comments

Comments
 (0)