[R][client] fix: map OpenAPI date and date-time to R Date and POSIXct

[ahjota]

The R client generator emitted format: date and format: date-time fields as plain character vectors, so generated models held raw JSON strings, emitted schema defaults as string literals, accepted arbitrary strings in initialize() validation, and skipped conversion on both serialize and deserialize paths.

• RClientCodegen: map date -> R Date and date-time -> R POSIXct via typeMapping, mark both as languageSpecificPrimitives, and add rDate()/rDateTime() helpers used to emit defaults and examples as as.Date()/as.POSIXct(...) expressions. rDateTime() normalizes every default to UTC: a trailing Z is stripped (same instant), an explicit offset is shifted to UTC, and a zone-less value is interpreted as UTC.

• modelGeneric.mustache: validate date fields with inherits(x, "Date") / inherits(x, "POSIXt") instead of is.character(x) — including per-element sapply() checks for array/map items — and convert in fromJSON/fromJSONString behind the existing is.null() guard so nullable fields stay NULL. Serialization is delegated to jsonlite's ISO 8601 options (Date = "ISO8601", POSIXt = "ISO8601", UTC = TRUE) in toJSONString, with no manual formatting of Date/POSIXct in toSimpleType; jsonlite (>= 1.0) is pinned in DESCRIPTION.

• api.mustache / api_client.mustache (root + httr2): format Date and POSIXct for headers and query strings as ISO 8601 UTC, and convert primitive date/date-time values in ApiClient$deserialize().

as.POSIXct's default tryFormats do not include the ISO 8601 'T'-separator format and strptime's %z does not accept a trailing 'Z' on input, so the generated code passes an explicit tryFormats list with tz = "UTC" to parse JSON date-time strings on all current R versions.

Fixes #24811

PR checklist

