Skip to content

feat!(core): add non-templated response schemas and rename templates with T suffix#1007

Draft
SnowboardTechie wants to merge 2 commits into
mainfrom
960-response-base-schemas
Draft

feat!(core): add non-templated response schemas and rename templates with T suffix#1007
SnowboardTechie wants to merge 2 commits into
mainfrom
960-response-base-schemas

Conversation

@SnowboardTechie

Copy link
Copy Markdown
Collaborator

Summary

Changes proposed

  • Adds non-templated Ok, Paginated, Sorted, Filtered, and Created response models so they are emitted as standalone JSON schemas and picked up by the schema changelog (all versioned from v0.1.0, matching when their templated equivalents were added).
  • Renames the templated variants with a T suffix (OkT<T>, PaginatedT<T>, SortedT<T>, FilteredT<ItemsT, FilterT>, CreatedT<T>); routes still use these to generate response bodies.
  • Documents the concrete schemas on the website responses pages (including a new Created section) with <SchemaChangelog> blocks, replacing the previously hand-written JSON schema snippets with the emitted schema files.
  • Adds a minor changeset for @common-grants/core — specs consuming the old templated names (e.g. Responses.Ok<T>) must switch to the T-suffixed equivalents.

Context for reviewers

The approach follows the CommonBenefits core library's base/templated schema split, with one adaptation: the templated variants spread a shared *Base<T> model instead of extending it. Extending a templated parent makes the openapi3 emitter declare the parent instantiations as named schemas, which fails with duplicate-type-name errors in our setup; spreading inlines the shared properties the same way the previous ...Paginated<T> composition did. The shared base still keeps the concrete and templated variants in sync. TypeSpec still has no native way to emit uninstantiated templates as schemas, so the base-model approach remains necessary.

Notes on the generated-output diffs:

  • Route response bodies in the OpenAPI output are unchanged apart from description strings; inherited status/message now arrive via allOf: Success composition instead of inline flattening (semantically equivalent).
  • Success.yaml loses unevaluatedProperties: not: {} — expected: the emitter unseals schemas that are now composed via allOf by the new concrete response schemas.

Verified with pnpm run ci at the repo root (all packages green) and by inspecting the built responses pages, which now render the emitted schemas and v0.1.0 changelog tables for Ok, Created, Paginated, Sorted, and Filtered.

Additional information

New emitted schemas: Ok.yaml, Paginated.yaml, Sorted.yaml, Filtered.yaml, Created.yaml (see website/public/schemas/yaml/). Example (Paginated.yaml):

$schema: https://json-schema.org/draft/2020-12/schema
$id: Paginated.yaml
type: object
properties:
  items:
    type: array
    items: {}
    description: Items from the current page
  paginationInfo:
    $ref: PaginatedResultsInfo.yaml
    description: Details about the paginated results
required:
  - items
  - paginationInfo
allOf:
  - $ref: Success.yaml
description: A 200 response with a paginated list of items

…with T suffix

Templated response models (Ok<T>, Paginated<T>, Sorted<T>, Filtered<ItemsT, FilterT>,
Created<T>) are never emitted as standalone JSON schemas, which left them out of the
schema changelog and forced hand-written schema blocks in the website docs.

- Add concrete Ok, Paginated, Sorted, Filtered, and Created models that emit JSON
  schemas, versioned from v0.1.0
- Rename the templated variants with a T suffix (OkT, PaginatedT, SortedT, FilteredT,
  CreatedT); routes keep using these, and shared *Base<T> templates keep the concrete
  and templated variants in sync
- Document the concrete schemas on the website responses pages with changelogs, using
  the emitted schema files instead of hand-written blocks

Closes #960
@github-actions github-actions Bot added cli Issue or PR related to the @common-grants/cli library website Issues related to the website core Issues related to @common-grants/core library typescript Issue or PR related to TypeScript tooling labels Jul 15, 2026
@github-actions

Copy link
Copy Markdown
Contributor

🚀 Website Preview Deployed!

Preview your changes at: https://cg-pr-1007.billy-daly.workers.dev

This preview will be automatically deleted when the PR is closed.

- SortedT now extends Success, keeping it in sync with the concrete Sorted
  model (no route uses SortedT directly, so emitted output is unchanged)
- Add missing @doc to CreatedT
- Consolidate the templates-don't-emit rationale into one file-header comment
- Fix docs frontmatter line ranges after the above edits
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cli Issue or PR related to the @common-grants/cli library core Issues related to @common-grants/core library typescript Issue or PR related to TypeScript tooling website Issues related to the website

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Core] Created non-templated response schemas to support versioning

1 participant