feat!(core): add non-templated response schemas and rename templates with T suffix#1007
Draft
SnowboardTechie wants to merge 2 commits into
Draft
feat!(core): add non-templated response schemas and rename templates with T suffix#1007SnowboardTechie wants to merge 2 commits into
SnowboardTechie wants to merge 2 commits into
Conversation
…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
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Changes proposed
Ok,Paginated,Sorted,Filtered, andCreatedresponse 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).Tsuffix (OkT<T>,PaginatedT<T>,SortedT<T>,FilteredT<ItemsT, FilterT>,CreatedT<T>); routes still use these to generate response bodies.Createdsection) with<SchemaChangelog>blocks, replacing the previously hand-written JSON schema snippets with the emitted schema files.@common-grants/core— specs consuming the old templated names (e.g.Responses.Ok<T>) must switch to theT-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 withduplicate-type-nameerrors 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:
status/messagenow arrive viaallOf: Successcomposition instead of inline flattening (semantically equivalent).Success.yamllosesunevaluatedProperties: not: {}— expected: the emitter unseals schemas that are now composed viaallOfby the new concrete response schemas.Verified with
pnpm run ciat 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 forOk,Created,Paginated,Sorted, andFiltered.Additional information
New emitted schemas:
Ok.yaml,Paginated.yaml,Sorted.yaml,Filtered.yaml,Created.yaml(seewebsite/public/schemas/yaml/). Example (Paginated.yaml):