Skip to content

[TS SDK] Consolidate the duplicate sort and pagination param schemas #1130

Open

Description

@laurabelinfante

Summary

SortQueryParamsSchema and SortBodyParamsSchema (sorting.ts:23 and :39) have identical shapes. Same for PaginatedQueryParamsSchema and PaginatedBodyParamsSchema. The split adds no type safety.

One caveat to resolve first: if we auto-generate schemas from TypeSpec later, a single shared schema may be hard to maintain. Zod does not distinguish query from body params, but TypeSpec does. Consolidating in Zod without a matching approach in the core library could create drift.

Acceptance criteria

  • The TypeSpec query-vs-body distinction is evaluated, and the approach either consolidates in the core library too or documents why the SDK can diverge
  • Each query/body pair shares one internal schema definition, or a concrete validation difference is implemented and tested to justify separate definitions
  • The existing query and body schema exports remain available and continue to pass parity tests against their corresponding generated TypeSpec schemas
  • Any Core or TypeScript SDK changes resulting from the decision are included in the [Core] v0.6.0 release and [TS SDK] v0.10.0 release candidates, respectively

Release coordination

This ticket may affect Core and the TypeScript SDK. GitHub allows only one milestone per issue, so [Core] v0.6.0 release is the primary planning milestone and [TS SDK] v0.10.0 release is the coordinated secondary release. If the decision does not require Core consolidation or a public SDK behavior change, one or both releases may not be necessary; update the milestone and release implications to match the recorded decision before closing the ticket.

Activity

  1. added
    breakingChange that breaks the published API. Belongs on a hold branch.
    coreIssues related to @common-grants/core library
    on Aug 27, 2026
  2. added
    sdkIssue or PR related to our SDKs
    typescriptIssue or PR related to TypeScript tooling
    ts-sdkRelated to TypeScript SDK
    on Aug 27, 2026
  3. SnowboardTechie commented on Sep 10, 2026

    @SnowboardTechie
    Collaborator

    Worth folding one more pagination-schema fix in here, since it's the same file and the same breaking release.

    PaginatedResultsInfoSchema.pageSize is min(0) in pagination.ts, with a comment saying 0 is for empty pages. That came in with #522. Core pagination.tsp requires pageSize >= 1 on responses, and every implementation I checked (Express template, simpler-grants-gov, and now the Hono template after cg-api-template-hono#1) reports the requested page size, not the item count. So the SDK is the outlier, and the current parity test can't see it because it only samples protocol-valid values.

    Proposed extra checkbox:

    • PaginatedResultsInfoSchema.pageSize is restored to min(1) to match core, with a regression that fails on pageSize: 0 and still accepts a valid empty page (items: [], pageSize: <requested>, totalItems: 0)

    This is breaking for any client whose server emits pageSize: 0, so it fits the [TS SDK] v0.10.0 release this ticket already targets. No Core change needed for this part.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

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

Type

Projects

Relationships

None yet

Development

No branches or pull requests

Issue actions