docs: decision record about multiple protocol versions

docs/developer/decision-records/2024-09-25-multiple-protocol-versions/README.md

@@ -0,0 +1,68 @@
+# Multiple protocol versions
+
+## Decision
+
+We will introduce a `protocolVersion` in `RemoteMessage`, `TransferProcess` and `ContractNegotiation`  that will drive
+the selection the right protocol version for connector to connector communication.
+
+## Rationale
+
+Currently, EDC supports only [DSP](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol)
+in the current stable form. As the spec is evolving, we should prepare the EDC for supporting multiple versions in the
+same EDC runtime. This will enable the communication between two EDC connectors as long as they agree on a common
+supported version.
+
+## Approach
+
+A new method will be added in the `RemoteMessage`:
+
+```java
+public interface RemoteMessage {
+    ...
+
+    /**
+     * Returns the transport protocol version for this message.
+     */
+    String getProtocolVersion();
+}
+```
+
+The `protocolVersion` should be stored together like the `protocol` field in `ContractNegotiation` and `TransferProcess`
+entities. Once stored, it can be used for dispatching subsequent `RemoteMessage`s using the same version.
+
+In the context of [DSP](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol) implementation
+a protocol version consists of:
+
+- A set of Transformers for `RemoteMessage`s serialization/deserialization.
+- A scoped JSON-LD `@context` configured in the `JsonLd` service.
+- A set of Controllers for receiving protocol `RemoteMessage`s.
+
+### Transformers
+
+Instead of having a single `TypeTransformerRegistry` for the `dsp-api` context, we should have one for
+each [DSP](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol) supported version.
+
+### JSON-LD `@context`
+
+Currently, we bind [DSP](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol) specific
+namespaces/contexts definition under the scope `DSP`. We should have multiple configurations for each supported version
+
+### Controllers
+
+We already provide versioned controllers, but each version should have its own `JerseyJsonLdInterceptor` for injecting
+the right JSON-LD scope. This can be achieved using `jakarta.ws.rs.container.DynamicFeature` interface.
+
+The `protocolVersion` should be added also in `DspRequest` for selecting the right transformers for  `RemoteMessage`s.
+
+## Further considerations
+
+How the `protocolVersion` is vehicle for the initial requests like `TransferRequest` or `ContractRequest` is not decided
+in this DR.
+
+We could:
+
+- automatically detect the common
+  supported [version](https://docs.internationaldataspaces.org/ids-knowledgebase/v/dataspace-protocol/common-functionalities/common.protocol).
+- let the user input the `protocolVersion` in the management APIs.
+
+If no `protocolVersion` is specified or found, the behavior should guarantee backward compatibility.

docs/developer/decision-records/README.md

@@ -61,3 +61,4 @@
 - [2024-08-05 Custom JWSSigner Implementations](./2024-08-05-custom-jwssigners/)
 - [2024-08-16 Policy_Validation](./2024-08-16-policy-validation)
 - [2024-09-24 STS Accounts API](./2024-09-24-sts-accounts-api)
+- [2024-09-25 Multiple Protocol Versions](./2024-09-25-multiple-protocol-versions)