docs: add decision record about optional params in CatalogRequest

DEPENDENCIES

@@ -45,14 +45,14 @@ maven/mavencentral/com.github.cliftonlabs/json-simple/3.0.2, Apache-2.0, approve
 maven/mavencentral/com.github.docker-java/docker-java-api/3.3.6, Apache-2.0, approved, #10346
 maven/mavencentral/com.github.docker-java/docker-java-transport-zerodep/3.3.6, Apache-2.0 AND (Apache-2.0 AND BSD-3-Clause), approved, #15251
 maven/mavencentral/com.github.docker-java/docker-java-transport/3.3.6, Apache-2.0, approved, #7942
-maven/mavencentral/com.github.java-json-tools/btf/1.3, Apache-2.0 AND GPL-1.0-or-later AND LGPL-3.0-only AND Apache-2.0 AND LGPL-3.0-only, restricted, #15201
+maven/mavencentral/com.github.java-json-tools/btf/1.3, Apache-2.0 OR LGPL-3.0-only, approved, #15201
 maven/mavencentral/com.github.java-json-tools/jackson-coreutils-equivalence/1.0, LGPL-3.0 OR Apache-2.0, approved, clearlydefined
 maven/mavencentral/com.github.java-json-tools/jackson-coreutils/2.0, Apache-2.0 OR LGPL-3.0-or-later, approved, #15186
 maven/mavencentral/com.github.java-json-tools/json-patch/1.13, Apache-2.0 OR LGPL-3.0-or-later, approved, CQ23929
-maven/mavencentral/com.github.java-json-tools/json-schema-core/1.2.14, Apache-2.0 AND LGPL-2.1-or-later AND LGPL-3.0-only AND (Apache-2.0 AND GPL-1.0-or-later AND LGPL-3.0-only) AND Apache-2.0 AND LGPL-3.0-only, restricted, #15282
-maven/mavencentral/com.github.java-json-tools/json-schema-validator/2.2.14, Apache-2.0 OR LGPL-3.0-or-later, approved, CQ20779
-maven/mavencentral/com.github.java-json-tools/msg-simple/1.2, Apache-2.0 AND LGPL-2.1-or-later AND LGPL-3.0-only AND (Apache-2.0 AND GPL-1.0-or-later AND LGPL-3.0-only) AND Apache-2.0 AND LGPL-3.0-only, restricted, #15239
-maven/mavencentral/com.github.java-json-tools/uri-template/0.10, Apache-2.0 AND LGPL-3.0-only AND (Apache-2.0 AND GPL-1.0-or-later AND LGPL-3.0-only), restricted, #15288
+maven/mavencentral/com.github.java-json-tools/json-schema-core/1.2.14, Apache-2.0 OR LGPL-3.0-or-later, approved, #15282
+maven/mavencentral/com.github.java-json-tools/json-schema-validator/2.2.14, Apache-2.0 OR LGPL-3.0-or-later, approved, #15263
+maven/mavencentral/com.github.java-json-tools/msg-simple/1.2, Apache-2.0 OR LGPL-3.0-or-later, approved, #15239
+maven/mavencentral/com.github.java-json-tools/uri-template/0.10, , approved, #15288
 maven/mavencentral/com.github.luben/zstd-jni/1.5.6-3, BSD-2-Clause, approved, clearlydefined
 maven/mavencentral/com.github.stephenc.jcip/jcip-annotations/1.0-1, Apache-2.0, approved, CQ21949
 maven/mavencentral/com.google.code.findbugs/jsr305/2.0.1, BSD-3-Clause AND CC-BY-2.5 AND LGPL-2.1+, approved, CQ13390
@@ -356,7 +356,7 @@ maven/mavencentral/org.testcontainers/jdbc/1.19.8, Apache-2.0, approved, #10348
 maven/mavencentral/org.testcontainers/junit-jupiter/1.19.8, MIT, approved, #10344
 maven/mavencentral/org.testcontainers/kafka/1.19.8, MIT, approved, #14177
 maven/mavencentral/org.testcontainers/postgresql/1.19.8, MIT, approved, #10350
-maven/mavencentral/org.testcontainers/testcontainers/1.19.8, Apache-2.0 AND MIT, approved, #10347
+maven/mavencentral/org.testcontainers/testcontainers/1.19.8, MIT, approved, #15203
 maven/mavencentral/org.testcontainers/vault/1.19.8, MIT, approved, #10852
 maven/mavencentral/org.xerial.snappy/snappy-java/1.1.10.5, Apache-2.0 AND (Apache-2.0 AND BSD-3-Clause), approved, #9098
 maven/mavencentral/org.xmlresolver/xmlresolver/5.2.2, Apache-2.0, approved, clearlydefined

docs/developer/decision-records/2024-07-03-additional-catalogrequest-param/README.md

@@ -0,0 +1,44 @@
+# Adding an additional parameter to the `CatalogRequest` (Management API)
+
+## Decision
+
+The `POST /catalog/request` endpoint to request a catalog will receive a new optional field in the request body with which the requesting participant (=consumer) can insert additional scopes into the DCP interaction.
+
+## Rationale
+
+In typical DCP interactions, the consumer derives the required scopes from the current request (e.g. policies, or existing agreements). This does not work for a Catalog request, because there is no request context.
+
+Further, in many dataspaces there are "default scopes", i.e. scopes that must be present on every DSP interaction, but these are static - they can't be changed at runtime.
+
+So if a provider offers assets, that are only available is a special (non-default) credential is presented, the consumer must be able to attach the respective scope strings to the access token.
+
+_NB: the information \_which_ scopes must be added, has to be conveyed out-of-band.\_
+
+In other words, a consumer may know that a provider has certain assets available, but they have an access policy constraint on them, which makes them "invisible" unless a certain credential is presented.
+
+## Approach
+
+The `CatalogRequest` will receive a new field `parameters`, which is an extensible map. This map may contain an entry `additionalScopes` which is a list of scope strings (as per [DCP Specification, Section 3.1](https://github.com/eclipse-tractusx/identity-trust/blob/main/specifications/verifiable.presentation.protocol.md#31-access-scopes)):
+
+```json
+{
+ "@type": "CatalogRequest",
+ "counterPartyAddress": "http://provider-address.com",
+ "counterPartyId": "providerId",
+ "protocol": "dataspace-protocol-http",
+ "querySpec": {
+ //...
+ },
+ "parameters": {
+ "additionalScopes": [
+ "org.eclipse.edc.vc.type.AdditionalCredentialType1:read",
+ "org.eclipse.edc.vc.type.AdditionalCredentialType2:*",
+ ]
+ }
+}
+```
+Scope strings provided in that fashion will get added to the default scopes.
+
+NB: both the `parameters` map and the `additionalScopes` entry are _OPTIONAL_.
+
+This feature will be added in an Alpha version of the Management API first, specifically of `3.1.0-alpha`. The respective URL path will be `/v31alpha/api/management/catalog/request` as per our [deprecation policy](https://github.com/eclipse-edc/docs/tree/main/developer/decision-records/2024-05-27-maturity-levels-deprecation-policy).

docs/developer/decision-records/README.md

@@ -57,3 +57,4 @@
 - [2024-01-12 Dynamic Constraint Functions](./2024-01-12-dynamic-constraint-functions/)
 - [2024-05-24 Dataplane Selection Improvements](./2024-05-24-dataplane-selection-improvements/)
 - [2024-06-24 Api Authentication Configuration](./2024-06-24-api-authentication-configuration/)
+- [2024-07-03 Additional CatalogRequest scope parameter](./2024-07-03-additional-catalogrequest-param/)