Defining a oneOf/union type

[absolutejam]

Hey!

I'm trying to define a oneOf schema and I'm looking for advice on how best to proceed.

Currently, in I have a DetailValueSpec marker interface that 2 types implement:

type DetailValueSpec interface {
	SpecKind() string
}

type DetailValueSpecFree struct{}
func (dk DetailValueSpecFree) SpecKind() string { return "free" }

type DetailValueSpecResource struct {
	AllowedResourceKinds []ResourceKind `json:"allowedResourceKinds"`
	MustExist            bool           `json:"mustExist"`
}
func (dk DetailValueSpecResource) SpecKind() string { return "resource" }

In my app, I just type-switch on the implementations (first class unions in Golang when?!).

The concrete types (DetailValueSpecFree and DetailValueSpecResource) have a custom MarshalJSON & UnmarshalJSON implementation that looks for / injects a kind property, so the JSON representation for them are:

{ "kind": "free" }
{ "kind": "resource", "allowedResourceKinds": [...], "mustExist": false }

In terms of schema, I suppose the 'correct' way would be something like...

config := huma.DefaultConfig("My API", "1.0.0")
config.Components.Schemas.Map()["DetailValueSpec"] = &huma.Schema{
	Type:            "DetailValueSpec",
	OneOf: []*huma.Schema{
		huma.SchemaFromType(r, reflect.TypeOf(DetailValueSpecFree{})),
		huma.SchemaFromType(r, reflect.TypeOf(DetailValueSpecResource{})),
	},
	Discriminator: &huma.Discriminator{
		PropertyName: "kind",
	},
}

And then also defining a custom schema on the concrete types (to include the kind)?

I've quickly tested this, but because my DetailValueSpec is part of another type, that type isn't resolving the custom schema.

My other, simpler option, was to have the API accept in input type that encompasses both and just validate that only one is present.

type DetailValueSpec struct {
	ResourceSpec *DetailValueSpecResource `json:"resource"`
	Free *DetailValueSpecFree `json:"free"`
}

But I feel like this still needs some kind of schema hint to show that only one is allowed, and should I be validating at the schema level (Transformer?) or just in my API?

Any suggestions would be great!

[absolutejam]

I'm currently using the latter approach, and using different types for my API than my internal domain logic, and transforming them in the handler. My question is, can I mark the fields as mutually exclusive in the schema, and can I get the example to show example valueSpecs instead of just [{}]?

[akpclarke]

I was attempting something somewhat similar to what I think you're trying to do here. If I remember correctly, it seemed like a schema for every type that I was using had already been created by the time my own code got run. Because of this, creating a schema with registry.Schema(reflect.TypeOf(MyCustomType{}), true, "") gave me a separate copy of the schema, which shared a bunch of the same attributes and values ( incl. the same value for its Ref attribute) as the one that was already registered but didn't really do what I wanted it to do.

I can't remember the details, but I managed to mostly sort things out by creating the schema like that and then using its Ref as the argument for the FromRef version of the function like this: registry.SchemaFromRef(mySchema.Ref). The schema object that I got from this call behaved quite differently from the other one.

Here I've approximately adapted my approach to your situation and hopefully that'll get you in the right direction.

// Before setting any of my routes
registry := api.OpenAPI().Components.Schemas

... 

// Building the "parent" schema so that we can get its Ref
var detailSpecSchema = registry.Schema(reflect.TypeOf(DetailSpec{}), true, "")

// Building the schemas for each option so that we can get their Refs
var dvsFreeSchema = registry.Schema(reflect.TypeOf(DetailValueSpecFree{}), true, "")
var dvsResourceSchema = registry.Schema(reflect.TypeOf(DetailValueSpecResource{}), true, "")

// Setting pretty titles for the selection menu :)
registry.SchemaFromRef(dvsFreeSchema.Ref).Title = "Detail Value Spec (Free)"
registry.SchemaFromRef(dvsResourceSchema.Ref).Title = "Detail Value Spec (Resource)"

// Setting our discriminated union as the type for the parent's "valueSpecs" property
registry.SchemaFromRef(detailSpecSchema.Ref).Properties["valueSpecs"] = &huma.Schema{
  OneOf: []*huma.Schema{
	 registry.SchemaFromRef(dvsFreeSchema.Ref),
	 registry.SchemaFromRef(dvsResourceSchema.Ref),
  },
  Discriminator: &huma.Discriminator{
	  PropertyName: "kind",
	  Mapping: map[string]string{
		  "free": dvsFreeSchema.Ref,
		  "resource":   dvsResourceSchema.Ref,
	  },
  },
}

