Migration from OpenAPI 3.0 Schema Object to JSONSchema in Eino

[mrh997]

📌 Summary

In the future, Eino will use JSONSchema Draft 2020-12 to replace OpenAPI 3.0 Schema Object to describe tool parameters. We will release v0.6.0 in November, at which time all OpenAPI 3.0 related codes will be removed.

---

❗Issues

Related issues: #299 #364 #381

• Dependency vulnerability
  Eino currently depends on kin-openapi@v0.118.0, which has a critical security vulnerability.
• Protocol alignment
  Most model platform protocols — such as OpenAI, ARK and Claude — specify that tool parameters should be described using JSONSchema. Likewise, the MCP protocol also suggests JSONSchema for tool parameters.

---

💡 Solution

• Adopt JSONSchema Draft 2020-12 as the standard tool parameter description format.
• Deprecate all OpenAPI 3.0 Schema Object references.

---

⚠️ Breaking Changes

✅ New Features
The two new methods planned are as follows:

• NewParamsOneOfByJSONSchema()

// NewParamsOneOfByJSONSchema creates a ParamsOneOf with JSONSchema.
func NewParamsOneOfByJSONSchema(jsonSchema *jsonschema.Schema) (*ParamsOneOf, error) {
    return &ParamsOneOf{
       jsonSchema: jsonSchema,
    }
}

• ParamsOneOf.ToJSONSchema()

// ToJSONSchema converts Params to JSONSchema.
func (p *ParamsOneOf) ToJSONSchema() (*jsonschema.Schema, error) {}

• WithSchemaModifier()

// WithSchemaModifier sets a user-defined schema modifier for inferring tool parameter from tagged go struct.
func WithSchemaModifier(modifier SchemaModifierFn) Option {}

⛔ Deprecated (will be removed in future releases)

• SchemaCustomizerFn

type SchemaCustomizerFn func(name string, t reflect.Type, tag reflect.StructTag, schema *openapi3.Schema) error

• WithSchemaCustomizer()

func WithSchemaCustomizer(sc SchemaCustomizerFn) Option {}

• NewParamsOneOfByOpenAPIV3()

func NewParamsOneOfByOpenAPIV3(openAPIV3 *openapi3.Schema) *ParamsOneOf {}

• ParamsOneOf.ToOpenAPIV3()

func (p *ParamsOneOf) ToOpenAPIV3() (*openapi3.Schema, error) {}

[marwan38]

Great! Looking forward to this.

Loving eino so far.

[eddiearc]

When I use utils.InferTool, I want to dynamically modify the enumeration values of the parameters.

but WithSchemaCustomizer is deprecated

Is it possible to support dynamic modification of jsonschema.Schema?

like WithJSONSchemaCustomizer(f func(jsm *jsonschema.Schema)) Option

[hi-pender]

When I use utils.InferTool, I want to dynamically modify the enumeration values of the parameters.

but WithSchemaCustomizer is deprecated

Is it possible to support dynamic modification of jsonschema.Schema?

like WithJSONSchemaCustomizer(f func(jsm *jsonschema.Schema)) Option

Thank you for your feedback, we will provide the dynamic modification capability as you suggested.
additionally, may I ask if your enumeration values are maintained separately as another configuration in a different place?

[mrh997]

When I use utils.InferTool, I want to dynamically modify the enumeration values of the parameters.

but WithSchemaCustomizer is deprecated

Is it possible to support dynamic modification of jsonschema.Schema?

like WithJSONSchemaCustomizer(f func(jsm *jsonschema.Schema)) Option

@eddiearc We added a new method WithSchemaModifier() in the v0.5.4, which is used in almost the same way as WithSchemaCustomizer().

[panwangwin]

Do we have ETA for these features?

[mrh997]

Do we have ETA for these features?

We plan to release v0.6.0 in November, at which time we will completely remove the OpenAPI 3.0 related code.

[mrh997]

We have released v0.6.1.

[mrh997]

