diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateClause.java b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateClause.java index aa8c314757..4d83be51d0 100644 --- a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateClause.java +++ b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateClause.java @@ -9,6 +9,7 @@ import java.util.stream.Collectors; import org.eclipse.microprofile.openapi.annotations.enums.SchemaType; import org.eclipse.microprofile.openapi.annotations.media.Schema; +import org.eclipse.microprofile.openapi.annotations.media.SchemaProperty; /** * Value type read from incoming JSON and used for resolving into actual {@link UpdateOperation}s @@ -16,16 +17,118 @@ */ @JsonDeserialize(using = UpdateClauseDeserializer.class) @Schema( + name = "UpdateClause", type = SchemaType.OBJECT, implementation = Object.class, - examples = - """ + additionalProperties = Schema.False.class, + description = + "The Update Clause to use when updating Documents in a Collection or Rows in a Table.", + properties = { + @SchemaProperty( + name = UpdateOperator.Names.SET, + type = SchemaType.OBJECT, + description = "Sets fields to the provided JSON value."), + @SchemaProperty( + name = UpdateOperator.Names.SET_ON_INSERT, + type = SchemaType.OBJECT, + description = + "Sets fields to the provided JSON value, only when an upsert inserts the document."), + @SchemaProperty( + name = UpdateOperator.Names.UNSET, + type = SchemaType.OBJECT, + description = "Removes fields from the Document, or sets Table columns to null."), + @SchemaProperty( + name = UpdateOperator.Names.INC, + type = SchemaType.OBJECT, + description = + "Updates numeric fields by incrementing them by the provided value (use negative values to decrement)."), + @SchemaProperty( + name = UpdateOperator.Names.MUL, + type = SchemaType.OBJECT, + description = "Updates numeric fields by multiplying them by the provided value."), + @SchemaProperty( + name = UpdateOperator.Names.MIN, + type = SchemaType.OBJECT, + description = + "Updates fields to the smaller of the current value or the provided value."), + @SchemaProperty( + name = UpdateOperator.Names.MAX, + type = SchemaType.OBJECT, + description = "Updates fields to the larger of the current value or the provided value."), + @SchemaProperty( + name = UpdateOperator.Names.RENAME, + type = SchemaType.OBJECT, + description = "Renames fields to the provided names."), + @SchemaProperty( + name = UpdateOperator.Names.CURRENT_DATE, + type = SchemaType.OBJECT, + description = + "Sets fields to the current date. The value must be true or {\"$type\": \"date\"}."), + @SchemaProperty( + name = UpdateOperator.Names.POP, + type = SchemaType.OBJECT, + description = + "Updates array fields to remove the first (-1) or the last (1) element of the array."), + @SchemaProperty( + name = UpdateOperator.Names.PUSH, + type = SchemaType.OBJECT, + description = + "Updates array fields in a Document, or list, set, and map columns in a Table, by appending values. Use $each for multiple values. Only collections accept $position."), + @SchemaProperty( + name = UpdateOperator.Names.ADD_TO_SET, + type = SchemaType.OBJECT, + description = + "Updates array fields in a Document by appending values that are not already present. Use $each for multiple values."), + @SchemaProperty( + name = UpdateOperator.Names.PULL_ALL, + type = SchemaType.OBJECT, + description = + "Updates list and set columns in a Table by removing the provided values, and map columns by removing the provided keys.") + }, + examples = { + """ { - "$set" : {"location": "New York"}, - "$unset" : {"new_data": 1} + "$set": {"location": "New York"}, + "$unset": {"obsolete": 1} } - """) -public record UpdateClause(EnumMap updateOperationDefs) { + """, + """ + { + "$inc": {"score": 0.25}, + "$mul": {"price": 1.5}, + "$min": {"lowest": 2.5}, + "$max": {"highest": 9.5} + } + """, + """ + { + "$push": { + "items": {"$each": [1, 2], "$position": 0} + }, + "$addToSet": { + "tags": {"$each": ["a", "b"]} + }, + "$pop": {"history": -1}, + "$rename": {"oldName": "newName"} + } + """, + """ + { + "$currentDate": {"updated": true}, + "$setOnInsert": {"created": {"$date": 123456}}, + "$set": {"optional": null} + } + """, + """ + { + "$pullAll": {"tags": ["a", "b"]} + } + """, + "{}" + }) +// Hide parsed operations from schemas without changing Jackson serialization. +public record UpdateClause( + @Schema(hidden = true) EnumMap updateOperationDefs) { /** * Method that will validate update operation definitions of the clause and construct an ordered * set of {@link UpdateOperation}s. diff --git a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateOperator.java b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateOperator.java index f9920aab0e..2968bfece7 100644 --- a/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateOperator.java +++ b/src/main/java/io/stargate/sgv2/jsonapi/api/model/command/clause/update/UpdateOperator.java @@ -7,92 +7,108 @@ /** List of update operator that's supported in update. */ public enum UpdateOperator { - ADD_TO_SET("$addToSet") { + ADD_TO_SET(Names.ADD_TO_SET) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return AddToSetOperation.construct(arguments); } }, - CURRENT_DATE("$currentDate") { + CURRENT_DATE(Names.CURRENT_DATE) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return CurrentDateOperation.construct(arguments); } }, - INC("$inc") { + INC(Names.INC) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return IncOperation.construct(arguments); } }, - MAX("$max") { + MAX(Names.MAX) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return MinMaxOperation.constructMax(arguments); } }, - MIN("$min") { + MIN(Names.MIN) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return MinMaxOperation.constructMin(arguments); } }, - MUL("$mul") { + MUL(Names.MUL) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return MulOperation.construct(arguments); } }, - POP("$pop") { + POP(Names.POP) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return PopOperation.construct(arguments); } }, - PUSH("$push") { + PUSH(Names.PUSH) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return PushOperation.construct(arguments); } }, - RENAME("$rename") { + RENAME(Names.RENAME) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return RenameOperation.construct(arguments); } }, - SET("$set") { + SET(Names.SET) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return SetOperation.constructSet(arguments); } }, - SET_ON_INSERT("$setOnInsert") { + SET_ON_INSERT(Names.SET_ON_INSERT) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return SetOperation.constructSetOnInsert(arguments); } }, - UNSET("$unset") { + UNSET(Names.UNSET) { @Override - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { return UnsetOperation.construct(arguments); } }, // Then operators that we recognize but do not (yet) support - PULL_ALL("$pullAll"); + PULL_ALL(Names.PULL_ALL); + + public interface Names { + String ADD_TO_SET = "$addToSet"; + String CURRENT_DATE = "$currentDate"; + String INC = "$inc"; + String MAX = "$max"; + String MIN = "$min"; + String MUL = "$mul"; + String POP = "$pop"; + String PUSH = "$push"; + String RENAME = "$rename"; + String SET = "$set"; + String SET_ON_INSERT = "$setOnInsert"; + String UNSET = "$unset"; + String PULL_ALL = "$pullAll"; + } private String apiName; @@ -104,7 +120,7 @@ public String apiName() { return apiName; } - public UpdateOperation resolveOperation(ObjectNode arguments) { + public UpdateOperation resolveOperation(ObjectNode arguments) { throw UpdateException.Code.UNSUPPORTED_UPDATE_OPERATION.get( Map.of("errorMessage", "Unsupported update operator '%s'".formatted(apiName))); } diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java index 99f5e33de0..d317e8f7d6 100644 --- a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java +++ b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpClauseSchemaContractTest.java @@ -3,29 +3,30 @@ import static io.restassured.RestAssured.given; import static org.junit.jupiter.api.Assertions.*; -import com.fasterxml.jackson.annotation.JsonIgnore; -import com.fasterxml.jackson.annotation.JsonProperty; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; -import com.fasterxml.jackson.databind.annotation.JsonDeserialize; import com.fasterxml.jackson.databind.node.MissingNode; import com.fasterxml.jackson.databind.node.ObjectNode; import com.github.victools.jsonschema.generator.*; import com.networknt.schema.JsonSchemaFactory; import com.networknt.schema.SpecVersion; +import com.networknt.schema.ValidationMessage; import io.quarkiverse.mcp.server.GlobalInputSchemaGenerator; import io.quarkiverse.mcp.server.ToolManager; import io.quarkus.test.junit.QuarkusTest; import io.quarkus.test.junit.TestProfile; import io.stargate.sgv2.jsonapi.TestConstants; -import io.stargate.sgv2.jsonapi.api.model.command.JsonDefinition; +import io.stargate.sgv2.jsonapi.api.model.command.Command; +import io.stargate.sgv2.jsonapi.api.model.command.Updatable; import io.stargate.sgv2.jsonapi.api.model.command.clause.filter.FilterDefinition; import io.stargate.sgv2.jsonapi.api.model.command.clause.filter.SortDefinition; import io.stargate.sgv2.jsonapi.api.model.command.clause.sort.FindAndRerankSort; +import io.stargate.sgv2.jsonapi.api.model.command.clause.update.UpdateClause; +import io.stargate.sgv2.jsonapi.api.model.command.clause.update.UpdateOperator; import io.stargate.sgv2.jsonapi.api.model.command.impl.CreateCollectionCommand; import io.stargate.sgv2.jsonapi.api.model.command.impl.FindAndRerankCommand; import io.stargate.sgv2.jsonapi.exception.RequestException; -import io.stargate.sgv2.jsonapi.metrics.CommandFeatures; +import io.stargate.sgv2.jsonapi.exception.UpdateException; import io.stargate.sgv2.jsonapi.service.provider.ApiModelSupport; import io.stargate.sgv2.jsonapi.service.reranking.configuration.RerankingProvidersConfig; import io.stargate.sgv2.jsonapi.service.reranking.configuration.RerankingProvidersConfig.RerankingProviderConfig.AuthenticationType; @@ -37,32 +38,33 @@ import io.stargate.sgv2.jsonapi.service.schema.collections.CollectionRerankDef; import io.stargate.sgv2.jsonapi.testresource.NoGlobalResourcesTestProfile; import jakarta.inject.Inject; -import java.util.ArrayList; -import java.util.Comparator; +import jakarta.validation.Validator; import java.util.HashSet; import java.util.List; import java.util.Map; import java.util.Optional; +import java.util.Set; import java.util.stream.Stream; +import java.util.stream.StreamSupport; import org.eclipse.microprofile.openapi.annotations.media.Schema; -import org.jboss.jandex.AnnotationTarget; -import org.jboss.jandex.IndexReader; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.function.Executable; import org.junit.jupiter.params.ParameterizedTest; -import org.junit.jupiter.params.provider.Arguments; +import org.junit.jupiter.params.provider.CsvSource; import org.junit.jupiter.params.provider.EnumSource; import org.junit.jupiter.params.provider.MethodSource; import org.junit.jupiter.params.provider.ValueSource; /** - * Checks that MCP and OpenAPI advertise the JSON accepted by Data API clause deserializers. - * Reflection alone exposes internal Java fields for clauses with custom deserializers, so those - * clauses need schema overrides. + * Checks the JSON schemas the Data API publishes for command clauses such as filter, sort, and + * update. Clients build requests from the MCP tool input schemas and the OpenAPI document, so both + * must accept the JSON the server accepts and reject the JSON it rejects. * - *

