---
# System prepended metadata

title: tbDEX Versioning

---

# tbDEX Versioning

How should tbDEX be versioned? There's quite a bit to unpack. Here's a few more concrete questions:

* Do we version the entire protocol? What are the implications of doing so? what is the resulting outcome?
* are individual message / resource schemas versioned? or are they all versioned together? Is this _in addition_ to versioning the entire protocol or what _causes_ the protocol to be versioned?
* what versioning scheme would one even use?


## Examples

so wot types of stuff can change? 2 categories i think

### Protocol-wide
* adding a net new message kind to tbdex. hopefully rare. Contrary would lead to a bloated / confusing protocol
  * required or optional message? required would change the state machine of an exchange
* message / resource removal (idk what this would even look like)
* adding a new resource kind
  * required or optional resource?


### Schema specific
* adding a field to a resource or schema
  * required or optional? 
* removing a field
  * was the field required or optional?
* updating data type of existing field - e.g. `paymentDetails` goes from being an object to an array


## Random Thoughts
Goal should be to keep versioning as simple as possible. Versioning the protocol itself _and_ individual schemas seems like it could get complicated to keep up with - "oh yeah i talk version 2 of tbdex but only version 3 of rfq and quote but version 4 of order"


---

maybe `x.x` semantic versioning does make sense where:
- major version bump:
    - a breaking change. **_not_** backwards compatible e.g.
        - adding a new required message kind
        - adding a new required property to an existing message kind
        - removing existing required property
        - changing data type of exsting field
- minor version bump:
  - backwards compatible change e.g.
    - adding a new optional field to a message


probably need to think ^ through a bit more. write up a list of different types of changes.

also worth looking into prior art


---

## Pratical Application

Maybe proposals to make changes to tbDEX can happen by submitting _TIPs_ (e.g. tbDEX Improvement Proposal).

Need to figure out structure of a TIP and what stages a TIP goes through.

Rough thoughts - TIP remains a draft until it's implemented & in-use by _n_ PFIs / SDKs  

I think every version major or minor should have a full set of message/resource schemas. will just be easier to track that way.


## TODOs
* Look at prior art for schema versioning
* Look at prior art for `*IP`s e.g. BIP, BEP, EIP etc.
* Look at prior art for protocol versioning - http, tcp, amqp etc.