feat(core): add models and routes for awards#1008
Open
widal001 wants to merge 6 commits into
Open
Conversation
Adds a lightweight reference model for opportunities, applications, and organizations (OppRef, AppRef, OrgRef, plus an OrgRefCollection for grouping organizations). A reference model previews the key fields a consumer needs to identify a record and look it up or join it to another response, without repeating the full model. Each base model now includes its own reference model, so the reference always matches the fields on the base, and any later change to those shared fields appears in the base model's changelog. Record ids are also now read-only across these models, matching opportunities. Also renames the application's `name` field to `title`, for consistency with the other models and the new reference models. Adopters reading application data at protocol version 0.4.0 should expect `title` in place of `name`.
Adds AwardBase, a model for reporting on a grant award: its funder,
recipient, financial amounts, and key dates, along with references to
the opportunity and application it resulted from. Awards can name
either an organization or an individual as the recipient.
Adds three endpoints an adopter can offer for awards:
- list awards: GET /common-grants/awards/
- view an award: GET /common-grants/awards/{awdId}
- search awards: POST /common-grants/awards/search
Available at protocol version 0.4.0 and marked experimental, so the
shape may still change before it becomes a stable part of the protocol.
Adds an Award page under Protocol > Models covering the award model and its supporting types. Each reference model is documented on the page for the model it points to (opportunity, application, and organization). Regenerates the published schemas and OpenAPI specification so the new models appear in the docs.
Adds a build step after the OpenAPI generation that removes any tag from a version's tag list when none of that version's routes use it. TypeSpec lists every tag in every version, so earlier versions advertised tags like Awards or Competitions that only have routes in later versions. Now each version's docs only list tags a consumer can actually find routes for. The step edits only the tag list, so the rest of each generated file stays unchanged.
github-actions
Bot
added
website
Contributor
|
🚀 Website Preview Deployed! Preview your changes at: https://cg-pr-1008.billy-daly.workers.dev This preview will be automatically deleted when the PR is closed. |
This was
linked to
issues
Jul 15, 2026
Removes recipientType (and the AwdRecipientType enum and search filter) from the award model. The recipient is already conveyed by whichever field is populated, recipientOrganizations or recipientIndividual, so the separate discriminator was redundant, and it is not present in most of the award standards we reviewed. Awards are experimental, so an explicit recipient type can be added later if one is needed.
Documents AwdIdFain on the award model page, which was missing, and adds v0.4.0 as the latest option in the API docs version dropdown so its routes (including awards) are viewable. Also regenerates the schemas after the recipientType removal.
widal001
commented
Jul 15, 2026
Collaborator
Author
There was a problem hiding this comment.
The changes in this file and the other pre v0.4.0 are because of the new script that I added that removes OpenAPI tags that don't have any associated routes in a given version.
widal001
commented
Jul 15, 2026
| description: The base model for an application to a competition for a funding opportunity | ||
| example: | ||
| id: 123e4567-e89b-12d3-a456-426614174000 | ||
| name: My Application |
Collaborator
Author
There was a problem hiding this comment.
The one tradeoff around examples and versioning in schemas is that example properties that were renamed seems to just drop the property instead of renaming it in previous versions.
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
1 participant
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
Adds models and routes that support awards to the
@common-grants/corelibrary and the protocol docs on the website.Changes proposed
GET /common-grants/awards/GET /common-grants/awards/search/GET /common-grants/awards/{awdId}{ id, name/title, identifiers })OppRefOrgRefAppRefApplicationBase.nametoApplicationBase.titleto match thetitleconvention inOpportunityBaseandAwardBasepnpm typespec:openapito strip OpenAPI tags that don't have any routes in earlier versions. The default@typespec/openapi3leaves in tags in earlier versions even if they don't contain routes in that version.Context for reviewers
Instructions to review
Opportunity,required, andoptionalNotes
src/public/schemas/yaml/and `src/public/openapi/. Historically we've committed the latest version of files in this directory because they help us catch unexpected drift between versions, but as the number of schemas and routes grows, we might want to revisit that policy to keep our PRs smaller.Awdto match the prefix in the ID registry (and follow the pattern ofOpportunity->OppandApplication->App) but I could be persuaded to use the fullAwardinstead.Additional information
Awards models
Latest OpenAPI version
Filtering OpenAPI tags by version
Ref models