Proposal: Global Type Schema Overrides

[victorvcruz]

Feature Request: Global Type Schema Overrides

Is your feature request related to a problem? Please describe.

I'm always frustrated when I need to apply the same custom type schema mappings across multiple schema generations in my application. Currently, when using jsonschema.For[] or jsonschema.ForType(), I have to repeatedly define the same TypeSchemas map in ForOptions for every schema generation call.

For example, in my application I have UUID fields from github.com/google/uuid that should always be serialized as JSON strings rather than the default behavior. I need to define this mapping every time I generate a schema:

opts := &jsonschema.ForOptions{
    TypeSchemas: map[any]*jsonschema.Schema{
        uuid.UUID{}: &jsonschema.Schema{Type: "string"},
    },
}
mySchema, _ := jsonschema.For[MyStruct](opts)

This becomes repetitive and error-prone when I have multiple structs across different packages that all need the same UUID handling.

Describe the solution you'd like

I would like a way to register global type schema overrides that automatically apply to all schema generation calls without needing to pass them in ForOptions every time. This could be implemented as:

1. A global registry function like jsonschema.RegisterGlobalTypeSchema(any, *Schema), already using the structure of initialSchemaMap in infer.go
2. Or a package-level configuration that gets automatically merged with any provided ForOptions.TypeSchemas

The ideal API might look like:

// Register once at application startup
jsonschema.RegisterGlobalTypeSchema(uuid.UUID{}, &jsonschema.Schema{Type: "string"})

// Now all schema generations automatically use the registered mappings
mySchema1, _ := jsonschema.For[Struct1](nil)
mySchema2, _ := jsonschema.For[Struct2](nil) 
// Both schemas will have UUID fields as strings

Additional context

This feature would be particularly valuable for:

• Applications using domain-specific types (UUIDs, custom time formats, etc.) consistently across many structs
• Libraries that want to provide consistent JSON schema behavior for their types

A real-world example where this caused issues: I was generating JSON schemas for MCP tools with github.com/modelcontextprotocol/go-sdk where UUID fields needed to be consistently represented as strings across multiple tool definitions, but I had to remember to pass the same TypeSchemas configuration in every location. If I didn’t explicitly specify this configuration, the uuid.UUID type would default to being interpreted as a byte array ([]byte), which led to incorrect schema generation and validation mismatches between tools.

If this proposal makes sense and aligns with the project’s direction, I’d be happy to contribute an implementation for it.

[jba]

Having global state like that in a library package is always the option of last resort.
Why don't you define a global jsonschema.ForOptions and pass it in on every call?

[victorvcruz]

Actually, I’m already doing that. I’ve essentially implemented an abstraction over jsonschema.ForOptions in my application that always includes my “global” type schema definitions. I’m just raising this as a potential improvement because the current library already has a structure (initialSchemaMap) that could support this kind of global registration internally:

jsonschema-go/jsonschema/infer.go

Lines 80 to 82 in 6311905

	schemas := maps.Clone(initialSchemaMap)
	// Add types from the options. They override the default ones.
	maps.Copy(schemas, opts.TypeSchemas)

It’s mainly a convenience improvement for cases where multiple schema generations need the same custom type handling.