Skip to content

schema-governance.md

Latest commit

 

History

History
73 lines (46 loc) · 2.51 KB

schema-governance.md

File metadata and controls

73 lines (46 loc) · 2.51 KB
Raw

ConstituentEvent schema governance

UniSchema uses semantic versioning for the repository and documents breaking changes to the ConstituentEvent master schema.

Version policy

Change type Example Version bump
New optional field Add middleName? Minor (v0.x)
New sourceSystem enum Add SLATE Minor (v0.x)
New eventType enum Add VOLUNTEER_SHIFT Minor — coordinate downstream
Remove / rename core field Rename constituentEmail Major (v1.0+)
Change field type amount string → number only Major

Adding event types

  1. Extend EventTypeSchema in src/schema/master.ts
  2. Update frontend constituentEvent.ts
  3. Document migration in CHANGELOG
  4. Notify downstream pipelines (dbt models, warehouse loaders)

Adding source systems

Follow adding-a-vendor.md — each vendor adds a sourceSystem enum value.

Deprecation window

From v1.0 onward: 6 months notice in CHANGELOG before removing or renaming core fields. Use normalizedMetadata for org-specific extensions instead of forking the master schema.

Future: schemaVersion field

Planned for v1.0 if breaking changes accumulate:

{ "schemaVersion": 1, "eventId": "...", ... }

Downstream loaders should ignore unknown versions and alert operators.

RFC process (community)

Open a GitHub Discussion with:

  • Motivation (which vendors / pipelines need the change)
  • Proposed Zod diff
  • Migration notes for existing S3 batches

Maintainers label rfc/schema and decide before merge.

Community RFC: VOLUNTEER_SHIFT (documentation only)

Status: Not implemented — awaiting pilot institution request.

Motivation

Advancement teams track volunteer shifts separately from event registrations. Today these map awkwardly to EVENT_REGISTRATION.

Proposed change

Add VOLUNTEER_SHIFT to EventTypeSchema in src/schema/master.ts.

Downstream impact

Component Action
dbt mart_constituent_engagement_daily Add volunteer_shift_count column
dbt mart_constituent_rfm_features Optional engagement feature
philanthropy.ingest (PhilanthroPy repo) Add volunteer_shift_count to the feature contract
PhilanthroPy pipelines Map to engagement features or separate model

Do not implement until

At least one pilot institution confirms the enum name and provides sample webhook payloads.