ISO 8601 vs RFC 3339: the two date formats behind your API responses

The 'ISO 8601' field that rejects valid ISO 8601 — a week date or a reduced-precision value sent to an API that expected RFC 3339

An API field described casually as “ISO 8601” may accept only one date-time shape. Sending another standards-valid representation can still fail its parser. The remedy is not to argue from the umbrella name; it is to document the exact wire grammar with examples and validation tests.

ToolAcre contributes a stable canonical output from `Date.toISOString()`, but it is not a conformance suite for every representation. Treat the generated string as one useful interchange form and compare it with the API contract you actually own.

A schema should therefore publish a regular expression or formal type only if it accurately reflects the parser. Examples alone are useful, but explicit rejection cases close ambiguity.

A broad date standard and a narrow API grammar are not interchangeable

The generated form contains calendar date, `T`, time through milliseconds and trailing Z. The implementation calls it ISO 8601 (UTC) in the UI. Input accepts what JavaScript Date reads, including an explicit offset and the local picker’s zoneless date-time shape.

That behavior is much narrower than a complete standard parser. Week dates, intervals, durations and reduced precision have no repository tests. A string accepted by one browser Date is not thereby guaranteed across languages, and a rejected specialized form does not disprove its standing elsewhere.

The output’s fixed millisecond precision is a formatting choice, not evidence that the source measured milliseconds. Date may have received a whole-second value and still prints `.000`.

ToolAcre emits one ISO-shaped form; it does not validate the full ISO 8601 standard

The workbook characterized RFC 3339, its year and mandatory offset rules. No RFC text or dedicated parser exists in the source set, so those particulars are not asserted. The authoring contract requires leaving unsupported precision out rather than citing a title from memory.

If your API means RFC 3339, name it in the schema and test against an implementation grounded in the actual specification. ToolAcre can bridge a known epoch to its UTC ISO output for comparison, but it cannot certify that arbitrary input satisfies that profile.

This is an editorial and engineering safeguard: standards profiles are precise contracts, and paraphrasing them without the text risks changing requirements in documentation.

RFC 3339 requirements need an external standards source not present in this repository

Claims about alternate separators, lowercase designators and `−00:00` depend on exact standards language. They are omitted here. The converter’s own zone detector recognizes trailing Z or numeric `±HH:MM` and flags zoneless date-times as local; that is the boundary we can verify.

Build API validation from explicit accepted examples and rejection cases. Do not infer permission from JavaScript Date’s convenience parser. A permissive browser can normalize input that a strict server correctly rejects, hiding interoperability defects during manual testing.

A dedicated standards-aware parser should return structured error reasons. Letting Date normalize broad input can turn an API validation bug into a later cross-platform discrepancy.

Specific separator and unknown-offset rules are omitted without the standards text

Epoch values make arithmetic and ordering compact when unit and origin are fixed. Textual date-times make a UTC or offset reading visible to people and preserve that designator in transit. Many APIs choose one canonical string to avoid JavaScript integer or unit ambiguity.

If an API carries both, define which field is authoritative and test agreement. A stale formatted string beside a fresh epoch is worse than either alone. ToolAcre can compare the pair by converting the integer and checking the generated ISO value, but consistency enforcement belongs in the producer.

Worked example: one instant, four representations — epoch seconds, epoch milliseconds, an RFC 3339 string in UTC and one with a local offset

Use instant `2025-02-03T10:22:00.000Z`. Its epoch forms are 1,738,578,120 seconds and 1,738,578,120,000 milliseconds. An explicit-offset reading is `2025-02-03T12:22:00+02:00`; parsing it in ToolAcre returns the same epoch and canonical UTC ISO row.

These are four repository-verifiable representations: seconds, milliseconds, toISOString output and a Date-parsed numeric-offset string. The example does not claim every external parser accepts the same fractional precision or offset syntax. Run the API’s own validation before shipping.

Subtracting the +02:00 offset from the written clock yields 10:22 UTC. That simple equality is enough to test this particular input without generalizing a full standard grammar.

Worked example: one instant in the four forms this repository can verify

HTTP headers and e-mail dates use textual contracts not implemented here. ToolAcre does not format those protocols, nor does it promise that its ISO output can be substituted. A timestamp’s instant can be the same while its required wire representation differs.

Keep protocol serialization in dedicated adapters with fixtures copied from authoritative specifications. Use epoch conversion to verify the underlying instant, then test grammar separately. This prevents a calendar-correct value from passing review in a syntactically invalid envelope.

The dedicated adapter should also preserve whether missing or unknown offset carries domain meaning. Flattening every textual date into a local assumption can destroy that information.

Other textual protocols remain outside the converter

Specify the narrow format your API accepts instead of relying on a broad label. For this tool, the safest reproducible output is the UTC ISO string returned by `toISOString()`, and the safest numeric input includes an explicit seconds or milliseconds contract.

ToolAcre bridges those forms and reports assumptions. It does not adjudicate all ISO 8601 or RFC 3339 edge cases. Clear ownership of grammar, unit and zone designator is what makes timestamps portable—not attaching a familiar standard name to an underspecified field.

A precise contract lets clients fail early with useful messages. A broad label pushes disagreement into runtime, where two otherwise correct parsers can choose different subsets.