[Issue #736] ADR: Nullable Optional Fields

[jcrichlake]

Summary

• Fixes ADR: Should optional fields in the CommonGrants protocol be nullable? #736
• Time to review: 5 minutes

Changes proposed

Adds ADR-0024 documenting the decision on optional field nullability in the CommonGrants protocol spec and SDKs.

Context for reviewers

This ADR resolves the question of whether optional fields in the base protocol (TypeSpec-generated) should be nullable. The current situation: both the Python SDK
(Optional[X]) and TypeScript SDK (.nullish()) render optional fields as nullable, but the base protocol declares them as optional-but-non-nullable. Once the
resolveAnyOf() bug in cg check spec is fixed (#735), both SDKs will fail validation.

Decision: Make optional fields nullable in the base protocol (Option 1).

The key insight driving this decision is that publishers need to express three distinct field states — "not provided" (field absent), "doesn't apply" (explicit
null), and "has a value" — and this three-state model is only achievable with a nullable spec, especially for scalar types like dates where no natural sentinel
value exists.

No code changes are included in this PR; the ADR documents the rationale so the corresponding TypeSpec and implementation changes can follow in a subsequent PR.

Additional information

The three options evaluated in the ADR:

Option	Description	Chosen?
Option 1	Make optional fields nullable in the base protocol	✅
Option 2	Keep non-nullable; update SDKs to remove .nullish() / Optional[X]	❌
Option 3	Allow both representations; treat null and absent as equivalent	❌

[github-actions]

🚀 Website Preview Deployed!

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

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

[SnowboardTechie]

👍🏻

[SnowboardTechie]

👍 — approved.

Heads up that this ADR has handler-level implications the SDK PoCs didn't anticipate. The TypeScript transforms PoC (#825) had three coercing handlers (numberToString, stringToNumber, switchOnValue) that collapsed an explicit null source into undefined, which would have made the publisher's "doesn't apply" assertion unobservable through toCommon / fromCommon once ADR-0024 lands.

I've pushed alignment commits to #825 that:

• preserve null through the coercing handlers (return type widens accordingly)
• add an opt-in case: { "null": "..." } to match / switch for target-side translation, while keeping pass-through as the default
• document the three-state contract in the SDK README for custom-handler authors
• exercise the round-trip end-to-end via the existing example (source_url: null survives both directions)

ADR-0024's "SDKs already reflect this model and require no changes" framing is accurate for the validation surface (.nullish() already accepts both), but the transforms layer is downstream of that and needs its own pin. Worth a follow-up against the Python PoC (#810) for the same alignment — TS leads, Python parity tracked there.

No changes needed in ADR-0024 itself.

[github-actions]

🗑️ Preview Cleaned Up

The preview for this PR has been automatically deleted.