google / google/jsonschema-go

Proposal: Global Type Schema Overrides

Open
#37 2 comments 2 reactions 0 assignees View on GitHub
enhancement
Dominant language
Go
Stars
478
Forks
37
PR merge metrics
No merged PRs in 30d

Description

# 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](https://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:

```go
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](https://github.com/google/jsonschema-go/blob/main/jsonschema/infer.go)
2. Or a package-level configuration that gets automatically merged with any provided `ForOptions.TypeSchemas`

The ideal API might look like:

```go
// 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](https://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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.