Context
The shared AddCloudHealthOfficeJsonOptions() helper introduced in
claude/shared-json-options-3YZO1 / commit 6043ce7 registers
JsonStringEnumConverter with the framework default allowIntegerValues: true.
This is intentional for the first rollout — it preserves backward compatibility
with any external caller still POSTing numeric enum values (e.g. "status": 4
instead of "status": "Approved"). Without it, a cutover from integer-enum
to string-enum payloads would have been a breaking change for any client
that hadn't migrated.
The problem with leaving it
Once the shared extension is adopted everywhere, integer-enum payloads
silently continue to work. The whole point of centralizing the converter
is to make the string-enum contract enforceable. If allowIntegerValues
stays true forever, external callers will keep POSTing ints, and we'll
discover a year from now that the "migration" never actually finished.
Definition of done
References
- Shared extension:
src/services/shared/CloudHealthOffice.Infrastructure/Json/CloudHealthOfficeJsonOptions.cs
- Follow-up called out in
docs/architecture/shared-json-options.md
- Related commit:
6043ce7 (PR for claude/shared-json-options-3YZO1)
Context
The shared
AddCloudHealthOfficeJsonOptions()helper introduced inclaude/shared-json-options-3YZO1/ commit6043ce7registersJsonStringEnumConverterwith the framework defaultallowIntegerValues: true.This is intentional for the first rollout — it preserves backward compatibility
with any external caller still POSTing numeric enum values (e.g.
"status": 4instead of
"status": "Approved"). Without it, a cutover from integer-enumto string-enum payloads would have been a breaking change for any client
that hadn't migrated.
The problem with leaving it
Once the shared extension is adopted everywhere, integer-enum payloads
silently continue to work. The whole point of centralizing the converter
is to make the string-enum contract enforceable. If
allowIntegerValuesstays
trueforever, external callers will keep POSTing ints, and we'lldiscover a year from now that the "migration" never actually finished.
Definition of done
(grep HTTP access logs / OpenAPI consumer telemetry if available,
or ask API consumers directly).
new JsonStringEnumConverter()tonew JsonStringEnumConverter(namingPolicy: null, allowIntegerValues: false)in
src/services/shared/CloudHealthOffice.Infrastructure/Json/CloudHealthOfficeJsonOptions.cs.docs/architecture/shared-json-options.mdto reflect the change.References
src/services/shared/CloudHealthOffice.Infrastructure/Json/CloudHealthOfficeJsonOptions.csdocs/architecture/shared-json-options.md6043ce7(PR forclaude/shared-json-options-3YZO1)