opamp-spec icon indicating copy to clipboard operation
opamp-spec copied to clipboard

Add schema_version field to CustomMessage for fine-grained data schema versioning

Open juandemanjon opened this issue 1 month ago • 0 comments

Add schema_version field to CustomMessage for fine-grained data schema versioning

Summary

This PR adds an optional schema_version field to the CustomMessage protobuf definition to enable fine-grained versioning of custom message data schemas, independent of capability versioning.

Motivation

The current CustomMessage design requires both Agent and Server to decode the binary data field. As custom capabilities evolve, the data schema will change. Currently, the specification suggests embedding version information in the capability string (e.g., "com.company.capability/v2")

Proposed Solution

Add an optional explicit schema_version field to CustomMessage:

message CustomMessage {
    string capability = 1;
    string type = 2;
    bytes data = 3;
    string schema_version = 4;
}

Backward Compatibility

Fully backward compatible

  • The schema_version field is optional
  • When unset or empty, implementations use default/previous behavior
  • Existing implementations without version support will ignore the field
  • No breaking changes to existing custom capabilities

Outcome

Enables fine-grained, per-message data schema versioning within a single capability, allowing gradual migration and multiple schema versions to coexist without requiring separate capability declarations. This decouples capability evolution (adding/removing message types) from data schema evolution (changing message formats), enabling each to evolve independently and simplifying version management for custom capabilities.

juandemanjon avatar Dec 05 '25 16:12 juandemanjon