If migrating to JSON Schema is too complex, consider using these two alternative methods.

OpenAPIV3ToJSONSchema

import (
    "encoding/json"
    "fmt"
    "strconv"

    "github.com/eino-contrib/jsonschema"
    "github.com/getkin/kin-openapi/openapi3"
    orderedmap "github.com/wk8/go-ordered-map/v2"
)

func OpenAPIV3ToJSONSchema(openAPIV3Ref *openapi3.SchemaRef) (*jsonschema.Schema, error) {
    if openAPIV3Ref == nil || openAPIV3Ref.Value == nil {
       return nil, nil
    }

    openAPIV3 := openAPIV3Ref.Value

    js := &jsonschema.Schema{
       Type:          openAPIV3.Type,
       Ref:           openAPIV3Ref.Ref,
       Title:         openAPIV3.Title,
       Format:        openAPIV3.Format,
       Description:   openAPIV3.Description,
       Default:       openAPIV3.Default,
       MaxLength:     openAPIV3.MaxLength,
       UniqueItems:   openAPIV3.UniqueItems,
       ReadOnly:      openAPIV3.ReadOnly,
       WriteOnly:     openAPIV3.WriteOnly,
       Deprecated:    openAPIV3.Deprecated,
       Pattern:       openAPIV3.Pattern,
       MaxItems:      openAPIV3.MaxItems,
       MaxProperties: openAPIV3.MaxProps,
    }

    if openAPIV3.Example != nil {
       js.Examples = []any{openAPIV3.Example}
    }

    if openAPIV3.MinLength > 0 {
       js.MinLength = &openAPIV3.MinLength
    }

    if openAPIV3.MinItems > 0 {
       js.MinItems = &openAPIV3.MinItems
    }

    if openAPIV3.MinProps > 0 {
       js.MinProperties = &openAPIV3.MinProps
    }

    if openAPIV3.OneOf != nil {
       js.OneOf = make([]*jsonschema.Schema, len(openAPIV3.OneOf))
       for i, oneOf := range openAPIV3.OneOf {
          v, err := OpenAPIV3ToJSONSchema(oneOf)
          if err != nil {
             return nil, err
          }
          js.OneOf[i] = v
       }
    }

    if openAPIV3.AnyOf != nil {
       js.AnyOf = make([]*jsonschema.Schema, len(openAPIV3.AnyOf))
       for i, anyOf := range openAPIV3.AnyOf {
          v, err := OpenAPIV3ToJSONSchema(anyOf)
          if err != nil {
             return nil, err
          }
          js.AnyOf[i] = v
       }
    }

    if openAPIV3.AllOf != nil {
       js.AllOf = make([]*jsonschema.Schema, len(openAPIV3.AllOf))
       for i, allOf := range openAPIV3.AllOf {
          v, err := OpenAPIV3ToJSONSchema(allOf)
          if err != nil {
             return nil, err
          }
          js.AllOf[i] = v
       }
    }

    if openAPIV3.Not != nil {
       v, err := OpenAPIV3ToJSONSchema(openAPIV3.Not)
       if err != nil {
          return nil, err
       }
       js.Not = v
    }

    if openAPIV3.Min != nil {
       if openAPIV3.ExclusiveMin {
          js.ExclusiveMinimum = json.Number(strconv.FormatFloat(*openAPIV3.Min, 'g', -1, 64))
       } else {
          js.Minimum = json.Number(strconv.FormatFloat(*openAPIV3.Min, 'g', -1, 64))
       }
    }

    if openAPIV3.Max != nil {
       if openAPIV3.ExclusiveMax {
          js.ExclusiveMaximum = json.Number(strconv.FormatFloat(*openAPIV3.Max, 'g', -1, 64))
       } else {
          js.Maximum = json.Number(strconv.FormatFloat(*openAPIV3.Max, 'g', -1, 64))
       }
    }

    if openAPIV3.MultipleOf != nil {
       js.MultipleOf = json.Number(strconv.FormatFloat(*openAPIV3.MultipleOf, 'g', -1, 64))
    }

    if openAPIV3.Enum != nil {
       js.Enum = make([]any, len(openAPIV3.Enum))
       for i, enum := range openAPIV3.Enum {
          js.Enum[i] = enum
       }
    }

    if openAPIV3.Items != nil {
       v, err := OpenAPIV3ToJSONSchema(openAPIV3.Items)
       if err != nil {
          return nil, err
       }
       js.Items = v
    }

    if openAPIV3.Properties != nil {
       js.Properties = orderedmap.New[string, *jsonschema.Schema]()
       for k, v := range openAPIV3.Properties {
          if v == nil || v.Value == nil {
             continue
          }
          v_, err := OpenAPIV3ToJSONSchema(v)
          if err != nil {
             return nil, err
          }
          js.Properties.Set(k, v_)
       }
    }

    if openAPIV3.Required != nil {
       js.Required = make([]string, len(openAPIV3.Required))
       for i, required := range openAPIV3.Required {
          js.Required[i] = required
       }
    }

    if openAPIV3.AdditionalProperties.Schema != nil {
       v, err := OpenAPIV3ToJSONSchema(openAPIV3.AdditionalProperties.Schema)
       if err != nil {
          return nil, err
       }
       js.AdditionalProperties = v
    }

    if openAPIV3.Extensions != nil {
       if js.Extras == nil {
          js.Extras = make(map[string]any, len(openAPIV3.Extensions))
       }

       for k, v := range openAPIV3.Extensions {
          js.Extras[k] = v
       }
    }

    return js, nil
}

