WIP

Author: slifty

CHANGELOG.md

@@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+### Added
+
+- Added `terminology_sets`: per-funder display-label overrides for `opportunity`, `applicationForm`, and `proposal` (singular/plural; null means PDC default). Exposed via `GET`/`POST`/`PATCH /terminologySets[/:id]`. A new `terminologySet` context and scope are inherited from the owning funder.
+- Added `funders.defaultTerminologySetId`: a funder's chosen default for newly-created opportunities. Existing opportunities are not re-bound when the default changes.
+- Added `opportunities.terminologySetId`: opportunities may reference a terminology set owned by the same funder. When omitted on `POST /opportunities`, the funder's default is pinned at insert time; setting it explicitly requires `reference | terminologySet`.
+- `opportunity` responses now include `terminologySetId` and an inlined `terminologySet` (or `null`); `funder` responses now include `defaultTerminologySetId`.
+
 ### Changed
 
 - Creating an entity now automatically grants the creator a `manage` permission with `any` scope on the new entity. This applies to opportunities, changemakers, proposals, sources, bulk upload tasks, application forms (and their fields), proposal versions (and their field values), and changemaker field values created via the HTTP API, as well as proposals, proposal versions, proposal field values, and newly inserted changemakers created during bulk upload processing.

docs/ENTITY_RELATIONSHIP_DIAGRAM.md

@@ -70,6 +70,7 @@ erDiagram
     int id PK
     string title
     string funderShortCode FK
+    int terminologySetId FK
     datetime createdAt
     uuid createdBy FK
   }
@@ -119,6 +120,20 @@ erDiagram
     string name
     uuid keycloakOrganizationId
     boolean isCollaborative
+    int defaultTerminologySetId FK
+    datetime createdAt
+    uuid createdBy FK
+  }
+  TerminologySet {
+    int id PK
+    string funderShortCode FK
+    string name
+    string opportunityLabel
+    string opportunitiesLabel
+    string applicationFormLabel
+    string applicationFormsLabel
+    string proposalLabel
+    string proposalsLabel
     datetime createdAt
     uuid createdBy FK
   }
@@ -179,6 +194,7 @@ erDiagram
     int sourceId FK
     int bulkUploadTaskId FK
     int changemakerFieldValueId FK
+    int terminologySetId FK
     string[] scope
     string[] verbs
     jsonb conditions
@@ -190,6 +206,9 @@ erDiagram
   Opportunity ||--|{ ApplicationForm : establishes
   Funder ||--|{ Opportunity : has
   Funder ||--|{ BulkUploadTask : has
+  Funder ||--o{ TerminologySet : "authors"
+  Funder }o--o| TerminologySet : "defaults to"
+  Opportunity }o--o| TerminologySet : "uses"
   ApplicationForm ||--|{ ApplicationFormField : has
   ApplicationFormField }o--|| BaseField : represents
   BaseField ||--o{ BaseFieldLocalization : "has localizations"
@@ -226,6 +245,7 @@ erDiagram
   PermissionGrant }o--o| Source : "references"
   PermissionGrant }o--o| BulkUploadTask : "references"
   PermissionGrant }o--o| ChangemakerFieldValue : "references"
+  PermissionGrant }o--o| TerminologySet : "references"
   PermissionGrant }o--|| User : "is created by"
   Changemaker ||--o{ FiscalSponsorship : "sponsors"
   Changemaker ||--o{ FiscalSponsorship : "is sponsored by"

docs/GLOSSARY.md

@@ -11,3 +11,11 @@ or may be part of an organization's attributes returned by a data provider.
 
 A person or group that makes change. For example, a grant applicant, grant
 recipient, non-profit organization, or an individual seeking funds.
+
+## Terminology set
+
+A funder-authored bundle of display-label overrides for canonical PDC concepts
+(e.g. "opportunity", "application form", "proposal"). A funder may publish many
+terminology sets and pick one as the default that newly-created opportunities
+adopt. Individual opportunities can also reference a terminology set explicitly.
+A label left null falls back to the PDC default.

docs/PERMISSIONS.md

@@ -268,6 +268,8 @@ context key).
 | edit   | proposal           | Create or update proposal versions for the funder's proposals                        |
 | view   | source             | View the funder's sources                                                            |
 | create | source             | Create sources associated with the funder                                            |
+| view   | terminologySet     | View the funder's terminology sets                                                   |
+| edit   | terminologySet     | Create or update terminology sets owned by the funder                                |
 | manage | funder             | View, send, and respond to funder collaborative invitations                          |
 |        |                    | View collaborative members for the funder                                            |
 
@@ -325,6 +327,21 @@ not by a separate field-level permission.
 | view | applicationForm | View the specific application form and its fields                                                                                |
 | edit | applicationForm | Update the application form (including its fields' labels, instructions, and input types via `PATCH /applicationFormFields/:id`) |
 
+### TerminologySet Permissions
+
+Permissions granted against a terminology set (using the terminology set's `id`
+as the context key). Terminology sets are funder-scoped: an `edit |
+terminologySet` grant on a funder automatically applies to all of that funder's
+terminology sets. Opportunity-level grants do **not** confer access to
+terminology sets — terminology sets inherit only from the parent funder.
+
+| Verb      | Scope          | What It Enables                                                                              |
+| --------- | -------------- | -------------------------------------------------------------------------------------------- |
+| view      | terminologySet | View the specific terminology set                                                            |
+| edit      | terminologySet | Update the terminology set's name and label fields                                           |
+| reference | terminologySet | Bind the terminology set to an opportunity (via `terminologySetId` on `POST /opportunities`) |
+| manage    | terminologySet | Full permissions including managing permission grants on the terminology set                 |
+
 ### Proposal Permissions
 
 Permissions granted directly against a proposal (using the proposal's `id` as

src/__tests__/funders.int.test.ts

@@ -122,6 +122,7 @@ describe('/funders', () => {
 						name: 'The Foundation Foundation',
 						keycloakOrganizationId: null,
 						isCollaborative: false,
+						defaultTerminologySetId: null,
 					},
 					{
 						shortCode: 'theFundFund',
@@ -130,6 +131,7 @@ describe('/funders', () => {
 						name: 'The Fund Fund',
 						keycloakOrganizationId: null,
 						isCollaborative: false,
+						defaultTerminologySetId: null,
 					},
 					systemFunder,
 				],
@@ -164,6 +166,7 @@ describe('/funders', () => {
 						name: 'Green Environment Fund',
 						keycloakOrganizationId: null,
 						isCollaborative: false,
+						defaultTerminologySetId: null,
 					},
 				],
 			});
@@ -371,6 +374,7 @@ describe('/funders', () => {
 				name: 'The Foundation Foundation',
 				keycloakOrganizationId: '0de87edc-be40-11ef-8249-0312f1b87538',
 				isCollaborative: false,
+				defaultTerminologySetId: null,
 			});
 		});
 
@@ -456,6 +460,7 @@ describe('/funders', () => {
 				createdAt: expectTimestamp(),
 				createdBy: testUser.keycloakUserId,
 				isCollaborative: false,
+				defaultTerminologySetId: null,
 			});
 			expect(after.count).toEqual(before.count);
 			expect(anotherFunderAfter).toEqual(anotherFunderBefore);