Now to be honest, I couldn't get the Discriminator prop to work quite right, but I'm pretty sure it should look something like what I included there. I managed to mostly work around that problem anyway though by providing the discriminator prop on each struct (so in your case, the "kind" prop) with an enum struct tag that only has a single value defined so that way Huma should validate it correctly even if it's not technically 100% accurate.

So that would be something like

type DetailValueSpecFree struct{
	Kind string `json:"contentType" enum:"free"`
}

type DetailValueSpecResource struct {
	Kind			string		`json:"contentType" enum:"resource"`
	AllowedResourceKinds	[]ResourceKind	`json:"allowedResourceKinds"`
	MustExist		bool		`json:"mustExist"`
}

Anyway, if you manage to do it right, you'll get a dropdown to choose from in the OpenAPI doc. Mine looks like this:

I've only been coding in Go for like 2 weeks (of which almost an entire day was wasted on exactly this) and it's 3AM right now so take everything I've said here with a grain of salt, but hopefully that helps!

[seyfahni]

Ok, so I stumbled upon this issue as well and managed to solve in to a satisfactory level, but it is by no means perfect.

Multiple issues that prevent this from being solvable pretty:

• There is no nice way to register a custom schema and get the ref to it. One can either register a custom schema or get the ref for a generated type-based schema.
• While in the huma.SchemaProvider or huma.SchemaTransformer methods, there is no way to identify the name or ref of the current schema. This might not be an issue when working on the top-level struct, but when writing a struct that one might want to embed it is.

Going by OpenAPI Spec the minimum requirements for using a discriminator to work are as follows:

discriminator:
  mapping:
    foo: "#/components/schemas/Foo"
    bar: "#/components/schemas/Bar"
  propertyName: type
oneOf:
  - $ref: "#/components/schemas/Foo"
  - $ref: "#/components/schemas/Bar"

Assume we are working with these types:

type FooData struct {
	Foo string `json:"foo"`
}

type BarData struct {
	Bar string `json:"bar"`
}

type TypeData struct {
	Type string `json:"type"`
	*FooData
	*BarData
}

I needed a struct that I could embed, so I cannot use huma.SchemaProvider as I have no knowledge of all the other properties. Thus I implemented the huma.SchemaTransformer interface. This is a minimalist non-embeddable implementation that recreates the OpenAPI spec described above, but still requires all properties of all included-schemas:

func (t TypeData) TransformSchema(r huma.Registry, s *huma.Schema) *huma.Schema {
	ref := r.Schema(reflect.TypeOf(t), true, "").Ref
	return &huma.Schema{
		Discriminator: &huma.Discriminator{
			PropertyName: "type",
			Mapping: map[string]string{
				"foo": ref,
				"bar": ref,
			},
		},
		OneOf: []*huma.Schema{
			{Ref: ref},
		},
	}
}

So first of all the fact that FooData and BarData are exclusive needs to be fixed. To accomplish that, properties not part of the desired sub-schema need to be removed, along with their required entries if present. Then that newly created schema needs to be registered in the huma.Registry so we can reference it. I modified the huma.SchemaTransformer implementation and wrote these methods to make that happen:

func (t TypeData) TransformSchema(r huma.Registry, s *huma.Schema) *huma.Schema {
	baseRef := r.Schema(reflect.TypeOf(t), true, "").Ref

	fooSchemaRef := deriveDiscriminatedSchema(r, *s, baseRef, "Foo", func(property string) bool {
		return property != "bar"
	})
	barSchemaRef := deriveDiscriminatedSchema(r, *s, baseRef, "Bar", func(property string) bool {
		return property != "foo"
	})

	return &huma.Schema{
		Discriminator: &huma.Discriminator{
			PropertyName: "type",
			Mapping: map[string]string{
				"foo": fooSchemaRef,
				"bar": barSchemaRef,
			},
		},
		OneOf: []*huma.Schema{
			{Ref: fooSchemaRef},
			{Ref: barSchemaRef},
		},
	}
}

func deriveDiscriminatedSchema(
	registry huma.Registry,
	schema huma.Schema,
	baseRef string,
	title string,
	isIncluded func(property string) bool,
) string {
	schema.Title = title
	schema.Properties = copyMapKeyFiltered(schema.Properties, isIncluded)
	schema.Required = copySliceFiltered(schema.Required, isIncluded)
	schema.PrecomputeMessages()
	ref := baseRef + "-" + title
	registry.Map()[path.Base(ref)] = &schema
	return ref
}

