Skip to content

[SDK] Decide how datetimes are represented in the SDKs and the core library #1125

Open

Description

@laurabelinfante

Summary

UTCDateTimeSchema and OffsetDateTimeSchema coerce to JS Date objects. Two separate signals say that is wrong: the Pennsylvania API hit friction with the coercion and would rather have validated strings, and the TS plugin work suggests the core library's datetime representation may need more precision than Date carries.

Note this pulls against #1016, closed by PR #1024, which fixed date-only round-tripping by introducing a PlainDate class. Date-only values are already handled; this is about datetimes, and the proposed direction (keep strings, drop the coercion) is the opposite of the one already shipped.

Acceptance criteria

  • A decision on datetime representation is recorded, covering both the SDK schemas and whether the core library needs more precision
  • The decision is reconciled with the PlainDate approach from fix(ts-sdk): preserve plain dates in JSON #1024
  • Any resulting public contract change is marked as breaking for Release Please
  • How the Python SDK represents datetimes is checked, and the decision says whether Python needs a matching change. If it does, a Python SDK ticket is created for that work

Activity

  1. added
    breakingChange that breaks the published API. Belongs on a hold branch.
    on Aug 27, 2026
  2. added
    coreIssues related to @common-grants/core library
    sdkIssue or PR related to our SDKs
    pythonIssue or PR related to Python tooling
    typescriptIssue or PR related to TypeScript tooling
    py-sdkRelated to Python SDK
    ts-sdkRelated to TypeScript SDK
    on Aug 27, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    breakingChange that breaks the published API. Belongs on a hold branch.coreIssues related to @common-grants/core librarypy-sdkRelated to Python SDKpythonIssue or PR related to Python toolingsdkIssue or PR related to our SDKsts-sdkRelated to TypeScript SDKtypescriptIssue or PR related to TypeScript tooling

    Type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions