Implement planned topic: 0017-jackson-3

references/java/data-handling.md

@@ -37,6 +37,21 @@ WorkflowClient client = WorkflowClient.newInstance(
 );
 ```
 
+## Jackson 3 (opt-in)
+
+The Java SDK's default JSON path runs through Jackson 2's `JacksonJsonPayloadConverter`.  A separate Jackson 3 payload-conversion path is available as an opt-in, selected via a new startup API.
+
+**Wire compatibility.** Payloads written by the Jackson 3 path remain readable by Jackson 2 converters on the other side of the wire, and vice versa — a worker on Jackson 3 can interoperate with a client still on Jackson 2 without re-encoding history.
+
+**Opt-in call site.** Switch to the Jackson 3 path by calling the Jackson 3 opt-in startup API  when constructing your `DefaultDataConverter`, then install the converter on `WorkflowClientOptions` the same way as today.  Customising the underlying `ObjectMapper` (modules, serialisation features) is still how you tune behaviour — Jackson 3's `ObjectMapper` lives in a different package and is constructed through a builder, so the surrounding Jackson 2 idiom in the section above does not transfer verbatim.
+
+**When to opt in:**
+
+- **Opt in** when the surrounding codebase has already standardised on Jackson 3, or a downstream library you depend on requires it.
+- **Stay on the default Jackson 2 path** otherwise — there is no behavioural gain to switching in an app that has no Jackson 3 requirement.
+
+The existing `## Jackson Integration` section above still describes the Jackson 2 path; this opt-in does not change it.
+
 ## Custom Data Converter
 
 Implement `PayloadConverter` for custom serialization:

references/java/integrations/spring-ai.md

@@ -217,7 +217,6 @@ Media image = new Media(MimeTypeUtils.IMAGE_PNG, URI.create("https://cdn.example
 
 For anything larger than a small thumbnail, route the bytes to a binary store from an Activity and pass only the URL across the conversation.
 
-
 ## Vector stores, embeddings, and MCP
 
 When the corresponding Spring AI modules (`spring-ai-rag`, `spring-ai-mcp`) are on the classpath, the integration registers Activities for vector stores, embeddings, and MCP tool calls automatically. Inject the matching Spring AI types into your Activities or Workflows and use them as you would in any Spring AI application — each operation executes through a Temporal Activity.