# tbdex versioning
@plew , @moejangda

## protocol versioning

We propose using major and minor versions _only_ (no patch) for the protocol itself and adding `protocol` as a required field to `resourceMetadata` and `messageMetadata`, respectively (TS types used as an example):

export type ResourceMetadata<T extends ResourceKind> = {
  /** The author's DID */
  from: string
  /** the resource kind (e.g. Offering) */
  kind: T
  /** the resource id */
  id: string
  /** When the resource was created at. Expressed as ISO8601 */
  createdAt: string
  /** When the resource was last updated. Expressed as ISO8601 */
  updatedAt?: string
  /** Version of the protocol in use (x.x format) */
  protocol: string
}

export type MessageMetadata<T extends MessageKind> = {
  /** The sender's DID */
  from: string
  /** the recipient's DID */
  to: string
  /** the message kind (e.g. rfq, quote) */
  kind: T
  /** the message id */
  id: string
  /** ID for an "exchange" of messages between Alice - PFI. Uses the id of the RFQ that initiated the exchange */
  exchangeId: string
  /** Message creation time. Expressed as ISO8601 */
  createdAt: string
  /** Version of the protocol in use (x.x format) */
  protocol: string
}

In addition, we may want to explore adding a `GET /pfi-protocol-versions` endpoint to the HTTP API spec. This would return an array of protocol versions that the PFI supports.

### anticipated changes
#### protocol-wide
- adding a net new message kind
- required or optional message. Required would change the state machine of an exchange
- message / resource removal
- adding a new resource kind

#### schema-specific
- adding a field to a resource or schema (required or optional)
- removing a field (required or optional)
- updating data type of existing field - e.g. paymentDetails goes from being an object to an array

#### http API
- adding a new endpoint (required or optional)
- removing an endpoint
- changing the request/response for an existing endpoint

### when to bump
All changes which result in either the client or the PFI being unable to correctly serialize/deserialze messages are considered breaking changes. Therefore, we will wait until a "version train" with sizable changes has accumulated to release a new version.

We will maintain spec text for all versions that are supported, i.e protocol definition v1, protocol definition v2. All spec changes that are in flight can be, in the interim, allocated to the next version number, but we will finalize which features make the "train" at the point of officially releasing the next version. This way, protocol changes can be proposed independently of version release.

tbdex spec versions are *generally* updated ahead of implementations; i.e the latest version of the spec may be released without a corresponding implementation being available. Implementations must state which version(s) of tbdex they support.

### client-server communication
Supporting more than one version of the protocol necessarily introduces complexity. A problem to be tackled after we cut v1 will be to architect the SDKs in such a way that it's as easy as possible for PFIs and clients to communicate.

Our initial thinking:

sequenceDiagram
autonumber

participant A as Alice
participant P as PFI

A->>P: GET /pfi-protocol-versions
P->>A: [2.0]
A->>A: Instantiate TbdexHttpClientV2
A->>P: TbdexHttpClientV2.getOfferings()
P->>A: [OfferingV2 {}]

SDKs will maintain versioned data models, servers, and clients for all supported versions. It'll be up to individual clients and PFIs which version(s) they want to implement.

At the moment, it seems reasonable to maintain the last two versions of the protocol at any time. We can revisit this assumption after the release of v1.

## SDK versioning
SDKs themselves follow semantic versioning. Each tbdex SDK will make the following packages available:
1. rollup, which exposes all individual packages
2. protocol, which contains the foundational data models
3. http-server, which implements the HTTP API spec and contains convenient functionality for PFIs wishing to operate on tbdex
4. http-client, which contains helper methods to construct and send tbdex messages for users seeking liquidity from PFIs

Packages 2-4 are versioned and can be bumped independently. As the rollup contains all of the other packages, it may be bumped as a train, whenever a collection of its subpackages are tested and ready to be cohesively released together.

Note that SDK semantic versioning is completely decoupled from the _protocol_ versions described above. For example, the JS SDK could be at v2.8.8 while the protocol is on v2. The major versions of the SDK will always be greater than or equal to the protocol version as all breaking changes will result in a major version bump of the SDKs.