JSONSchemaToOpenAPIV3

import (
    "encoding/json"
    "fmt"
    "strconv"

    "github.com/eino-contrib/jsonschema"
    "github.com/getkin/kin-openapi/openapi3"
    orderedmap "github.com/wk8/go-ordered-map/v2"
)

func JSONSchemaToOpenAPIV3(js *jsonschema.Schema) (*openapi3.Schema, error) {
    if js == nil {
       return nil, nil
    }

    openAPIV3 := &openapi3.Schema{
       Type:        js.Type,
       Title:       js.Title,
       Format:      js.Format,
       Description: js.Description,
       Default:     js.Default,
       MaxLength:   js.MaxLength,
       UniqueItems: js.UniqueItems,
       ReadOnly:    js.ReadOnly,
       WriteOnly:   js.WriteOnly,
       Deprecated:  js.Deprecated,
       Pattern:     js.Pattern,
       MaxItems:    js.MaxItems,
       MaxProps:    js.MaxProperties,
    }

    if js.MinLength != nil {
       openAPIV3.MinLength = *js.MinLength
    }

    if js.MinItems != nil {
       openAPIV3.MinItems = *js.MinItems
    }

    if js.MinProperties != nil {
       openAPIV3.MinProps = *js.MinProperties
    }

    if len(js.Examples) > 0 {
       openAPIV3.Example = js.Examples[0]
    }

    if js.OneOf != nil {
       openAPIV3.OneOf = make([]*openapi3.SchemaRef, len(js.OneOf))
       for i, oneOf := range js.OneOf {
          v, err := JSONSchemaToOpenAPIV3(oneOf)
          if err != nil {
             return nil, err
          }
          openAPIV3.OneOf[i] = &openapi3.SchemaRef{
             Ref:   oneOf.Ref,
             Value: v,
          }
       }
    }

    if js.AnyOf != nil {
       openAPIV3.AnyOf = make([]*openapi3.SchemaRef, len(js.AnyOf))
       for i, anyOf := range js.AnyOf {
          v, err := JSONSchemaToOpenAPIV3(anyOf)
          if err != nil {
             return nil, err
          }
          openAPIV3.AnyOf[i] = &openapi3.SchemaRef{
             Ref:   anyOf.Ref,
             Value: v,
          }
       }
    }

    if js.AllOf != nil {
       openAPIV3.AllOf = make([]*openapi3.SchemaRef, len(js.AllOf))
       for i, allOf := range js.AllOf {
          v, err := JSONSchemaToOpenAPIV3(allOf)
          if err != nil {
             return nil, err
          }
          openAPIV3.AllOf[i] = &openapi3.SchemaRef{
             Ref:   allOf.Ref,
             Value: v,
          }
       }
    }

    if js.Not != nil {
       v, err := JSONSchemaToOpenAPIV3(js.Not)
       if err != nil {
          return nil, err
       }
       openAPIV3.Not = &openapi3.SchemaRef{
          Ref:   js.Not.Ref,
          Value: v,
       }
    }
    
    if js.ExclusiveMaximum != "" {
        openAPIV3.ExclusiveMax = true
        max, err := js.ExclusiveMaximum.Float64()
        if err != nil {
           return nil, fmt.Errorf("`ExclusiveMaximum` in JSONSchema must be a number: %w", err)
        }
        openAPIV3.Max = &max
    } else if js.Maximum != "" {
        max, err := js.Maximum.Float64()
        if err != nil {
           return nil, fmt.Errorf("`Maximum` in JSONSchema must be a number: %w", err)
        }
        openAPIV3.Max = &max
    }
    
    if js.ExclusiveMinimum != "" {
        openAPIV3.ExclusiveMin = true
        min, err := js.ExclusiveMinimum.Float64()
        if err != nil {
           return nil, fmt.Errorf("`ExclusiveMinimum` in JSONSchema must be a number: %w", err)
        }
        openAPIV3.Min = &min
    } else if js.Minimum != "" {
        min, err := js.Minimum.Float64()
        if err != nil {
           return nil, fmt.Errorf("`Minimum` in JSONSchema must be a number: %w", err)
        }
        openAPIV3.Min = &min
    }

    if js.MultipleOf != "" {
       multipleOf, err := js.MultipleOf.Float64()
       if err != nil {
          return nil, fmt.Errorf("`MultipleOf` in JSONSchema must be a number: %w", err)
       }
       openAPIV3.MultipleOf = &multipleOf
    }

    if js.Enum != nil {
       openAPIV3.Enum = make([]any, len(js.Enum))
       for i, enum := range js.Enum {
          openAPIV3.Enum[i] = enum
       }
    }

    if js.Items != nil {
       v, err := JSONSchemaToOpenAPIV3(js.Items)
       if err != nil {
          return nil, err
       }
       openAPIV3.Items = &openapi3.SchemaRef{Value: v}
    }

    if js.Properties != nil {
       openAPIV3.Properties = make(map[string]*openapi3.SchemaRef, js.Properties.Len())
       for pair := js.Properties.Oldest(); pair != nil; pair = pair.Next() {
          v, err := JSONSchemaToOpenAPIV3(pair.Value)
          if err != nil {
             return nil, err
          }
          openAPIV3.Properties[pair.Key] = &openapi3.SchemaRef{
             Ref:   pair.Value.Ref,
             Value: v,
          }
       }
    }

    if js.Required != nil {
       openAPIV3.Required = make([]string, len(js.Required))
       for i, required := range js.Required {
          openAPIV3.Required[i] = required
       }
    }

    if js.AdditionalProperties != nil {
       add, err := JSONSchemaToOpenAPIV3(js.AdditionalProperties)
       if err != nil {
          return nil, err
       }
       openAPIV3.AdditionalProperties = openapi3.AdditionalProperties{
          Schema: &openapi3.SchemaRef{
             Ref:   js.AdditionalProperties.Ref,
             Value: add,
          },
       }
    }

    if js.Extras != nil {
       if openAPIV3.Extensions == nil {
          openAPIV3.Extensions = make(map[string]any, len(js.Extras))
       }

       for k, v := range js.Extras {
          openAPIV3.Extensions[k] = v
       }
    }

    return openAPIV3, nil
}