• Read the contribution guidelines.
• Run the following to build the project and update samples:

  ./mvnw clean package || exit
  ./bin/generate-samples.sh ./bin/configs/*.yaml || exit
  ./bin/utils/export_docs_generators.sh || exit
  

  (For Windows users, please run the script in WSL)
  Commit all changed files.
  This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
  These must match the expectations made by your contribution.
  You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
  IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

---

Summary by cubic

Maps OpenAPI date and date-time fields to R Date and POSIXct instead of plain character vectors, fixing #24811. Generated models and clients now hold real temporal objects and round-trip them as ISO 8601 UTC, parsing Z, numeric offsets, zone-less, and space-separated datetime variants; callers must pass as.Date()/as.POSIXct() (or as.POSIXlt()) values since character strings are rejected.

• RClientCodegen maps both formats to their R primitives and emits defaults/examples as as.Date()/as.POSIXct() expressions.
• Shared .parse_datetime/.format_datetime helpers centralize parsing and formatting; serialization needs no jsonlite option flags, so the jsonlite (>= 1.0) pin is dropped.
• Model and API templates validate via inherits(), convert in fromJSON/fromJSONString/deserialize (reading JSON key names), and format headers and query strings as ISO 8601 UTC.
• Conversion guards keep nullable fields NULL and use is.character(obj) checks so bare date arrays and same-named models (e.g. petstore Date) dispatch correctly.
• Tests cover mapping, defaults, nullable fields, POSIXlt, arrays of date values, and Z/offset/no-Z/space-separated datetime string formats.

^{Written for commit 18a29ad. Summary will update on new commits.}

[ahjota]

@Ramanth @saigiridhar21 your review would be appreciated

[cubic-dev-ai]

2 issues found across 107 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="samples/client/petstore/R/R/api_client.R">

<violation number="1" location="samples/client/petstore/R/R/api_client.R:403">
P2: The new `as.POSIXct` tryFormats only cover `...Z`, no-zone, and space-separated forms. ISO 8601 timestamps with a numeric UTC offset (`+02:00`/`-05:00`) or without seconds parse to NA. Add `%z`-style formats (e.g. `"%Y-%m-%dT%H:%M:%OS%z"`) and a seconds-less variant, or document the accepted subset.</violation>
</file>

<file name="modules/openapi-generator/src/main/resources/r/libraries/httr2/api_client.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/r/libraries/httr2/api_client.mustache:433">
P1: When an API returns a valid RFC3339 date-time with an explicit offset, `deserializeObj()` cannot match any `tryFormats` entry and loses the timestamp as `NA`. Normalize the colon in the offset and add a `%z` format before calling `as.POSIXct()`.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: When an API returns a valid RFC3339 date-time with an explicit offset, deserializeObj() cannot match any tryFormats entry and loses the timestamp as NA. Normalize the colon in the offset and add a %z format before calling as.POSIXct().

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/main/resources/r/libraries/httr2/api_client.mustache, line 433:

<comment>When an API returns a valid RFC3339 date-time with an explicit offset, `deserializeObj()` cannot match any `tryFormats` entry and loses the timestamp as `NA`. Normalize the colon in the offset and add a `%z` format before calling `as.POSIXct()`.</comment>

<file context>
@@ -424,7 +424,16 @@ ApiClient  <- R6::R6Class(
+          # NOTE: an explicit tryFormats list is required in all current R versions thru 4.3.x
+          # as.POSIXct's default tryFormats omit the ISO 8601 'T'-separator format, and
+          # strptime's %z does not accept a trailing 'Z' as a UTC designator on input.
+          return_obj <- if (is.null(obj)) NULL else as.POSIXct(obj, tryFormats = c("%Y-%m-%dT%H:%M:%OSZ", "%Y-%m-%dT%H:%M:%OS", "%Y-%m-%d %H:%M:%S"), tz = "UTC")
+        } else {
+          return_obj <- obj
</file context>

Suggested change

	return_obj <- if (is.null(obj)) NULL else as.POSIXct(obj, tryFormats = c("%Y-%m-%dT%H:%M:%OSZ", "%Y-%m-%dT%H:%M:%OS", "%Y-%m-%d %H:%M:%S"), tz = "UTC")
	return_obj <- if (is.null(obj)) NULL else {
	obj <- sub("([+-][0-9]{2}):([0-9]{2})$", "\\1\\2", obj)
	as.POSIXct(obj, tryFormats = c("%Y-%m-%dT%H:%M:%OSZ", "%Y-%m-%dT%H:%M:%OS%z", "%Y-%m-%dT%H:%M:%OS", "%Y-%m-%d %H:%M:%S"), tz = "UTC")
	}

[ahjota]

That was some review. I admit it has been a while since I've actively worked in R, but I noticed that the review bot comments collapsed into a few root causes, most related to my use of jsonlite::toJSON(), and I wasn't aware of its limitations. I went back to using toSimpleType(), but then added a handful of helper R methods in the mustache templates to consolidate the extra work with dealing with UTC, offsets, and fractional seconds. Thereś one limitation with this approach, and that is untyped additional properties holding temporal values will fall back to jsonlite's defaults.

Also added more testing to cover the scenarios that the review bot raised, in junit tests. One scenario I specifically wanted to test was the existence of an OAS model called Date -- Date is not a reserved word in R, as it's an S3 class.

[cubic-dev-ai]

6 issues found across 91 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="modules/openapi-generator/src/main/resources/r/date_time_helpers.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/r/date_time_helpers.mustache:8">
P3: `.parse_datetime()` only normalizes an uppercase trailing `Z`; ISO 8601 also permits a lowercase `z` as the UTC designator (e.g. `2020-01-01T12:00:00z`). Such a string survives both `sub()` calls unchanged, fails every `tryFormats` entry (R's `%z` does not accept `z`), and silently becomes `NA` with a parse warning, corrupting the field instead of raising an error. Make the substitution case-insensitive.</violation>

<violation number="2" location="modules/openapi-generator/src/main/resources/r/date_time_helpers.mustache:24">
P2: When a POSIXct contains sub-millisecond precision, `%OS3` serializes it with only three fractional digits, changing the instant before requests or model JSON are sent. Emit the precision POSIXct preserves, such as `%OS6`, instead of hard-coding milliseconds.</violation>
</file>

<file name="modules/openapi-generator/src/test/resources/bugs/issue_24813-datetime-parsing.yaml">

<violation number="1" location="modules/openapi-generator/src/test/resources/bugs/issue_24813-datetime-parsing.yaml:149">
P2: The comment in this fixture is wrong for the R generator: RClientCodegen.toVarName() returns the name unchanged, so toVarName("ship-date") is "ship-date". The generated R field name and the JSON baseName are both `ship-date` (no ship_date). The FieldAlias fixture therefore does not create a name/baseName divergence, and the `this_object$\`ship-date\`` assertion in RClientCodegenTest passes even without the fromJSONString baseName fix you're testing. Correct the comment and use a property that truly diverges (or drop the claim) so the baseName fix is actually exercised.</violation>
</file>

<file name="samples/client/petstore/R-httr2/R/api_client.R">

<violation number="1" location="samples/client/petstore/R-httr2/R/api_client.R:31">
P3: The comment on .format_datetime() says the 1e-6 nudge makes %OS3 "round to the nearest millisecond", but %OSn in format() truncates (R docs: "gives the seconds truncated to exactly 0 <= n <= 6 decimal places"). The nudge only compensates for double-precision representation error; it does not round. For fractional seconds in [0.9995, 0.999999), e.g. 12:00:00.9996, the output is "12:00:00.999Z" instead of the correctly rounded "12:00:01.000Z" — 1 ms low. Round explicitly in POSIXct representation before formatting (e.g. format(round(x, 3), ...)) or correct the comment to describe truncation with a float-error nudge.</violation>
</file>

<file name="modules/openapi-generator/src/main/resources/r/api.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/r/api.mustache:371">
P1: When an exploded query parameter is a `Date` or `POSIXct` vector, the `for` loop can strip the temporal class before these conversions run, so requests contain numeric epoch/day values instead of ISO dates. Format the original vector by index (for example, iterate over `seq_along()` and pass `paramName[[i]]`/`paramName[i]`) so each item retains its class.</violation>
</file>

<file name="modules/openapi-generator/src/main/resources/r/modelGeneric.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/r/modelGeneric.mustache:242">
P2: For arrays or maps of dates, these sections test the container's `isDate` flag instead of its item's flag, so `toSimpleType()` returns raw Date/POSIXct elements. `toJSONString()` then serializes those elements without the new ISO-8601 UTC helpers; use `items.isDate` and `items.isDateTime` in every container serialization branch, as the validation and API templates already do.</violation>
</file>

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic</sub>

[cubic-dev-ai]

P1: When an exploded query parameter is a Date or POSIXct vector, the for loop can strip the temporal class before these conversions run, so requests contain numeric epoch/day values instead of ISO dates. Format the original vector by index (for example, iterate over seq_along() and pass paramName[[i]]/paramName[i]) so each item retains its class.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/main/resources/r/api.mustache, line 371:

<comment>When an exploded query parameter is a `Date` or `POSIXct` vector, the `for` loop can strip the temporal class before these conversions run, so requests contain numeric epoch/day values instead of ISO dates. Format the original vector by index (for example, iterate over `seq_along()` and pass `paramName[[i]]`/`paramName[i]`) so each item retains its class.</comment>

<file context>
@@ -364,6 +364,12 @@
+        query_item <- as.character(query_item)
+        {{/isDate}}
+        {{#isDateTime}}
+        query_item <- .format_datetime(query_item)
+        {{/isDateTime}}
         {{/items}}
</file context>

[cubic-dev-ai]

P2: For arrays or maps of dates, these sections test the container's isDate flag instead of its item's flag, so toSimpleType() returns raw Date/POSIXct elements. toJSONString() then serializes those elements without the new ISO-8601 UTC helpers; use items.isDate and items.isDateTime in every container serialization branch, as the validation and API templates already do.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/main/resources/r/modelGeneric.mustache, line 242:

<comment>For arrays or maps of dates, these sections test the container's `isDate` flag instead of its item's flag, so `toSimpleType()` returns raw Date/POSIXct elements. `toJSONString()` then serializes those elements without the new ISO-8601 UTC helpers; use `items.isDate` and `items.isDateTime` in every container serialization branch, as the validation and API templates already do.</comment>

<file context>
@@ -239,15 +239,35 @@
           {{#isContainer}}
           {{#isArray}}
           {{#isPrimitiveType}}
+          {{#isDate}}
+          lapply(self$`{{name}}`, as.character)
+          {{/isDate}}
</file context>

[cubic-dev-ai]

P2: The comment in this fixture is wrong for the R generator: RClientCodegen.toVarName() returns the name unchanged, so toVarName("ship-date") is "ship-date". The generated R field name and the JSON baseName are both ship-date (no ship_date). The FieldAlias fixture therefore does not create a name/baseName divergence, and the this_object$\ship-date`` assertion in RClientCodegenTest passes even without the fromJSONString baseName fix you're testing. Correct the comment and use a property that truly diverges (or drop the claim) so the baseName fix is actually exercised.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/test/resources/bugs/issue_24813-datetime-parsing.yaml, line 149:

<comment>The comment in this fixture is wrong for the R generator: RClientCodegen.toVarName() returns the name unchanged, so toVarName("ship-date") is "ship-date". The generated R field name and the JSON baseName are both `ship-date` (no ship_date). The FieldAlias fixture therefore does not create a name/baseName divergence, and the `this_object$\`ship-date\`` assertion in RClientCodegenTest passes even without the fromJSONString baseName fix you're testing. Correct the comment and use a property that truly diverges (or drop the claim) so the baseName fix is actually exercised.</comment>

<file context>
@@ -74,3 +133,24 @@ components:
+      type: object
+    # A model with a property whose JSON key (baseName) differs from the R field
+    # name exercises the fromJSONString baseName fix for date/date-time fields.
+    # toVarName("ship-date") = underscore(camelize("ship-date")) = "ship_date",
+    # so name="ship_date" but baseName="ship-date".
+    FieldAlias:
</file context>

[cubic-dev-ai]

P2: When a POSIXct contains sub-millisecond precision, %OS3 serializes it with only three fractional digits, changing the instant before requests or model JSON are sent. Emit the precision POSIXct preserves, such as %OS6, instead of hard-coding milliseconds.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/main/resources/r/date_time_helpers.mustache, line 24:

<comment>When a POSIXct contains sub-millisecond precision, `%OS3` serializes it with only three fractional digits, changing the instant before requests or model JSON are sent. Emit the precision POSIXct preserves, such as `%OS6`, instead of hard-coding milliseconds.</comment>

<file context>
@@ -0,0 +1,26 @@
+  if (inherits(x, "Date")) {
+    return(as.character(x))
+  }
+  s <- format(x + 1e-6, "%Y-%m-%dT%H:%M:%OS3Z", tz = "UTC")
+  sub("\\.000Z$", "Z", s)
+}
</file context>

Suggested change

	s <- format(x + 1e-6, "%Y-%m-%dT%H:%M:%OS3Z", tz = "UTC")
	sub("\\.000Z$", "Z", s)
	s <- format(x + 1e-6, "%Y-%m-%dT%H:%M:%OS6Z", tz = "UTC")
	sub("\\.0+Z$", "Z", s)

[cubic-dev-ai]

P3: .parse_datetime() only normalizes an uppercase trailing Z; ISO 8601 also permits a lowercase z as the UTC designator (e.g. 2020-01-01T12:00:00z). Such a string survives both sub() calls unchanged, fails every tryFormats entry (R's %z does not accept z), and silently becomes NA with a parse warning, corrupting the field instead of raising an error. Make the substitution case-insensitive.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At modules/openapi-generator/src/main/resources/r/date_time_helpers.mustache, line 8:

<comment>`.parse_datetime()` only normalizes an uppercase trailing `Z`; ISO 8601 also permits a lowercase `z` as the UTC designator (e.g. `2020-01-01T12:00:00z`). Such a string survives both `sub()` calls unchanged, fails every `tryFormats` entry (R's `%z` does not accept `z`), and silently becomes `NA` with a parse warning, corrupting the field instead of raising an error. Make the substitution case-insensitive.</comment>

<file context>
@@ -0,0 +1,26 @@
+# silently drops offsets, so lapply() keeps each instant correct.
+# @keywords internal
+.parse_datetime <- function(x) {
+  x <- sub("Z$", "+0000", x)
+  x <- sub("([+-][0-9]{2}):([0-9]{2})$", "\\1\\2", x)
+  do.call(c, lapply(x, function(s)
</file context>

Suggested change

	x <- sub("Z$", "+0000", x)
	x <- sub("[Zz]$", "+0000", x)

[cubic-dev-ai]

P3: The comment on .format_datetime() says the 1e-6 nudge makes %OS3 "round to the nearest millisecond", but %OSn in format() truncates (R docs: "gives the seconds truncated to exactly 0 <= n <= 6 decimal places"). The nudge only compensates for double-precision representation error; it does not round. For fractional seconds in [0.9995, 0.999999), e.g. 12:00:00.9996, the output is "12:00:00.999Z" instead of the correctly rounded "12:00:01.000Z" — 1 ms low. Round explicitly in POSIXct representation before formatting (e.g. format(round(x, 3), ...)) or correct the comment to describe truncation with a float-error nudge.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/client/petstore/R-httr2/R/api_client.R, line 31:

<comment>The comment on .format_datetime() says the 1e-6 nudge makes %OS3 "round to the nearest millisecond", but %OSn in format() truncates (R docs: "gives the seconds truncated to exactly 0 <= n <= 6 decimal places"). The nudge only compensates for double-precision representation error; it does not round. For fractional seconds in [0.9995, 0.999999), e.g. 12:00:00.9996, the output is "12:00:00.999Z" instead of the correctly rounded "12:00:01.000Z" — 1 ms low. Round explicitly in POSIXct representation before formatting (e.g. format(round(x, 3), ...)) or correct the comment to describe truncation with a float-error nudge.</comment>

<file context>
@@ -5,6 +5,32 @@
+  if (inherits(x, "Date")) {
+    return(as.character(x))
+  }
+  s <- format(x + 1e-6, "%Y-%m-%dT%H:%M:%OS3Z", tz = "UTC")
+  sub("\\.000Z$", "Z", s)
+}
</file context>

Suggested change

	s <- format(x + 1e-6, "%Y-%m-%dT%H:%M:%OS3Z", tz = "UTC")
	s <- format(round(x, 3), "%Y-%m-%dT%H:%M:%OS3Z", tz = "UTC")