[BUG] Instant fields serialize as numeric epoch timestamps instead of ISO-8601 strings in azure-cosmos

[pure-zero]

Describe the bug

When a POJO stored/read via CosmosContainer/CosmosAsyncContainer has a java.time.Instant field, the field is serialized to Cosmos DB as a numeric epoch
value (seconds since epoch, with fractional nanoseconds) instead of an ISO-8601 date-time string.

Root cause: Utils.createAndInitializeObjectMapper() (com.azure.cosmos.implementation.Utils) registers Jackson's JavaTimeModule but never disables
SerializationFeature.WRITE_DATES_AS_TIMESTAMPS, which defaults to true on a plain ObjectMapper. JavaTimeModule's InstantSerializer checks that flag
before choosing between epoch-numeric and ISO-8601 string output — since it's left enabled, Instant fields always serialize as a number. This ObjectMapper
is the one backing Utils.getDocumentObjectMapper(...), which CosmosItemSerializer.DEFAULT_SERIALIZER / DefaultCosmosItemSerializer use for all item
bodies, so it affects every item write/read through both the sync CosmosContainer and CosmosAsyncContainer (the sync client is a thin blocking wrapper
around the async one and shares the same serializer).

Other java.time types handled by JavaTimeModule (e.g. LocalDateTime) are affected the same way for the same reason.

Exception or Stack Trace

None — no exception is thrown. The item is written/read successfully, but the Instant field's JSON representation is wrong (a number instead of a string),
which silently breaks any downstream consumer (other SDKs, the Data Explorer UI, queries filtering on the field as a string, etc.) that expects an ISO-8601
date-time string.

To Reproduce

1. Define a POJO with an Instant field.
2. Write an instance to a container with createItem/upsertItem.
3. Read the raw item JSON back (e.g. via the Azure Portal Data Explorer, or container.readItem(id, pk, JsonNode.class)).
4. Observe the field is a number, not a quoted ISO-8601 string.

Code Snippet

public class Event {
    public String id;
    public Instant createdAt;
}

CosmosClient client = new CosmosClientBuilder()
    .endpoint(endpoint)
    .key(key)
    .buildClient();

CosmosContainer container = client.getDatabase("db").getContainer("events");

Event event = new Event();
event.id = "1";
event.createdAt = Instant.parse("2023-07-22T09:46:40.123456789Z");

container.createItem(event);

// Read back the raw JSON to inspect the wire format
ObjectNode raw = container.readItem("1", new PartitionKey("1"), ObjectNode.class).getItem();
System.out.println(raw.toPrettyString());

Expected behavior

{
  "id": "1",
  "createdAt": "2023-07-22T09:46:40.123456789Z"
}

Actual behavior

{
  "id": "1",
  "createdAt": 1690019200.123456789
}

Screenshots

N/A

