feat(indexing): index-json-documents takes a typed documents array

[adityamparikh]

Summary

index-json-documents took its documents as a JSON string, so the model had to escape every quote and newline of the payload inside a JSON string argument. On the 61-show sample that escaping is about 12% of the output tokens the model generates for the call, and one mis-escaped quote fails the whole call after the payload has been produced.

The parameter is now List<Map<String, Object>> documents, advertised in the tool schema as an array of objects. The model emits native JSON, the MCP client parses it once, and on the SDK 2.0 line (#23) the shape is validated before dispatch.

before:  {"collection":"shows","json":"[{\"id\":\"netflix-001\",\"title\":\"Stranger Things\",...}]"}
after:   {"collection":"shows","documents":[{"id":"netflix-001","title":"Stranger Things",...}]}

What changed

• JsonDocumentCreator.create(List<Map<String,Object>>): same flattening as the string path (nested objects to a_b, arrays to multi-valued fields, nulls skipped). JsonDocumentCreatorTest pins that both entry points produce identical documents.
• IndexingService.indexJsonDocuments takes the typed list; description tells the model to pass the array itself, not a string. The index-data prompt says the same for the JSON path and its opening line names the format rather than the parameter.
• Tests keep their JSON text blocks and parse them through a new TestDocuments.json(...) helper; the MCP-level tests send the array.
• README tool table.

Cleanup pass (00e8c7c)

• One flattening path. create(List) and create(String) now share flatten(JsonNode) / toDocument(JsonNode) instead of maintaining parallel loops, so objectsAndStringProduceTheSameDocuments guards a shared path rather than being the only thing keeping two hand-written loops in step. create(List) converts the whole list with one valueToTree call rather than one per document.
• Javadoc rebinding. create(List) had been inserted between the create(String) javadoc and the method it documents, so javac bound only the trailing block: create(String) lost its docs and create(List) inherited a @param json it does not have.
• Null moved to the creator, which already owns the "nothing to index" policy, dropping a one-off IllegalArgumentException from indexJsonDocuments that none of the three sibling index tools had.
• IndexTool gained the canonical format. The prompt's first %s was indexTool.paramName(), which worked only because paramName happened to equal the format keyword; renaming the JSON parameter to documents broke that, and re-normalising the raw argument lost the md → markdown canonicalisation, so format=md rendered "You are indexing md data".
• createSchemalessDocuments → createSchemalessDocumentsFromJson, keeping the orchestrator's ...From<Format> family; stale @see; TestDocuments catches JsonProcessingException (what readValue declares, and what survives Jackson 3) and hoists its TypeReference; CollectionServiceIntegrationTest passes the documents it already holds instead of serialising and reparsing them, retiring a now-unused autowired ObjectMapper.

Input size limits removed (0c0a2f2, 327ae50, 792ecd5)

The typed documents array has no string form to measure, so the JSON tool path was already uncapped. Rather than add a second limit to match, the existing 10 MB caps were removed across all four formats.

All four carried the same copy-pasted 10 * 1024 * 1024 constant and the same getBytes() length check, which materialised a second full copy of the payload purely to measure it, immediately before the parser read the string again — in two different layers (JSON/CSV/markdown in the creators, XML in the orchestrator) with two different message formats.

Payload size is now bounded by the heap and by whatever limit the transport in front of the server imposes. Blank/null validation is unchanged on every path and still covered. Only one test touched a limit — testCreateSchemalessDocumentsFromXmlWithLargeDocument, which built a 12 MB document to assert the XML check fired — and it is removed with it.

Not changed

CSV, XML and Markdown stay strings: those formats have few quotes and no repeated keys, so a string is already their cheapest wire form. Part of a set with feat/markdown-multi-document and fix/xml-record-fields; the three are independent and merge in any order.

Verification

• ./gradlew build on Java 25: green — 406 tests, 399 passed, 0 failed, 7 skipped (the pre-existing @Disabled OTLP/LGTM class). The count is one lower than before the cap removal, which is the deleted XML size test.
• ./gradlew nativeTest -Pnative on GraalVM CE 25.0.2: 259 successful, 0 failed (the generic List<Map> parameter deserialises natively without extra hints). Measured before the cleanup commits; the cleanup adds no new types or reflection.
• Measured against a running server: 61 documents index in 0.1 s server-side either way; the saving is entirely in what the model has to emit.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JZoVjWoHU315uEngMQdhWE