Package org.springframework.ai.util.json.schema

Class JsonSchemaUtils

java.lang.Object
org.springframework.ai.util.json.schema.JsonSchemaUtils
public final class JsonSchemaUtils extends Object
Utility methods for working with JSON schemas.
Since:
1.0.0
Author:
Guangdong Liu, Ilayaperumal Gopinathan, Sebastien Deleuze

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    ensureValidInputSchema(String inputSchema)
    Ensures that the input schema is valid for AI model APIs.
    static tools.jackson.databind.node.ObjectNode
    getJsonSchema(Type inputType)
    Generates JSON Schema (version 2020_12) for the given class.
    static void
    hoistDefsToRoot(tools.jackson.databind.node.ObjectNode rootSchema, tools.jackson.databind.node.ObjectNode subSchema)
    Moves any $defs block found on subSchema into the $defs block of rootSchema, creating one on the root if needed.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • hoistDefsToRoot

      public static void hoistDefsToRoot(tools.jackson.databind.node.ObjectNode rootSchema, tools.jackson.databind.node.ObjectNode subSchema)
      Moves any $defs block found on subSchema into the $defs block of rootSchema, creating one on the root if needed. On key collisions the existing root entry is reused when the two definitions are structurally equal; otherwise the incoming entry is renamed with a numeric suffix and every "#/$defs/<oldKey>" reference inside the inlined sub-schema and inside every definition inserted by this call is rewritten to point at the new key.

      This is needed because victools generates self-contained schemas where $defs and the $ref pointers into them are rooted at the sub-schema. Inlining the sub-schema under properties.<paramName> re-parents existing "#/$defs/<Name>" refs to the outer root, leaving them unresolvable unless $defs is hoisted first.

      Parameters:
      rootSchema - the wrapper schema that will receive the hoisted definitions
      subSchema - the per-parameter sub-schema whose $defs block is consumed

    • ensureValidInputSchema

      public static String ensureValidInputSchema(String inputSchema)
      Ensures that the input schema is valid for AI model APIs. Many AI models require that the parameters object must have a "properties" field, even if it's empty. This method normalizes schemas from external sources (like MCP tools) that may not include this field.
      Parameters:
      inputSchema - the input schema as a JSON string
      Returns:
      a valid input schema as a JSON string with required fields

    • getJsonSchema

      public static tools.jackson.databind.node.ObjectNode getJsonSchema(Type inputType)
      Generates JSON Schema (version 2020_12) for the given class.
      Parameters:
      inputType - the input Type to generate JSON Schema from.
      Returns:
      the generated JSON Schema as a String.
      Since:
      2.0.0