Schema validation checks the advertised JSON shape. Deserialization and clause building check - * that the server accepts the examples. Generated tool schemas and the OpenAPI document also verify - * that the overrides reach clients. These checks do not execute commands or require a database. + *

The clause classes use custom deserializers, so each schema is a hand-written {@code @Schema} + * annotation rather than one generated from the Java fields. These tests compare each schema with + * the server's parser so the two stay in step. No commands run and no database is needed. + * + *

Test cases are tables with one JSON value per line, separated from other columns by {@code |}. */ @QuarkusTest @TestProfile(NoGlobalResourcesTestProfile.Impl.class) @@ -70,66 +72,21 @@ class McpClauseSchemaContractTest { @Inject ObjectMapper objectMapper; @Inject GlobalInputSchemaGenerator schemaGenerator; @Inject ToolManager toolManager; + @Inject Validator validator; - record WireNames( - @JsonProperty("wireName") String internalName, @JsonIgnore CommandFeatures commandFeatures) {} - - record PropertyNameDefaults( - @JsonProperty("") String defaultName, @JsonProperty(" ") String whitespaceName) {} - - record IgnoredFields( - @JsonIgnore String internal, - @JsonIgnore(false) String visible, - CommandFeatures unannotatedFeatures) {} - - static class GetterIgnoredField { - public String internal; - - @JsonIgnore - public String getInternal() { - return internal; - } - } - - @Test - void jsonIgnoreControlsFieldVisibility() { - var properties = schemaFor(IgnoredFields.class).path("properties"); - assertFalse(properties.has("internal")); - assertTrue(properties.has("visible")); - assertTrue(properties.has("unannotatedFeatures")); - } - - @Test - void jsonIgnoreOnGetterHidesField() { - assertFalse(schemaFor(GetterIgnoredField.class).path("properties").has("internal")); - } + // ---- Clause schemas, one clause type at a time ---- - @Test - void fieldsUseJsonPropertyNamesAndHideCommandFeatures() { - var properties = schemaFor(WireNames.class).path("properties"); - assertTrue(properties.has("wireName")); - assertFalse(properties.has("internalName")); - assertFalse(properties.has("commandFeatures")); - } - - @Test - void emptyAndWhitespacePropertyNamesMatchJackson() throws Exception { - var payload = - objectMapper.readTree( - """ - {"defaultName": "default", " ": "explicit"} - """); - var schema = schemaFor(PropertyNameDefaults.class); - var properties = schema.path("properties"); - assertEquals(payload.size(), properties.size()); - payload.fieldNames().forEachRemaining(name -> assertTrue(properties.has(name))); - assertSchemaAccepts(schema, payload); - assertEquals( - new PropertyNameDefaults("default", "explicit"), - objectMapper.treeToValue(payload, PropertyNameDefaults.class)); + /** The clause types whose schemas come from {@code @Schema} rather than their Java fields. */ + static Stream> clauseTypes() { + return Stream.of( + FilterDefinition.class, + SortDefinition.class, + UpdateClause.class, + FindAndRerankSort.class, + FindAndRerankCommand.HybridLimits.class); } - /** An example must satisfy both its advertised schema and the server's clause parser. */ + /** Clients copy these examples, so each must pass its own schema and the server's parser. */ @ParameterizedTest @MethodSource("clauseTypes") void everyAdvertisedClauseExampleDeserializes(Class clauseType) throws Exception { @@ -142,41 +99,24 @@ void everyAdvertisedClauseExampleDeserializes(Class clauseType) throws Except assertSchemaAccepts(schema, example); var clause = objectMapper.treeToValue(example, clauseType); assertNotNull(clause); - // These two clauses defer parsing until build, so deserialization alone cannot validate them. + // These clauses defer parsing until build, so deserialization alone cannot validate them. if (clause instanceof FilterDefinition filter) { assertNotNull(filter.build(new TestConstants().collectionContext())); } else if (clause instanceof SortDefinition sort) { assertNotNull(sort.build(new TestConstants().collectionContext())); - } - } - } - - static Stream> clauseTypes() throws Exception { - var loader = FilterDefinition.class.getClassLoader(); - // Use the build's class index so new annotated clauses join these tests automatically. - try (var indexStream = loader.getResourceAsStream("META-INF/jandex.idx")) { - assertNotNull(indexStream, "The application class index must be available"); - var index = new IndexReader(indexStream).read(); - var clauseTypes = new ArrayList>(); - for (var annotation : index.getAnnotations(Schema.class)) { - if (annotation.target().kind() != AnnotationTarget.Kind.CLASS) { - continue; - } - var type = Class.forName(annotation.target().asClass().name().toString(), false, loader); - var schema = type.getAnnotation(Schema.class); - // Select parsed clause types, excluding helper classes for nested JSON shapes. - if (!schema.name().isBlank() - && (JsonDefinition.class.isAssignableFrom(type) - || type.isAnnotationPresent(JsonDeserialize.class))) { - clauseTypes.add(type); + } else if (clause instanceof UpdateClause update) { + // $pullAll is table only, so the collection operations cannot build it. + if (!example.has(UpdateOperator.PULL_ALL.apiName())) { + assertNotNull(update.buildOperations()); } } - assertFalse(clauseTypes.isEmpty(), "The application index must contain clause schemas"); - return clauseTypes.stream().sorted(Comparator.comparing(Class::getName)); } } - /** Both entry points accept the same clause JSON and must expose the same schema definition. */ + /** + * MCP builds clause schemas from the OpenAPI document generated at build time. This checks they + * match the document the server serves, so Swagger and MCP clients see the same clause JSON. + */ @ParameterizedTest @MethodSource("clauseTypes") void openApiAndMcpShareClauseSchemas(Class clauseType) throws Exception { @@ -193,120 +133,307 @@ void openApiAndMcpShareClauseSchemas(Class clauseType) throws Exception { assertEquals(expected.path("$defs"), actual.path("$defs")); } - @Test - void filterSchemaAcceptsDocumentObjectsAndNull() throws Exception { - var annotation = FilterDefinition.class.getAnnotation(Schema.class); - var schema = schemaFor(FilterDefinition.class); - var component = referencedSchema(schema, schema); - - assertEquals(annotation.description(), schemaMetadata(schema, schema, "description").asText()); - assertEquals(annotation.examples().length, component.path("examples").size()); - for (var i = 0; i < annotation.examples().length; i++) { - assertEquals( - objectMapper.readTree(annotation.examples()[i]), component.path("examples").get(i)); + /** Accepting the examples proves nothing alone, since an empty schema accepts every value. */ + @ParameterizedTest + @CsvSource( + delimiter = '|', + textBlock = + """ + FilterDefinition | [] + FindAndRerankSort | {"vectorizeSort": "query"} + FindAndRerankSort | {"$hybrid": {"$lexical": 1}} + FindAndRerankSort | {"$hybrid": {"$vector": "query"}} + FindAndRerankSort | {"$hybrid": {"$vector": null, "$vectorize": null}} + HybridLimits | {"vectorLimit": 50, "lexicalLimit": 10} + HybridLimits | {"$vector": 50} + HybridLimits | {"$vector": 50, "$lexical": "10"} + """) + void clauseSchemasRejectInvalidJson(String clauseName, String json) throws Exception { + var clauseType = + clauseTypes().filter(type -> type.getSimpleName().equals(clauseName)).findFirst(); + assertTrue(clauseType.isPresent(), () -> "Not a clause type: " + clauseName); + assertSchemaRejects(schemaFor(clauseType.get()), objectMapper.readTree(json)); + } + + /** The findAndRerank sort parser accepts null and empty legs, so the schema must as well. */ + @ParameterizedTest + @CsvSource( + delimiter = '|', + textBlock = + """ + {"$hybrid": {"$vector": null, "$lexical": "query"}} + {"$hybrid": {"$vectorize": null, "$lexical": "query"}} + {"$hybrid": {"$vectorize": "query", "$lexical": null}} + {"$hybrid": {"$vector": [1, 2, 3], "$lexical": null}} + {"$hybrid": {"$vector": null}} + {"$hybrid": {"$vectorize": null}} + {"$hybrid": {"$lexical": null}} + {"$hybrid": {}} + {} + null + """) + void rerankSortAcceptsNullableAndEmptyJson(String json) throws Exception { + var sort = objectMapper.readTree(json); + assertSchemaAccepts(schemaFor(FindAndRerankSort.class), sort); + var clause = assertDoesNotThrow(() -> objectMapper.treeToValue(sort, FindAndRerankSort.class)); + if (!sort.isNull()) { + assertNotNull(clause); } - assertSchemaAccepts(schema, objectMapper.readTree("null")); - assertSchemaAccepts(schema, objectMapper.readTree("{\"some.path\": {\"$gt\": 40}}")); - assertFalse( - JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012) - .getSchema(schema) - .validate(objectMapper.readTree("[]")) - .isEmpty()); + assertSchemaAccepts(inputSchema("findAndRerank"), toolInput("{}").set("sort", sort)); + } + + /** The update clause examples are the only place a client sees how each operator is written. */ + @ParameterizedTest + @EnumSource(UpdateOperator.class) + void everyUpdateOperatorHasAnAdvertisedExample(UpdateOperator operator) { + var schema = schemaFor(UpdateClause.class); + var examples = schemaMetadata(schema, schema, "examples"); + assertTrue( + StreamSupport.stream(examples.spliterator(), false) + .anyMatch(example -> example.has(operator.apiName())), + () -> "Missing example for " + operator.apiName()); } - /** A correct reusable schema has no effect unless command fields actually reference it. */ + /** Nonempty arguments exercise each operation's parser, including supported array modifiers. */ + @ParameterizedTest + @CsvSource( + delimiter = '|', + textBlock = + """ + {} + {"$set": {}} + {"$set": {"profile.name": "Ada", "optional": null}} + {"$set": {"created": {"$date": 123456}, "owner": {"$uuid": "550e8400-e29b-41d4-a716-446655440000"}}} + {"$set": {"nested": [null, true, 1.25, {"name": "Ada"}]}, "$unset": {"obsolete": 1}} + {"$unset": {"obsolete": null}} + {"$setOnInsert": {"created": true}} + {"$inc": {"score": 0.25}} + {"$mul": {"score": 1.5}} + {"$min": {"score": 2.5}} + {"$max": {"score": 9.5}} + {"$rename": {"oldName": "newName"}} + {"$currentDate": {"updated": true, "reviewed": {"$type": "date"}}} + {"$pop": {"first": -1, "last": 1}} + {"$push": {"items": {"$each": [1, 2], "$position": 0}}} + {"$addToSet": {"tags": {"$each": ["a", "b"]}}} + """) + void updateClauseAcceptsSupportedUpdates(String json) throws Exception { + var update = objectMapper.readTree(json); + assertSchemaAccepts(schemaFor(UpdateClause.class), update); + assertNotNull(objectMapper.treeToValue(update, UpdateClause.class).buildOperations()); + } + + /** The update parser rejects these, so the schema must reject them too. */ + @ParameterizedTest + @CsvSource( + delimiter = '|', + textBlock = + """ + [] + 5 + "update" + {"name": "Ada"} + {"updateOperationDefs": {}} + {"$unknown": {}} + {"$set": null} + {"$set": 5} + {"$set": []} + {"$set": "value"} + """) + void updateClauseRejectsMalformedUpdates(String json) throws Exception { + var update = objectMapper.readTree(json); + assertSchemaRejects(schemaFor(UpdateClause.class), update); + assertThrows(UpdateException.class, () -> objectMapper.treeToValue(update, UpdateClause.class)); + } + + // ---- MCP tool input schemas, as the MCP server publishes them ---- + + /** + * Tool schemas describe the JSON clients send, so they must show JSON names and leave out fields + * the server keeps for itself. Each name below is a Java field on a class a tool argument uses. + */ @Test - void openApiCommandsReferenceSharedSchemas() throws Exception { - var document = openApi(); - var schemas = document.path("components").path("schemas"); - var find = schemas.path("FindCommand").path("properties"); - assertEquals(schemas.path("FilterDefinition"), referencedSchema(document, find.path("filter"))); - assertEquals(schemas.path("SortDefinition"), referencedSchema(document, find.path("sort"))); - var rerank = schemas.path("FindAndRerankCommand").path("properties"); - assertEquals( - schemas.path("FindAndRerankSort"), referencedSchema(document, rerank.path("sort"))); - var options = referencedSchema(document, rerank.path("options")).path("properties"); - assertEquals( - schemas.path("HybridLimits"), referencedSchema(document, options.path("hybridLimits"))); - var openApiOverride = - (ObjectNode) referencedSchema(document, options.path("rerank")).deepCopy(); - // The field description belongs to the command options, not the reusable schema component. - openApiOverride.remove("description"); - assertEquals(schemas.path("RerankServiceOverride"), openApiOverride); - var mcpDocument = inputSchema("findAndRerank"); - var mcpOverride = - (ObjectNode) - referencedSchema(mcpDocument, propertySchema(mcpDocument, "options", "rerank")) - .deepCopy(); - ((ObjectNode) mcpOverride).remove("description"); - var expected = - objectMapper.createObjectNode().put("$ref", FindAndRerankCommand.RerankOverrideSchema.REF); - McpOpenApiSchemaAdapter.bundleOpenApiSchemas(expected, document); - assertEquals(referencedSchema(expected, expected), mcpOverride); + void toolSchemasHideJavaFieldNames() throws Exception { + var javaFieldNames = + List.of( + // @JsonIgnore fields on FilterDefinition, SortDefinition, and FindAndRerankSort. + "filterClause", + "sortClause", + "commandFeatures", + "rerankLegMode", + "hybridSort", + "vectorizeSort", + "lexicalSort", + "vectorSort", + // Fields the JSON names differently, on UpdateClause, HybridLimits, and Options. + "updateOperationDefs", + "vectorLimit", + "lexicalLimit", + "rerankServiceOverride"); + for (var tool : toolManager) { + var document = inputSchema(tool.name()); + for (var name : javaFieldNames) { + assertNull(document.findParent(name), () -> tool.name() + " schema shows " + name); + } + } } - /** Check the complete command schema because inferred parent types can restrict valid clauses. */ + /** + * Each update tool must use the update clause schema and require an update, as the command's + * validation does. The filter may be left out or null. + */ @ParameterizedTest - @ValueSource(strings = {"50", "{\"$vector\": 50, \"$lexical\": 10}", "null"}) - void openApiAcceptsHybridLimitsWireForms(String limits) throws Exception { - var document = openApi(); - var schema = - objectMapper.createObjectNode().put("$ref", "#/components/schemas/FindAndRerankCommand"); - schema.set("components", document.path("components")); - var command = objectMapper.createObjectNode(); - command.putObject("sort").put("$hybrid", "search text"); - command.putObject("options").set("hybridLimits", objectMapper.readTree(limits)); - assertSchemaAccepts(schema, command); + @ValueSource(strings = {"updateOne", "updateMany", "findOneAndUpdate"}) + void updateToolsRequireAnUpdateClause(String tool) throws Exception { + var schema = inputSchema(tool); + var payload = toolInput("{}"); + payload.putObject("update"); + assertSchemaAccepts(schema, payload); + assertNotNull(parseUpdateCommand(tool, payload).updateClause().buildOperations()); + payload.putNull("filter"); + assertSchemaAccepts(schema, payload); + assertNotNull(parseUpdateCommand(tool, payload).updateClause().buildOperations()); + + // Any object schema accepts this. Only the update clause schema rejects it. + payload.putObject("update").put("name", "Ada"); + assertSchemaRejects(schema, payload); + payload.remove("update"); + assertSchemaRejects(schema, payload); + assertFalse(validator.validate(command(tool, payload)).isEmpty()); + payload.putNull("update"); + assertSchemaRejects(schema, payload); + assertFalse(validator.validate(command(tool, payload)).isEmpty()); + } + + // The findAndRerank rerank override has its own schema, written to match CollectionRerankDef. + + /** + * Schema acceptance must agree with service validation of the override fields. Whether + * credentials are allowed depends on the provider's configuration, which the schema cannot see, + * so the test provider here accepts a shared secret. + */ + @ParameterizedTest + @CsvSource( + delimiter = '|', + textBlock = + """ + {"provider": "nvidia", "modelName": "nvidia/rerank-v1"} | true + {"provider": "nvidia", "modelName": "nvidia/rerank-v1", "authentication": {}, "parameters": {}} | true + {"provider": "nvidia", "modelName": "nvidia/rerank-v1", "authentication": null, "parameters": null} | true + {"provider": "nvidia", "modelName": "nvidia/rerank-v1", "authentication": {"providerKey": "credential-reference"}} | true + {"provider": "nvidia", "modelName": "nvidia/rerank-v1", "parameters": {"truncate": "END"}} | false + {} | false + {"provider": "nvidia"} | false + {"modelName": "nvidia/rerank-v1"} | false + {"provider": null, "modelName": "nvidia/rerank-v1"} | false + {"provider": "nvidia", "modelName": null} | false + {"provider": null, "modelName": null} | false + """) + void rerankOverrideSchemaMatchesServiceValidation(String json, boolean accepted) + throws Exception { + var payload = objectMapper.readTree(json); + var command = toolInput("{}"); + command.putObject("options").set("rerank", payload); + var errors = schemaErrors(inputSchema("findAndRerank"), command); + assertEquals( + accepted, errors.isEmpty(), () -> "Schema validation for " + json + " returned " + errors); + + Executable validate = () -> validateRerankOverride(payload); + if (accepted) { + assertDoesNotThrow(validate); + } else { + var error = assertThrows(RequestException.class, validate); + assertEquals(RequestException.Code.INVALID_RERANK_OVERRIDE.name(), error.code); + } } @Test - void openApiAcceptsNullOptionalClauses() throws Exception { - var schema = - objectMapper.createObjectNode().put("$ref", "#/components/schemas/FindAndRerankCommand"); - schema.set("components", openApi().path("components")); - assertSchemaAccepts( - schema, - objectMapper.readTree( - """ - {"filter": null, "sort": null, "options": {"rerank": null}} - """)); + void rerankOverrideExamplesDeserialize() throws Exception { + var document = inputSchema("findAndRerank"); + var rerank = propertySchema(document, "options", "rerank"); + var examples = schemaMetadata(document, rerank, "examples"); + assertFalse(examples.isMissingNode()); + assertFalse(examples.isEmpty()); + for (var example : examples) { + var command = toolInput("{}"); + command.putObject("options").set("rerank", example); + assertSchemaAccepts(document, command); + assertNotNull( + objectMapper.treeToValue( + example, CreateCollectionCommand.Options.RerankServiceDesc.class)); + } } - private JsonNode referencedSchema(JsonNode document, JsonNode schema) { - var visited = new HashSet(); - while (schema.has("$ref")) { - var reference = schema.path("$ref").asText(); - assertTrue(reference.startsWith("#/"), "Expected a local schema reference"); - assertTrue(visited.add(reference), "Circular schema reference"); - schema = document.at(reference.substring(1)); - assertFalse(schema.isMissingNode(), "Unresolved schema reference " + reference); - } + // ---- OpenAPI command schemas, as the server publishes them for Swagger ---- + + /** The HTTP API accepts this JSON, so the OpenAPI command schemas must accept it too. */ + @ParameterizedTest + @CsvSource( + delimiter = '|', + textBlock = + """ + FindCommand | {"filter": {"age": {"$gt": 40}}, "sort": {"user.age": -1}} + FindAndRerankCommand | {"sort": {"$hybrid": "search text"}, "options": {"hybridLimits": 50}} + FindAndRerankCommand | {"sort": {"$hybrid": "search text"}, "options": {"hybridLimits": {"$vector": 50, "$lexical": 10}}} + FindAndRerankCommand | {"sort": {"$hybrid": "search text"}, "options": {"hybridLimits": null}} + FindAndRerankCommand | {"filter": null, "sort": null, "options": {"rerank": null}} + UpdateOneCommand | {"filter": {"_id": "doc1"}, "update": {"$set": {"name": "Ada"}}} + """) + void openApiCommandsAcceptValidPayloads(String command, String json) throws Exception { + assertSchemaAccepts(openApiCommandSchema(command), objectMapper.readTree(json)); + } + + /** + * A command schema that accepts everything passes the test above, so check it rejects too. Each + * payload is an accepted one with a single clause broken. + */ + @ParameterizedTest + @CsvSource( + delimiter = '|', + textBlock = + """ + FindCommand | {"filter": 5, "sort": {"user.age": -1}} + FindCommand | {"filter": {"age": {"$gt": 40}}, "sort": []} + FindAndRerankCommand | {"sort": {"vectorizeSort": "query"}} + FindAndRerankCommand | {"sort": {"$hybrid": "search text"}, "options": {"hybridLimits": {"$vector": 50}}} + FindAndRerankCommand | {"sort": {"$hybrid": "search text"}, "options": {"rerank": {"provider": "nvidia"}}} + UpdateOneCommand | {"filter": {"_id": "doc1"}, "update": {"$unknown": {}}} + """) + void openApiCommandsRejectInvalidPayloads(String command, String json) throws Exception { + assertSchemaRejects(openApiCommandSchema(command), objectMapper.readTree(json)); + } + + // ---- Helpers ---- + + /** Generates a schema for one type the way the MCP server does for a tool argument. */ + private JsonNode schemaFor(Class type) { + var builder = + new SchemaGeneratorConfigBuilder( + objectMapper, SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON) + .without(Option.SCHEMA_VERSION_INDICATOR); + new McpSchemaCustomizer().customize(builder); + var schema = new SchemaGenerator(builder.build()).generateSchema(type); + McpOpenApiSchemaAdapter.bundleOpenApiSchemas( + schema, McpOpenApiSchemaAdapter.readGeneratedOpenApiDocument()); return schema; } - private JsonNode propertySchema(JsonNode document, String... names) { - var schema = document; - for (var name : names) { - schema = referencedSchema(document, schema).path("properties").path(name); - assertFalse(schema.isMissingNode(), "Missing property " + name); - } - return schema; + /** The input schema the MCP server publishes for a registered tool. */ + private JsonNode inputSchema(String name) throws Exception { + var tool = toolManager.getTool(name); + assertNotNull(tool); + return objectMapper.readTree(schemaGenerator.generate(tool).asJson()); } - private JsonNode schemaMetadata(JsonNode document, JsonNode schema, String keyword) { - if (schema.has(keyword)) { - return schema.get(keyword); - } - if (schema.has("$ref")) { - return schemaMetadata(document, referencedSchema(document, schema), keyword); - } - for (var branch : schema.path("allOf")) { - var metadata = schemaMetadata(document, branch, keyword); - if (!metadata.isMissingNode()) { - return metadata; - } - } - return MissingNode.getInstance(); + /** A self-contained schema for one command component of the served OpenAPI document. */ + private JsonNode openApiCommandSchema(String command) throws Exception { + var components = openApi().path("components"); + assertFalse( + components.path("schemas").path(command).isMissingNode(), + "Missing OpenAPI component " + command); + var schema = objectMapper.createObjectNode().put("$ref", "#/components/schemas/" + command); + schema.set("components", components); + return schema; } private JsonNode openApi() throws Exception { @@ -321,161 +448,33 @@ private JsonNode openApi() throws Exception { return objectMapper.readTree(json); } - @Test - void rerankToolUsesSortClassDescription() throws Exception { - var description = FindAndRerankSort.class.getAnnotation(Schema.class).description(); - assertFalse(description.isBlank()); - var document = inputSchema("findAndRerank"); - assertEquals( - description, - schemaMetadata(document, propertySchema(document, "sort"), "description").asText()); - } - - @Test - void rerankToolUsesFilterClassDescription() throws Exception { - var description = FilterDefinition.class.getAnnotation(Schema.class).description(); - assertFalse(description.isBlank()); - var document = inputSchema("findAndRerank"); - assertEquals( - description, - schemaMetadata(document, propertySchema(document, "filter"), "description").asText()); - } - - /** A description that only repeats the argument name tells a client nothing. */ - @Test - void rerankToolDescribesEveryArgument() throws Exception { - var document = inputSchema("findAndRerank"); - for (var argument : document.path("properties").properties()) { - var name = argument.getKey(); - var description = schemaMetadata(document, argument.getValue(), "description").asText(); - assertFalse(description.isBlank(), name); - assertNotEquals(name, description.toLowerCase(), name); - } + private ObjectNode toolInput(String json) throws Exception { + // Routing arguments are required by MCP but are not part of the command clauses. + return ((ObjectNode) objectMapper.readTree(json)) + .put("keyspace", "default_keyspace") + .put("collection", "documents"); } - @Test - void rerankToolUsesOverrideFieldDescription() throws Exception { - var description = - FindAndRerankCommand.Options.class - .getDeclaredField("rerankServiceOverride") - .getAnnotation(Schema.class) - .description(); - assertFalse(description.isBlank()); - var document = inputSchema("findAndRerank"); - assertEquals( - description, - schemaMetadata(document, propertySchema(document, "options", "rerank"), "description") - .asText()); + private Updatable parseUpdateCommand(String tool, ObjectNode payload) throws Exception { + var command = command(tool, payload); + assertTrue(validator.validate(command).isEmpty()); + return (Updatable) command; } - /** Schema acceptance must agree with service validation of the override fields. */ - @ParameterizedTest - @MethodSource("rerankOverrides") - void rerankOverrideSchemaMatchesServiceValidation(String json, boolean accepted) - throws Exception { - var schema = inputSchema("findAndRerank"); - var payload = objectMapper.readTree(json); - var command = toolInput("{}"); - command.putObject("options").set("rerank", payload); - var errors = - JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012) - .getSchema(schema) - .validate(command); - assertEquals( - accepted, errors.isEmpty(), () -> "Schema validation for " + json + " returned " + errors); - - Executable validate = () -> validateRerankOverride(payload, AuthenticationType.NONE); - if (accepted) { - assertDoesNotThrow(validate); - } else { - var error = assertThrows(RequestException.class, validate); - assertEquals(RequestException.Code.INVALID_RERANK_OVERRIDE.name(), error.code); - } + /** Builds the command a tool call runs, without the MCP routing arguments. */ + private Command command(String tool, ObjectNode payload) throws Exception { + var arguments = payload.deepCopy(); + arguments.remove(List.of("keyspace", "collection")); + return objectMapper.treeToValue( + objectMapper.createObjectNode().set(tool, arguments), Command.class); } - static Stream rerankOverrides() { - return Stream.of( - Arguments.of( - """ - {"provider": "nvidia", "modelName": "nvidia/rerank-v1"} - """, - true), - Arguments.of( - """ - {"provider": "nvidia", "modelName": "nvidia/rerank-v1", - "authentication": {}, "parameters": {}} - """, - true), - Arguments.of( - """ - {"provider": "nvidia", "modelName": "nvidia/rerank-v1", - "authentication": null, "parameters": null} - """, - true), - Arguments.of( - """ - {"provider": "nvidia", "modelName": "nvidia/rerank-v1", - "parameters": {"truncate": "END"}} - """, - false), - Arguments.of("{}", false), - Arguments.of( - """ - {"provider": "nvidia"} - """, - false), - Arguments.of( - """ - {"modelName": "nvidia/rerank-v1"} - """, - false), - Arguments.of( - """ - {"provider": null, "modelName": "nvidia/rerank-v1"} - """, - false), - Arguments.of( - """ - {"provider": "nvidia", "modelName": null} - """, - false), - Arguments.of( - """ - {"provider": null, "modelName": null} - """, - false)); - } - - /** The schema allows credentials because the provider configuration determines support. */ - @ParameterizedTest - @EnumSource(AuthenticationType.class) - void rerankAuthenticationValidationDependsOnProvider(AuthenticationType authenticationType) + private CollectionRerankDef.RerankServiceDef validateRerankOverride(JsonNode payload) throws Exception { - var payload = - objectMapper.readTree( - """ - {"provider": "nvidia", "modelName": "nvidia/rerank-v1", - "authentication": {"providerKey": "credential-reference"}} - """); - var command = toolInput("{}"); - command.putObject("options").set("rerank", payload); - assertSchemaAccepts(inputSchema("findAndRerank"), command); - - Executable validate = () -> validateRerankOverride(payload, authenticationType); - if (authenticationType == AuthenticationType.SHARED_SECRET) { - assertDoesNotThrow(validate); - } else { - var error = assertThrows(RequestException.class, validate); - assertEquals(RequestException.Code.INVALID_RERANK_OVERRIDE.name(), error.code); - } - } - - private CollectionRerankDef.RerankServiceDef validateRerankOverride( - JsonNode payload, AuthenticationType authenticationType) throws Exception { var override = objectMapper.treeToValue(payload, CreateCollectionCommand.Options.RerankServiceDesc.class); return CollectionRerankDef.validateServiceDesc( - supportedRerankingProvider(authenticationType), + sharedSecretRerankingProvider(), override.provider(), override.modelName(), override.authentication(), @@ -483,8 +482,8 @@ private CollectionRerankDef.RerankServiceDef validateRerankOverride( RequestException.Code.INVALID_RERANK_OVERRIDE); } - private static RerankingProvidersConfig supportedRerankingProvider( - AuthenticationType authenticationType) { + /** One enabled nvidia provider and model that accepts a shared secret. */ + private static RerankingProvidersConfig sharedSecretRerankingProvider() { var model = new ModelConfigImpl( "nvidia/rerank-v1", @@ -500,187 +499,65 @@ private static RerankingProvidersConfig supportedRerankingProvider( false, "nvidia", true, - Map.of(authenticationType, new AuthenticationConfigImpl(true, List.of())), + Map.of( + AuthenticationType.SHARED_SECRET, + new AuthenticationConfigImpl(true, List.of())), List.of(model)))); } - @ParameterizedTest - @ValueSource(strings = {"50", "{\"$vector\": 50, \"$lexical\": 10}"}) - void rerankToolAcceptsWirePayloads(String limits) throws Exception { - var payload = - toolInput( - """ - { - "filter": {"age": {"$gt": 40}}, - "sort": {"$hybrid": "search text"}, - "options": {"rerank": {"provider": "nvidia", "modelName": "nvidia/rerank-v1"}} - } - """); - ((ObjectNode) payload.path("options")).set("hybridLimits", objectMapper.readTree(limits)); - assertSchemaAccepts(inputSchema("findAndRerank"), payload); - } - - @ParameterizedTest - @ValueSource( - strings = { - "{\"$hybrid\":{\"$vector\":null,\"$lexical\":\"query\"}}", - "{\"$hybrid\":{\"$vectorize\":null,\"$lexical\":\"query\"}}", - "{\"$hybrid\":{\"$vectorize\":\"query\",\"$lexical\":null}}", - "{\"$hybrid\":{\"$vector\":[1,2,3],\"$lexical\":null}}", - "{\"$hybrid\":{\"$vector\":null}}", - "{\"$hybrid\":{\"$vectorize\":null}}", - "{\"$hybrid\":{\"$lexical\":null}}", - "{\"$hybrid\":{}}", - "{}", - "null" - }) - void sortSchemaAcceptsNullableAndEmptyWireForms(String json) throws Exception { - var sort = objectMapper.readTree(json); - assertSchemaAccepts(schemaFor(FindAndRerankSort.class), sort); - var clause = assertDoesNotThrow(() -> objectMapper.treeToValue(sort, FindAndRerankSort.class)); - if (!sort.isNull()) { - assertNotNull(clause); + /** Follows local {@code $ref} links until it reaches the schema they point to. */ + private JsonNode referencedSchema(JsonNode document, JsonNode schema) { + var visited = new HashSet(); + while (schema.has("$ref")) { + var reference = schema.path("$ref").asText(); + assertTrue(reference.startsWith("#/"), "Expected a local schema reference"); + assertTrue(visited.add(reference), "Circular schema reference"); + schema = document.at(reference.substring(1)); + assertFalse(schema.isMissingNode(), "Unresolved schema reference " + reference); } - - var payload = toolInput("{}"); - payload.set("sort", sort); - assertSchemaAccepts(inputSchema("findAndRerank"), payload); + return schema; } - @Test - void rerankOverrideExamplesDeserialize() throws Exception { - var document = inputSchema("findAndRerank"); - var rerank = propertySchema(document, "options", "rerank"); - var examples = schemaMetadata(document, rerank, "examples"); - assertFalse(examples.isMissingNode()); - assertFalse(examples.isEmpty()); - for (var example : examples) { - var command = toolInput("{}"); - command.putObject("options").set("rerank", example); - assertSchemaAccepts(document, command); - assertNotNull( - objectMapper.treeToValue( - example, CreateCollectionCommand.Options.RerankServiceDesc.class)); + /** The schema of a nested property, such as {@code options} then {@code rerank}. */ + private JsonNode propertySchema(JsonNode document, String... names) { + var schema = document; + for (var name : names) { + schema = referencedSchema(document, schema).path("properties").path(name); + assertFalse(schema.isMissingNode(), "Missing property " + name); } + return schema; } - @Test - void findToolAcceptsWirePayloads() throws Exception { - var payload = - toolInput( - """ - {"filter": {"age": {"$gt": 40}}, "sort": {"user.age": -1, "user.name": 1}} - """); - assertSchemaAccepts(inputSchema("find"), payload); - } - - @ParameterizedTest - @MethodSource("invalidToolPayloads") - void toolSchemasRejectInvalidPayloads(String tool, String json) throws Exception { - var schema = - JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012).getSchema(inputSchema(tool)); - assertFalse(schema.validate(toolInput(json)).isEmpty()); - } - - static Stream invalidToolPayloads() { - return Stream.of( - Arguments.of("find", "{\"filter\": 5}"), - Arguments.of("find", "{\"sort\": []}"), - Arguments.of("findAndRerank", "{\"sort\": {\"vectorizeSort\": \"query\"}}"), - Arguments.of("findAndRerank", "{\"sort\": {\"$hybrid\": {\"$vector\": \"query\"}}}"), - Arguments.of("findAndRerank", "{\"options\": {\"hybridLimits\": {\"$vector\": 50}}}"), - Arguments.of("findAndRerank", "{\"options\": {\"rerank\": {\"provider\": \"nvidia\"}}}")); - } - - private ObjectNode toolInput(String json) throws Exception { - // Routing arguments are required by MCP but are not part of the command clauses. - return ((ObjectNode) objectMapper.readTree(json)) - .put("keyspace", "default_keyspace") - .put("collection", "documents"); - } - - /** Positive examples alone would also pass against a schema that accepts every JSON value. */ - @ParameterizedTest - @MethodSource("invalidWireShapes") - void schemaRejectsInvalidWireShapes(Class clauseType, String json) throws Exception { - var schema = - JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012) - .getSchema(schemaFor(clauseType)); - assertFalse(schema.validate(objectMapper.readTree(json)).isEmpty()); - } - - static Stream invalidWireShapes() { - return Stream.of( - Arguments.of(FindAndRerankSort.class, "{\"vectorizeSort\": \"query\"}"), - Arguments.of(FindAndRerankSort.class, "{\"$hybrid\": {\"$lexical\": 1}}"), - Arguments.of(FindAndRerankSort.class, "{\"$hybrid\": {\"$vector\": \"query\"}}"), - Arguments.of( - FindAndRerankSort.class, "{\"$hybrid\": {\"$vector\": null, \"$vectorize\": null}}"), - Arguments.of( - FindAndRerankCommand.HybridLimits.class, "{\"vectorLimit\": 50, \"lexicalLimit\": 10}"), - Arguments.of(FindAndRerankCommand.HybridLimits.class, "{\"$vector\": 50}"), - Arguments.of( - FindAndRerankCommand.HybridLimits.class, "{\"$vector\": 50, \"$lexical\": \"10\"}")); - } - - private void assertSchemaAccepts(JsonNode schema, JsonNode example) { - var validator = - JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012).getSchema(schema); - assertTrue(validator.validate(example).isEmpty(), () -> validator.validate(example).toString()); - } - - @Test - void collectionCreationAcceptsRerankAuthenticationAndParameters() throws Exception { - var payload = - objectMapper.readTree( - """ - { - "provider": "nvidia", "modelName": "nvidia/rerank-v1", - "authentication": {"providerKey": "credential-reference"}, - "parameters": {"truncate": "END"} - } - """); - assertSchemaAccepts( - schemaFor(CreateCollectionCommand.Options.RerankServiceDesc.class), payload); - assertEquals( - new CreateCollectionCommand.Options.RerankServiceDesc( - "nvidia", - "nvidia/rerank-v1", - Map.of("providerKey", "credential-reference"), - Map.of("truncate", "END")), - objectMapper.treeToValue(payload, CreateCollectionCommand.Options.RerankServiceDesc.class)); + /** A keyword such as {@code examples}, found on the schema or through its refs and allOf. */ + private JsonNode schemaMetadata(JsonNode document, JsonNode schema, String keyword) { + if (schema.has(keyword)) { + return schema.get(keyword); + } + if (schema.has("$ref")) { + return schemaMetadata(document, referencedSchema(document, schema), keyword); + } + for (var branch : schema.path("allOf")) { + var metadata = schemaMetadata(document, branch, keyword); + if (!metadata.isMissingNode()) { + return metadata; + } + } + return MissingNode.getInstance(); } - @Test - void allRegisteredToolsGenerateInputSchemas() { - var count = 0; - // Exercise named OpenAPI lookups for every tool, including ordinary options records. - for (var tool : toolManager) { - var schema = - assertDoesNotThrow( - () -> objectMapper.readTree(schemaGenerator.generate(tool).asJson()), tool.name()); - assertTrue(schema.path("properties").isObject(), tool.name()); - count++; - } - assertTrue(count > 0, "The MCP server must register tools"); + private Set schemaErrors(JsonNode schema, JsonNode payload) { + return JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012) + .getSchema(schema) + .validate(payload); } - private JsonNode inputSchema(String name) throws Exception { - // The registered tool includes nested command fields and the application's customizer wiring. - var tool = toolManager.getTool(name); - assertNotNull(tool); - return objectMapper.readTree(schemaGenerator.generate(tool).asJson()); + private void assertSchemaAccepts(JsonNode schema, JsonNode payload) { + var errors = schemaErrors(schema, payload); + assertTrue(errors.isEmpty(), () -> "Schema rejected " + payload + ": " + errors); } - private JsonNode schemaFor(Class type) { - var builder = - new SchemaGeneratorConfigBuilder( - objectMapper, SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON) - .without(Option.SCHEMA_VERSION_INDICATOR); - new McpSchemaCustomizer().customize(builder); - var schema = new SchemaGenerator(builder.build()).generateSchema(type); - McpOpenApiSchemaAdapter.bundleOpenApiSchemas( - schema, McpOpenApiSchemaAdapter.readGeneratedOpenApiDocument()); - return schema; + private void assertSchemaRejects(JsonNode schema, JsonNode payload) { + assertFalse( + schemaErrors(schema, payload).isEmpty(), () -> "Schema accepted invalid " + payload); } } diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpOpenApiSchemaAdapterTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpOpenApiSchemaAdapterTest.java index b093b66e99..c29506f691 100644 --- a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpOpenApiSchemaAdapterTest.java +++ b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpOpenApiSchemaAdapterTest.java @@ -297,6 +297,39 @@ void shouldEscapeComponentNamesInReferences() { assertEquals("#/components/schemas/A~1B~0C", McpOpenApiSchemaAdapter.componentRef("A/B~C")); } + /** + * Checks that copying an OpenAPI component into {@code $defs} keeps decimal numbers exact. The + * test adds this component to the fixture document and bundles a reference to it. + * + *

+   * "Decimal": {"type": "number", "minimum": 0.25, "maximum": 1.75, "default": 0.5}
+   * 
+ * + *

The bundled copy must keep those three values, accept the bounds, and reject values just + * outside them. + */ + @Test + void shouldPreserveDecimalSchemaBoundsAndDefault() throws Exception { + var document = fixtureDocument(); + ((ObjectNode) document.path("components").path("schemas")) + .putObject("Decimal") + .put("type", "number") + .put("minimum", 0.25) + .put("maximum", 1.75) + .put("default", 0.5); + var schema = bundle(MAPPER.readTree("{\"$ref\":\"#/components/schemas/Decimal\"}"), document); + var component = schema.at(schema.path("$ref").asText().substring(1)); + + assertEquals(0.25, component.path("minimum").doubleValue()); + assertEquals(1.75, component.path("maximum").doubleValue()); + assertEquals(0.5, component.path("default").doubleValue()); + assertAccepts(schema, "0.25"); + assertAccepts(schema, "1.75"); + assertAccepts(schema, component.path("default").toString()); + assertRejects(schema, "0.125"); + assertRejects(schema, "1.875"); + } + /** Bundles a copy of {@code input}, so tests can compare the result with the input. */ private static ObjectNode bundle(JsonNode input, JsonNode document) { ObjectNode schema = input.deepCopy(); diff --git a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaCustomizerTest.java b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaCustomizerTest.java index 9ec348f1f1..999771aa98 100644 --- a/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaCustomizerTest.java +++ b/src/test/java/io/stargate/sgv2/jsonapi/api/v1/mcp/McpSchemaCustomizerTest.java @@ -2,193 +2,112 @@ import static org.junit.jupiter.api.Assertions.*; +import com.fasterxml.jackson.annotation.JsonIgnore; +import com.fasterxml.jackson.annotation.JsonProperty; import com.fasterxml.jackson.databind.JsonNode; import com.github.victools.jsonschema.generator.Option; import com.github.victools.jsonschema.generator.OptionPreset; import com.github.victools.jsonschema.generator.SchemaGenerator; import com.github.victools.jsonschema.generator.SchemaGeneratorConfigBuilder; import com.github.victools.jsonschema.generator.SchemaVersion; +import java.util.List; +import java.util.Set; +import java.util.TreeSet; import org.eclipse.microprofile.openapi.annotations.media.Schema; import org.junit.jupiter.api.Test; /** - * Checks OpenAPI references and annotation descriptions supplied by {@link McpSchemaCustomizer}. + * Unit tests for {@link McpSchemaCustomizer}. Each test covers one rule the customizer adds to the + * MCP schema generator, using records that apply the rule next to fields that do not. */ class McpSchemaCustomizerTest { + private static final String COMPONENT_REF = "#/components/schemas/CustomizerTestSchema"; - /** - * Test record that mimics nested command structures such as {@link - * io.stargate.sgv2.jsonapi.api.model.command.impl.CreateTableCommand}. CreateTableCommand → - * TableDefinitionDesc → PrimaryKeyDesc - */ - record TestPrimaryKey( - @Schema(description = "Partition key columns") String[] keys, - @Schema(description = "Clustering key ordering") String ordering) {} + record PropertyNames( + @JsonProperty("wireName") String javaName, + // Jackson treats an empty name as "use the Java name". + @JsonProperty("") String emptyName, + String plain) {} - record TestDefinition( - @Schema(description = "Column definitions for the table") String columns, - @Schema(description = "Primary key definition") TestPrimaryKey primaryKey) {} + record IgnoredFields( + @JsonIgnore String ignored, + @JsonIgnore(false) String notIgnored, + @Schema(hidden = true) String hidden, + @Schema(description = "Not hidden") String visible) {} - record TestOptions( - @Schema(description = "Flag to ignore if already exists") Boolean ifNotExists) {} + @Schema(description = "Type description") + record DescribedType(String value) {} - record TestCreateTable( - @Schema(description = "Table definition") TestDefinition definition, - @Schema(description = "Configuration options") TestOptions options, - Boolean noAnnotation) {} - - @Schema(description = "Reusable value description") - record TestDescribedType(String value) {} - - record TestTypeDescription(TestDescribedType value) {} - - record TestHiddenFields(@Schema(hidden = true) String internal, String visible) {} - - record TestNamedField(@Schema(name = "aPropertyName") String value) {} + record Descriptions( + @Schema(description = "Field description") String described, + @Schema(description = " ") String blank, + String plain, + DescribedType typed) {} @Schema(name = "CustomizerTestSchema") - record TestSharedType(String internalValue) {} + record NamedType(String javaField) {} - @Schema(ref = "#/components/schemas/CustomizerTestSchema") - record TestReferencedType(String internalValue) {} + @Schema(ref = COMPONENT_REF) + record ReferencedType(String javaField) {} - record TestFieldValue(String internalValue) {} + record FieldValue(String javaField) {} - record TestSharedFields( - @Schema(ref = "#/components/schemas/CustomizerTestSchema", description = "First field") - TestFieldValue first, - @Schema(ref = "#/components/schemas/CustomizerTestSchema", description = "Second field") - TestFieldValue second) {} + record References( + NamedType namedType, + ReferencedType referencedType, + @Schema(ref = COMPONENT_REF, description = "Field description") FieldValue referencedField, + // A field's @Schema name only names the property, so the field keeps its own type. + @Schema(name = "notAComponent") String namedField, + // A type @Schema without a name or ref keeps the Java fields. + DescribedType describedType) {} @Test - void shouldReferenceNamedComponentInsteadOfInternalJavaFields() { - var schema = schemaFor(TestSharedType.class); - - assertEquals("#/components/schemas/CustomizerTestSchema", schema.path("$ref").asText()); - assertFalse(schema.path("properties").has("internalValue")); + void propertiesUseJsonPropertyNames() { + assertEquals(Set.of("wireName", "emptyName", "plain"), propertyNames(PropertyNames.class)); } @Test - void shouldKeepExplicitComponentReference() { - assertEquals(schemaFor(TestSharedType.class), schemaFor(TestReferencedType.class)); + void ignoredAndHiddenFieldsAreLeftOut() { + assertEquals(Set.of("notIgnored", "visible"), propertyNames(IgnoredFields.class)); } @Test - void shouldKeepFieldReferencesAndDescriptions() { - var properties = schemaFor(TestSharedFields.class).path("properties"); + void descriptionsComeFromSchemaAnnotations() { + var properties = schemaFor(Descriptions.class).path("properties"); - for (var name : new String[] {"first", "second"}) { - assertEquals( - "#/components/schemas/CustomizerTestSchema", properties.path(name).path("$ref").asText()); - assertFalse(properties.path(name).path("properties").has("internalValue")); - } - assertEquals("First field", properties.path("first").path("description").asText()); - assertEquals("Second field", properties.path("second").path("description").asText()); - assertFalse(schemaFor(TestSharedType.class).has("description")); + assertEquals("Field description", properties.path("described").path("description").asText()); + assertEquals("Type description", properties.path("typed").path("description").asText()); + assertFalse(properties.path("blank").has("description")); + assertFalse(properties.path("plain").has("description")); } @Test - void shouldOmitFieldsHiddenBySchemaAnnotation() { - var properties = schemaFor(TestHiddenFields.class).path("properties"); + void namedSchemasBecomeComponentReferences() { + var properties = schemaFor(References.class).path("properties"); - assertFalse(properties.has("internal")); - assertTrue(properties.has("visible")); + for (var name : List.of("namedType", "referencedType", "referencedField")) { + assertEquals(COMPONENT_REF, properties.path(name).path("$ref").asText(), name); + assertFalse(properties.path(name).has("properties"), name); + } + assertEquals( + "Field description", properties.path("referencedField").path("description").asText()); + assertEquals("string", properties.path("namedField").path("type").asText()); + assertFalse(properties.path("describedType").has("$ref")); + assertTrue(properties.path("describedType").path("properties").has("value")); } - @Test - void shouldNotTreatFieldSchemaNameAsComponentName() { - var schema = assertDoesNotThrow(() -> schemaFor(TestNamedField.class)); - - assertEquals("string", schema.path("properties").path("value").path("type").asText()); + private static Set propertyNames(Class type) { + var names = new TreeSet(); + schemaFor(type).path("properties").fieldNames().forEachRemaining(names::add); + return names; } + /** Generates a schema the way Quarkus MCP Server's {@code DefaultSchemaGenerator} does. */ private static JsonNode schemaFor(Class type) { - var builder = baseConfigBuilder(); + var builder = + new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON) + .without(Option.SCHEMA_VERSION_INDICATOR); new McpSchemaCustomizer().customize(builder); return new SchemaGenerator(builder.build()).generateSchema(type); } - - @Test - void shouldIncludeRootTypeDescription() { - var configBuilder = baseConfigBuilder(); - new McpSchemaCustomizer().customize(configBuilder); - - var schema = new SchemaGenerator(configBuilder.build()).generateSchema(TestDescribedType.class); - - assertEquals("Reusable value description", schema.path("description").asText()); - } - - @Test - void shouldIncludeNestedTypeDescriptionWithoutFieldDescription() { - var configBuilder = baseConfigBuilder(); - new McpSchemaCustomizer().customize(configBuilder); - - var schema = - new SchemaGenerator(configBuilder.build()).generateSchema(TestTypeDescription.class); - - assertEquals( - "Reusable value description", - schema.path("properties").path("value").path("description").asText()); - } - - @Test - void shouldIncludeSchemaDescriptionWithCustomizer() { - var configBuilder = baseConfigBuilder(); - new McpSchemaCustomizer().customize(configBuilder); - - var schema = new SchemaGenerator(configBuilder.build()).generateSchema(TestCreateTable.class); - var props = schema.path("properties"); - - // Level 1: top-level fields - assertEquals("Table definition", props.path("definition").path("description").asText()); - assertEquals("Configuration options", props.path("options").path("description").asText()); - assertTrue( - props.path("noAnnotation").path("description").isMissingNode(), - "Fields without @Schema should have no description"); - - // Level 2: nested inside TestDefinition - var defProps = props.path("definition").path("properties"); - assertEquals( - "Column definitions for the table", defProps.path("columns").path("description").asText()); - assertEquals( - "Primary key definition", defProps.path("primaryKey").path("description").asText()); - - // Level 2: nested inside TestOptions - var optProps = props.path("options").path("properties"); - assertEquals( - "Flag to ignore if already exists", - optProps.path("ifNotExists").path("description").asText()); - - // Level 3: nested inside TestPrimaryKey - var pkProps = defProps.path("primaryKey").path("properties"); - assertEquals("Partition key columns", pkProps.path("keys").path("description").asText()); - assertEquals("Clustering key ordering", pkProps.path("ordering").path("description").asText()); - } - - @Test - void shouldNotIncludeDescriptionWithoutCustomizer() { - var schema = - new SchemaGenerator(baseConfigBuilder().build()).generateSchema(TestCreateTable.class); - - // Spot-check: a deeply nested field should have no description - var pkProps = - schema - .get("properties") - .get("definition") - .get("properties") - .get("primaryKey") - .get("properties"); - assertNull( - pkProps.get("keys").get("description"), - "Without customizer, PLAIN_JSON preset should not resolve @Schema descriptions"); - } - - /** - * Creates a {@link SchemaGeneratorConfigBuilder} matching the configuration used by Quarkus MCP - * Server's {@code DefaultSchemaGenerator}. - */ - private static SchemaGeneratorConfigBuilder baseConfigBuilder() { - return new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON) - .without(Option.SCHEMA_VERSION_INDICATOR); - } }