Setup (please complete the following information):
- OS: N/A (reproducible on any OS)
- IDE: N/A
- Library/Libraries: com.azure:azure-cosmos:4.81.0
- Java version: 8+ (reproduced on Java 8 baseline; affects all supported Java versions since it's a Jackson configuration issue, not JVM-specific)
- App Server/Environment: N/A (reproducible in a plain main(), not environment-specific)
- Frameworks: N/A (does not require Spring/other frameworks; also affects azure-spring-data-cosmos since it depends on the same default serializer)

Additional context

- Same file, Utils.createAndInitializeDurationObjectMapper(), shows the team is aware Instant needs special handling to avoid Jackson's numeric default — it
explicitly registers ToStringSerializer.instance for Instant/Duration on a separate mapper used for diagnostics. This strongly suggests the missing
WRITE_DATES_AS_TIMESTAMPS = false on the main document mapper is an oversight, not an intentional design choice — JavaTimeModule appears to have been added in
an earlier PR purely to make Instant deserializable, without considering the serialization-format side effect.
- Workaround: supply a custom CosmosItemSerializer via CosmosClientBuilder.customItemSerializer(...) (client-wide) or
CosmosItemRequestOptions.setCustomItemSerializer(...) (per-request) backed by an ObjectMapper with JavaTimeModule registered and
SerializationFeature.WRITE_DATES_AS_TIMESTAMPS explicitly set to false.
- Compatibility note for the fix: changing this default is a breaking wire-format change for any existing data already written with Instant fields in epoch
format — needs a migration/compat plan, not a silent patch, since consumers may have already adapted to reading these fields as numbers.

Information Checklist
- [x] Bug Description Added
- [x] Repro Steps Added
- [x] Setup information Added

[github-actions]

Thank you for your feedback. Tagging and routing to the team member(s) best able to assist.

//cc: @kushagraThapar @pjohari-ms @TheovanKraay

[github-actions]

🎯 Agentic Issue Triage

Summary: Instant fields (and other java.time types) in POJOs stored via CosmosContainer/CosmosAsyncContainer are serialized as numeric epoch timestamps instead of ISO-8601 strings, because the shared ObjectMapper in Utils.createAndInitializeObjectMapper() registers JavaTimeModule but never disables SerializationFeature.WRITE_DATES_AS_TIMESTAMPS.

📋 Issue Details

Package: com.azure:azure-cosmos:4.81.0
Affected API: Utils.createAndInitializeObjectMapper() → Utils.getDocumentObjectMapper() → CosmosItemSerializer.DEFAULT_SERIALIZER / DefaultCosmosItemSerializer
Scenarios:

• Write a POJO with a java.time.Instant field via createItem/upsertItem — the field is stored as a decimal number (epoch seconds with nanosecond fraction) instead of an ISO-8601 string
• Read the raw JSON back via Data Explorer or readItem(..., JsonNode.class) — the field appears as a number
• Same issue affects all other java.time types handled by JavaTimeModule (e.g. LocalDateTime)

Root ask: Disable SerializationFeature.WRITE_DATES_AS_TIMESTAMPS on the document ObjectMapper so Instant (and other java.time) fields serialize as ISO-8601 strings by default. Caller attention needed for compatibility: this is a breaking wire-format change for data already stored in epoch format.

🔎 Debugging / Reproduction Notes

The root cause is confined to one location: Utils.createAndInitializeObjectMapper() in com.azure.cosmos.implementation.Utils. Adding mapper.disable(SerializationFeature.WRITE_DATES_AS_TIMESTAMPS) there would fix the issue for all consumers of the shared document mapper.

The author notes a strong signal for this being an oversight: Utils.createAndInitializeDurationObjectMapper() (a separate mapper used only for diagnostics) explicitly registers ToStringSerializer.instance for Instant/Duration to avoid the numeric default — the same awareness is missing on the main document mapper.

Suggested investigation steps:

1. Locate Utils.createAndInitializeObjectMapper() in sdk/cosmos/azure-cosmos/src/main/java/com/azure/cosmos/implementation/Utils.java and confirm JavaTimeModule is registered without WRITE_DATES_AS_TIMESTAMPS being disabled.
2. Evaluate compatibility impact: existing documents with Instant fields stored as numbers would fail to deserialize if the serializer is changed and the deserializer is not updated to handle both formats.
3. Consider whether to add a config option, a behavior flag, or a migration guide rather than a silent breaking change.
4. Verify the workaround mentioned by the author (CosmosClientBuilder.customItemSerializer(...) with a correctly configured ObjectMapper) works as expected and update docs if needed.
5. Check whether azure-spring-data-cosmos is independently affected or solely through its dependency on the shared serializer.

🏷️ Label Confidence

• Category: Client — The issue is with the Java SDK client library code (com.azure:azure-cosmos), not with the REST API or Azure service behavior. The bug is in ObjectMapper configuration within the SDK itself.
• Service: Cosmos — The issue explicitly references com.azure:azure-cosmos:4.81.0, and the service directory is sdk/cosmos/. Reference issue [QUERY] When will Azure Cosmos DB OLTP Spark 4 connector be ready? #46290 confirms Client + Cosmos for this package.
• Confidence: High — Package is explicitly named, there is no ambiguity between services or categories, and the pattern is validated by quality reference issues.

👥 Owner Routing

• Matched CODEOWNERS entry: # ServiceLabel: %Cosmos (line 295) — the only ServiceLabel entry that includes "Cosmos"; no multi-label entry combining "Cosmos" with another predicted label exists further down in the file.
• AzureSdkOwners: none listed
• ServiceOwners: @kushagraThapar, @pjohari-ms, @TheovanKraay
• Routing action: Added "Service Attention" and "needs-team-attention" labels; issue left unassigned (ServiceOwners path, no AzureSdkOwner to assign); mention_owners comment posted to notify ServiceOwners.
• Scan notes: Bottom-to-top scan from line 991. No entries below line 295 contained %Cosmos. No %Client catch-all ServiceLabel entry exists in the file. Line 295 was the first (and only) match.

Generated by Agentic Triage for #49715 · 37.8 AIC · ⌖ 7.42 AIC · ⊞ 11K · ◷