spring-projects/spring-ai · error · IllegalStateException

Failed to convert JSON Schema to OpenAPI format:

Error message

Failed to convert JSON Schema to OpenAPI format: 

What it means

JsonSchemaConverter.convertToOpenApiSchema(node, schemaType) rethrows any exception during the JSON Schema -> OpenAPI transformation as an IllegalStateException. The library throws this when the input ObjectNode has a shape the converter cannot transform (unexpected nodes, malformed nesting) or any internal error occurs.

Source

Thrown at models/spring-ai-google-genai/src/main/java/org/springframework/ai/google/genai/schema/JsonSchemaConverter.java:81

	 */
	public static ObjectNode convertToOpenApiSchema(ObjectNode jsonSchemaNode) {
		Assert.notNull(jsonSchemaNode, "JSON Schema node must not be null");
		Assert.isTrue(!jsonSchemaNode.has("$defs"), "Google's Structured Output schema doesn't support $defs property");

		try {
			// Convert to OpenAPI schema using our custom conversion logic
			ObjectNode openApiSchema = convertSchema(jsonSchemaNode,
					JacksonUtils.getDefaultJsonMapper().getNodeFactory());

			// Add OpenAPI-specific metadata
			if (!openApiSchema.has("openapi")) {
				openApiSchema.put("openapi", "3.0.0");
			}

			return openApiSchema;
		}
		catch (Exception e) {
			throw new IllegalStateException("Failed to convert JSON Schema to OpenAPI format: " + e.getMessage(), e);
		}
	}

	/**
	 * Copies common properties from source to target node.
	 * @param source The source ObjectNode containing JSON Schema properties
	 * @param target The target ObjectNode to copy properties to
	 */
	private static void copyCommonProperties(ObjectNode source, ObjectNode target) {
		Assert.notNull(source, "Source node must not be null");
		Assert.notNull(target, "Target node must not be null");
		String[] commonProperties = {
				// Core schema properties
				"format", "description", "default", "maximum", "minimum", "maxLength", "minLength", "pattern", "enum",
				"multipleOf", "uniqueItems",
				// OpenAPI specific properties
				"example", "deprecated", "readOnly", "writeOnly", "discriminator", "xml", "externalDocs" };

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Validate the input node is a valid JSON Schema object before converting
2. Remove unsupported JSON Schema keywords (e.g., $ref/$schema) not handled by the converter
3. Inspect the chained cause message for the specific node that failed
4. Ensure readTree produced an ObjectNode, not an array/scalar

Example fix

// before
ObjectNode openApi = JsonSchemaConverter.convertToOpenApiSchema(node, "OPENAPI");
// after
if (!node.isObject() || !node.has("type")) {
    throw new IllegalArgumentException("input is not a JSON Schema object");
}
ObjectNode openApi = JsonSchemaConverter.convertToOpenApiSchema(node, "OPENAPI");

if (node == null || !node.isObject() || !node.has("type")) {
    throw new IllegalArgumentException("not a JSON Schema object node");
}

boolean isJsonSchemaObject(com.fasterxml.jackson.databind.JsonNode n) {
    return n != null && n.isObject() && n.hasNonNull("type") && !n.has("$ref");
}

try {
    ObjectNode openApi = JsonSchemaConverter.convertToOpenApiSchema(node, "OPENAPI");
} catch (IllegalStateException e) {
    logger.error("schema conversion failed: {}", e.getCause() != null ? e.getCause().getMessage() : e.getMessage());
    throw e;
}

When it happens

Trigger: Passing an ObjectNode that is not a valid JSON Schema object (missing 'type'/'properties', null root, arrays where objects expected) so property-copy/transformation code throws.

Common situations: Programmatically built schema nodes missing required fields, schemas combining JSON Schema draft features unsupported by OpenAPI 3.0, or passing a non-object node (e.g., readTree returned an array).

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Failed to create index:
• Failed to parse tool input schema:
• Unsupported value type:
• Failed to parse JSON:
• Failed to parse JSON schema:

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/81ef59316e836f9f. Report an issue: GitHub.