Add schema version field to run config (#1424)

Now that the run config is part of our API contract, we need to consider backwards and forwards compatibility issues. As part of this - add a schema version field to the document so that we can add migration logic if needed.

Author: dmjb

pkg/runner/config.go

@@ -24,9 +24,18 @@ import (
 	"github.com/stacklok/toolhive/pkg/transport/types"
 )
 
+// CurrentSchemaVersion is the current version of the RunConfig schema
+// TODO: Set to "v1.0.0" when we clean up the middleware configuration.
+const CurrentSchemaVersion = "v0.1.0"
+
 // RunConfig contains all the configuration needed to run an MCP server
 // It is serializable to JSON and YAML
+// NOTE: This format is importable and exportable, and as a result should be
+// considered part of ToolHive's API contract.
 type RunConfig struct {
+	// SchemaVersion is the version of the RunConfig schema
+	SchemaVersion string `json:"schema_version" yaml:"schema_version"`
+
 	// Image is the Docker image to run
 	Image string `json:"image" yaml:"image"`
 
@@ -136,6 +145,10 @@ type RunConfig struct {
 
 // WriteJSON serializes the RunConfig to JSON and writes it to the provided writer
 func (c *RunConfig) WriteJSON(w io.Writer) error {
+	// Ensure the schema version is set
+	if c.SchemaVersion == "" {
+		c.SchemaVersion = CurrentSchemaVersion
+	}
 	encoder := json.NewEncoder(w)
 	encoder.SetIndent("", "  ")
 	return encoder.Encode(c)
@@ -167,6 +180,11 @@ func ReadJSON(r io.Reader) (*RunConfig, error) {
 		config.Secrets = []string{}
 	}
 
+	// Set the default schema version if not set
+	if config.SchemaVersion == "" {
+		config.SchemaVersion = CurrentSchemaVersion
+	}
+
 	return &config, nil
 }
 

pkg/runner/config_builder.go

@@ -321,6 +321,9 @@ func (b *RunConfigBuilder) Build(
 		return nil, fmt.Errorf("failed to set environment variables: %v", err)
 	}
 
+	// Set schema version.
+	b.config.SchemaVersion = CurrentSchemaVersion
+
 	return b.config, nil
 }