API: schedule item polymorphic fields rely on implicit Newtonsoft runtime-type serialization (OpenAPI schema gap) #126

Closed
opened 2026-07-05 12:02:24 +02:00 by timothy · 1 comment
Owner

Found during the PR #125 (#86 Schedule editor) review.

GET /api/schedules/{id}/items returns List<ProgramScheduleItemViewModel> where the VM is an abstract record with derived types (Flood/One/Multiple/Duration). The derived-only fields (count, multipleMode, playoutDuration, tailMode, discardToFillAttempts) reach the wire only because Startup.cs configures AddNewtonsoftJson, and Newtonsoft serializes list elements by runtime type. There is no [JsonPolymorphic]/[JsonDerivedType] annotation and the OpenAPI document only describes the abstract base shape — so the generated SPA types (web/src/api/generated/v1.d.ts) miss those fields, and web/src/api/schedules.ts compensates with a hand-widened intersection type.

Risks:

  • A future migration to System.Text.Json (or any serializer honoring declared types) would silently truncate these fields → the SPA's replace-all reorder PUT would then reset Multiple/Duration item settings or 422.
  • The OpenAPI contract is wrong today: consumers generating from v1.json cannot see fields the API actually returns.

Suggested fix (pick one):

  1. Flatten: return a dedicated non-polymorphic API DTO from the items endpoints (record in ErsatzTV.Core/Api with file-scoped #nullable enable, nullable derived-only fields), mapped from the VM hierarchy — matches the repo's API DTO conventions and makes v1.json truthful; then regen OpenAPI + SPA types and delete the hand-widened type in web/src/api/schedules.ts.
  2. Or annotate the VM hierarchy for explicit polymorphic serialization and teach the OpenAPI generation about the derived schemas (discriminator).

Option 1 is preferred (smaller blast radius, consistent with existing Core/Api DTO precedent).

Refs: PR #125 review, #86, #111 (duration estimate fields ride the same DTOs).

Found during the PR #125 (#86 Schedule editor) review. `GET /api/schedules/{id}/items` returns `List<ProgramScheduleItemViewModel>` where the VM is an **abstract** record with derived types (Flood/One/Multiple/Duration). The derived-only fields (`count`, `multipleMode`, `playoutDuration`, `tailMode`, `discardToFillAttempts`) reach the wire **only** because `Startup.cs` configures `AddNewtonsoftJson`, and Newtonsoft serializes list elements by runtime type. There is no `[JsonPolymorphic]`/`[JsonDerivedType]` annotation and the OpenAPI document only describes the abstract base shape — so the generated SPA types (`web/src/api/generated/v1.d.ts`) miss those fields, and `web/src/api/schedules.ts` compensates with a hand-widened intersection type. Risks: - A future migration to System.Text.Json (or any serializer honoring declared types) would silently truncate these fields → the SPA's replace-all reorder PUT would then reset Multiple/Duration item settings or 422. - The OpenAPI contract is wrong today: consumers generating from v1.json cannot see fields the API actually returns. Suggested fix (pick one): 1. Flatten: return a dedicated non-polymorphic API DTO from the items endpoints (record in ErsatzTV.Core/Api with file-scoped `#nullable enable`, nullable derived-only fields), mapped from the VM hierarchy — matches the repo's API DTO conventions and makes v1.json truthful; then regen OpenAPI + SPA types and delete the hand-widened type in `web/src/api/schedules.ts`. 2. Or annotate the VM hierarchy for explicit polymorphic serialization and teach the OpenAPI generation about the derived schemas (discriminator). Option 1 is preferred (smaller blast radius, consistent with existing Core/Api DTO precedent). Refs: PR #125 review, #86, #111 (duration estimate fields ride the same DTOs).
Author
Owner

Done — fixed via PR #229 (merged), option 1 (flatten) as preferred

What was done: the three /api/schedules/{id}/items endpoints now return a dedicated non-polymorphic ScheduleItemResponseModel (ErsatzTV.Core/Api/Scheduling/, 55 fields: all 39 ScheduleItemRequest-aligned mutation fields — nullable where subtype-gated — plus display names, playlistGroupId, {id,name} watermark/graphics lists) mapped from the VM hierarchy; the GET envelope is ScheduleItemsResponseModel {items, totalDurationEstimate}. The OpenAPI schema is now truthful (subtype fields present, no implicit-runtime-type dependence), and the hand-widened intersection type in web/src/api/schedules.ts is deleted — the SPA consumes generated types directly.

Root cause: as filed — abstract VM + Newtonsoft runtime-type serialization with no polymorphism contract in the spec.

Bonus hardening found while fixing (live E2E of PR #229): the write-path handlers projected the freshly-built entity graph whose watermark/graphics navs were unset — a lazy LanguageExt Map masked the NRE in tests (never enumerated) while the controller's serialization 500'd in production. Write paths now reload through the shared read include-chain (IncludeScheduleItemDetails()); pinned by ScheduleItemWriteProjectionTests with nothing pre-tracked. Convention recorded in api-conventions §7.

Verification: fixed-point round-trip test (GET→map→PUT→GET semantic equality over all four subtypes + rerun + search + fillers + overrides), OpenApiSerializerContractTests (dropped the now-off-surface WatermarkViewModel case), regenerated v1.json/endpoint-index/v1.d.ts committed, CI green.

## Done — fixed via PR #229 (merged), option 1 (flatten) as preferred **What was done**: the three `/api/schedules/{id}/items` endpoints now return a dedicated non-polymorphic `ScheduleItemResponseModel` (`ErsatzTV.Core/Api/Scheduling/`, 55 fields: all 39 `ScheduleItemRequest`-aligned mutation fields — nullable where subtype-gated — plus display names, `playlistGroupId`, `{id,name}` watermark/graphics lists) mapped from the VM hierarchy; the GET envelope is `ScheduleItemsResponseModel {items, totalDurationEstimate}`. The OpenAPI schema is now truthful (subtype fields present, no implicit-runtime-type dependence), and the hand-widened intersection type in `web/src/api/schedules.ts` is deleted — the SPA consumes generated types directly. **Root cause**: as filed — abstract VM + Newtonsoft runtime-type serialization with no polymorphism contract in the spec. **Bonus hardening found while fixing** (live E2E of PR #229): the write-path handlers projected the freshly-built entity graph whose watermark/graphics navs were unset — a lazy LanguageExt `Map` masked the NRE in tests (never enumerated) while the controller's serialization 500'd in production. Write paths now reload through the shared read include-chain (`IncludeScheduleItemDetails()`); pinned by `ScheduleItemWriteProjectionTests` with nothing pre-tracked. Convention recorded in api-conventions §7. **Verification**: fixed-point round-trip test (GET→map→PUT→GET semantic equality over all four subtypes + rerun + search + fillers + overrides), `OpenApiSerializerContractTests` (dropped the now-off-surface `WatermarkViewModel` case), regenerated v1.json/endpoint-index/v1.d.ts committed, CI green.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#126