func copySliceFiltered[S interface{ ~[]E }, E any](source S, filter func(E) bool) S {
	copied := make(S, 0, len(source))
	for _, v := range source {
		if filter(v) {
			copied = append(copied, v)
		}
	}
	return copied
}

func copyMapKeyFiltered[M interface{ ~map[K]V }, K comparable, V any](source M, filter func(K) bool) M {
	copied := make(M, len(source))
	for k, v := range source {
		if filter(k) {
			copied[k] = v
		}
	}
	return copied
}

Lastly, to make it possible to embed the TypeData struct I employed generics:

type TypeData[T any] struct {
	Type string `json:"type"`
	*FooData
	*BarData
}

func (t TypeData[T]) TransformSchema(r huma.Registry, s *huma.Schema) *huma.Schema {
	baseRef := r.Schema(reflect.TypeFor[T](), true, "").Ref

	fooSchemaRef := deriveDiscriminatedSchema(r, *s, baseRef, "Foo", func(property string) bool {
		return property != "bar"
	})
	barSchemaRef := deriveDiscriminatedSchema(r, *s, baseRef, "Bar", func(property string) bool {
		return property != "foo"
	})

	return &huma.Schema{
		Discriminator: &huma.Discriminator{
			PropertyName: "type",
			Mapping: map[string]string{
				"foo": fooSchemaRef,
				"bar": barSchemaRef,
			},
		},
		OneOf: []*huma.Schema{
			{Ref: fooSchemaRef},
			{Ref: barSchemaRef},
		},
	}
}

Thus we can pass the top-level struct's type to this embedded struct, even multiple embeds deep:

type FooBarBody struct {
	FooBarModel[FooBarBody]
}

type FooBarModel[T any] struct {
	TypeData[T]
}

This would generate the following OpenAPI spec:

discriminator:
  mapping:
    foo: "#/components/schemas/FooBarBody-Foo"
    bar: "#/components/schemas/FooBarBody-Bar"
  propertyName: type
oneOf:
  - $ref: "#/components/schemas/FooBarBody-Foo"
  - $ref: "#/components/schemas/FooBarBody-Bar"

Assuming that FooData and BarData are disjunct huma will generate a FooBarBody struct where *BarData == nil when Type == "foo" and vice versa. This is also extensible for more than two types.

Note that this solution might break other structs implementing huma.SchemaTransformer.

Complete & Final Example Code

import (
	"path"
	"reflect"

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

type FooBarBody struct {
	FooBarModel[FooBarBody]
}

type FooBarModel[T any] struct {
	TypeData[T]
}
type FooData struct {
	Foo string `json:"foo"`
}

type BarData struct {
	Bar string `json:"bar"`
}

type TypeData[T any] struct {
	Type string `json:"type"`
	*FooData
	*BarData
}

func (t TypeData[T]) TransformSchema(r huma.Registry, s *huma.Schema) *huma.Schema {
	baseRef := r.Schema(reflect.TypeFor[T](), true, "").Ref

	fooSchemaRef := deriveDiscriminatedSchema(r, *s, baseRef, "Foo", func(property string) bool {
		return property != "bar"
	})
	barSchemaRef := deriveDiscriminatedSchema(r, *s, baseRef, "Bar", func(property string) bool {
		return property != "foo"
	})

	return &huma.Schema{
		Discriminator: &huma.Discriminator{
			PropertyName: "type",
			Mapping: map[string]string{
				"foo": fooSchemaRef,
				"bar": barSchemaRef,
			},
		},
		OneOf: []*huma.Schema{
			{Ref: fooSchemaRef},
			{Ref: barSchemaRef},
		},
	}
}

func deriveDiscriminatedSchema(
	registry huma.Registry,
	schema huma.Schema,
	baseRef string,
	title string,
	isIncluded func(property string) bool,
) string {
	schema.Title = title
	schema.Properties = copyMapKeyFiltered(schema.Properties, isIncluded)
	schema.Required = copySliceFiltered(schema.Required, isIncluded)
	schema.PrecomputeMessages()
	ref := baseRef + "-" + title
	registry.Map()[path.Base(ref)] = &schema
	return ref
}

func copySliceFiltered[S interface{ ~[]E }, E any](source S, filter func(E) bool) S {
	copied := make(S, 0, len(source))
	for _, v := range source {
		if filter(v) {
			copied = append(copied, v)
		}
	}
	return copied
}

func copyMapKeyFiltered[M interface{ ~map[K]V }, K comparable, V any](source M, filter func(K) bool) M {
	copied := make(M, len(source))
	for k, v := range source {
		if filter(k) {
			copied[k] = v
		}
	}
	return copied
}