Are dynamic schemata possible?

[seyfahni]

I've got a requirement for an endpoint that has a dynamic schema:
In general /type/{type} returns just is a JSON object that maps a key to some kind of value, but for specific paths it might be more concrete.

For /type/A if could have a schema that a key foo exists with a string value and key bar with an integer value while /type/B should have a key baz with an array of stings. These types are however dynamic, so I must be able to add more of them (or remove them) during runtime (there will be a different API endpoint for it).

Is it theoretically possible to use huma with this kind of requirement? Ideally I'd still want the schema to be linked like in normal endpoints where it is generated from the type (Link: </schemas/TypeABody.json>; rel="describedBy").

---

I am fairly new to this library, so please forgive me if I missed anything obvious.

I've seen in hint in the Registry.Schema(..., hint string) *Schema method and the SchemaProvider interface, but how can I leverage either of those (if even possible) to do what I want? Which is the better way?

---

Update: I tried to provide a dynamic schema, but the methods providing custom schemata were never called.
Additionally, this causes me to loose the Link response header. I suspect that this is due to my usage of map[string]any.

Experimental Code for SchemaProvider

package main

import (
	"context"
	"fmt"
	"net/http"

	"github.com/danielgtaylor/huma/v2"
	"github.com/danielgtaylor/huma/v2/adapters/humago"
)

type Input struct {
	Name string `path:"name" maxLenth:"30" example:"world" doc:"Name to greet"`
}

type Output struct {
	huma.SchemaProvider
	Body map[string]any
}

type GenericOutputSchemaProvider struct{}

func (p GenericOutputSchemaProvider) Schema(r huma.Registry) *huma.Schema {
	return &huma.Schema{
		Type: "object",
		Properties: map[string]*huma.Schema{
			"message": {
				Type: "string",
			},
			"generic": {
				Type: "boolean",
			},
		},
		AdditionalProperties: false,
		Required:             []string{"message", "generic"},
	}
}

type SpecificOutputSchemaProvider struct{}

func (p SpecificOutputSchemaProvider) Schema(r huma.Registry) *huma.Schema {
	return &huma.Schema{
		Type: "object",
		Properties: map[string]*huma.Schema{
			"message": {
				Type: "string",
			},
		},
		AdditionalProperties: false,
		Required:             []string{"message"},
	}
}

func main() {
	router := http.NewServeMux()
	api := humago.New(router, huma.DefaultConfig("Config Service", "0.1.0"))

	huma.Register(api, huma.Operation{
		OperationID: "get-greeting",
		Method:      http.MethodGet,
		Path:        "/greeting/{name}",
		Summary:     "Get a greeting",
		Description: "Get a greeting for a person by name.",
		Tags:        []string{"Greetings"},
	}, func(ctx context.Context, input *Input) (*Output, error) {
		if input.Name == "there" {
			return &Output{
				SchemaProvider: GenericOutputSchemaProvider{},
				Body: map[string]any{
					"message": "Hello there!",
					"generic": true,
				},
			}, nil
		} else {
			return &Output{
				SchemaProvider: SpecificOutputSchemaProvider{},
				Body: map[string]any{
					"message": fmt.Sprintf("Hello, %s!", input.Name),
				},
			}, nil
		}
	})

	http.ListenAndServe("127.0.0.1:8080", router)
}

Experimental Code for Registry

package main

import (
	"context"
	"fmt"
	"net/http"
	"reflect"

	"github.com/danielgtaylor/huma/v2"
	"github.com/danielgtaylor/huma/v2/adapters/humago"
)

type Input struct {
	Name string `path:"name" maxLenth:"30" example:"world" doc:"Name to greet"`
}

type Output struct {
	Body map[string]any
}

func (o Output) Schema(r huma.Registry) *huma.Schema {
	hint := ""
	_, exists := o.Body["generic"]
	if exists {
		hint = "generic"
	}
	return r.Schema(reflect.TypeOf(o), true, hint)
}

type DynamicRegistry struct {
	huma.Registry
	dynamicSchemas map[reflect.Type]map[string]*huma.Schema
}

func (r DynamicRegistry) Schema(t reflect.Type, allowRef bool, hint string) *huma.Schema {
	schemas, exists := r.dynamicSchemas[t]
	if exists {
		schema, exists := schemas[hint]
		if exists {
			return schema
		}
	}

	return r.Registry.Schema(t, allowRef, hint)
}

func main() {
	router := http.NewServeMux()
	config := huma.DefaultConfig("Config Service", "0.1.0")
	config.OpenAPI.Components.Schemas = DynamicRegistry{
		Registry: config.OpenAPI.Components.Schemas,
		dynamicSchemas: map[reflect.Type]map[string]*huma.Schema{
			reflect.TypeFor[Output](): {
				"GenericOutput": {
					Type: "object",
					Properties: map[string]*huma.Schema{
						"message": {
							Type: "string",
						},
						"generic": {
							Type: "boolean",
						},
					},
					AdditionalProperties: false,
					Required:             []string{"message", "generic"},
				},
			},
		},
	}
	api := humago.New(router, config)

	huma.Register(api, huma.Operation{
		OperationID: "get-greeting",
		Method:      http.MethodGet,
		Path:        "/greeting/{name}",
		Summary:     "Get a greeting",
		Description: "Get a greeting for a person by name.",
		Tags:        []string{"Greetings"},
	}, func(ctx context.Context, input *Input) (*Output, error) {
		if input.Name == "there" {
			return &Output{
				Body: map[string]any{
					"message": "Hello there!",
					"generic": true,
				},
			}, nil
		} else {
			return &Output{
				Body: map[string]any{
					"message": fmt.Sprintf("Hello, %s!", input.Name),
				},
			}, nil
		}
	})

	http.ListenAndServe("127.0.0.1:8080", router)
}

[danielgtaylor]

@seyfahni while I'm not sure I'd recommend doing this it is certainly possible. If you protect the OpenAPI doc from concurrent access then your handlers can safely modify it at runtime however you like. For example:

https://go.dev/play/p/90XGCi3ewBm

mu := sync.Mutex{}
lockMiddleware := func(ctx huma.Context, next func(huma.Context)) {
	// Protect concurrent access to the OpenAPI doc. Using a middleware locks
	// *before* the validation happens, which also accesses the OpenAPI doc.
	mu.Lock()
	defer mu.Unlock()
	next(ctx)
}

huma.Get(api, "/type/{type}", func(ctx context.Context, input *struct {
	Type string `path:"type" enum:"initial"`
}) (*struct{}, error) {
	// TODO: Do something with type...
	fmt.Println("You sent me", input.Type)
	return nil, nil
}, WithMiddleware(lockMiddleware))

huma.Put(api, "/type/{type}", func(ctx context.Context, input *struct {
	Type string `path:"type"`
}) (*struct{}, error) {
	s := api.OpenAPI().Paths["/type/{type}"].Get.Parameters[0].Schema
	s.Enum = append(s.Enum, input.Type)
	s.PrecomputeMessages()
	// TODO: update output schemas via `OneOf`...
	return nil, nil
}, WithMiddleware(lockMiddleware))

Modifying the param's enum value means Huma will automatically validate the input types from a known list. Modifying the output schemas (left as a TODO in the example) will allow clients to be generated that support the various output types, but keep in mind those clients will be out of date anytime the API types change. I would suggest using a map[string]any as the output body type unless you want to handle serialization yourself and return []byte.

Assuming you have a lot more reads than writes you could also make this more efficient using a sync.RWMutex.

Hopefully that helps!