JSON Model Changes
v2 models are more explicit
v2 JSON models are more explicit than v1 client code may expect. Re-map payloads from the v2 schemas instead of copying v1 request and response structures.
Field Names
Scalar references and code values use self-describing names.
| Value kind | v2 naming pattern | Examples |
|---|---|---|
| Scalar reference ID | ...Id | platformId, categoryId, typeId, statusId |
| Reference ID list | ...Ids | groupIds, assignedTaskIds |
| Scalar code | ...Code | confirmationStatusCode |
| Code list | ...Codes | endpoint-specific code arrays where documented |
Bare names such as platform, status, or category are reserved for object-valued response
fields or embedded models. When the payload carries only an ID, expect an explicit ...Id field.
Request Models
Request models usually contain writable state only. Server-managed fields such as generated IDs, timestamps, read-only URLs, version metadata, and calculated lifecycle data should not be sent unless the API reference explicitly documents them as writable for that operation.
Before sending a write request:
- verify whether the operation is create, replace, partial update, or command-style
- check whether omitted fields are ignored, defaulted, cleared, or rejected
- check whether explicit
nullis accepted, rejected, or interpreted as a clear operation - check whether collection fields are replacement lists, instruction lists, or read-only
For method-level behavior, see Write Semantics.
Response Models
v2 responses can include richer objects and metadata. For example, response fields can include embedded references such as a platform, group, category, status, user, or external-system object instead of only scalar values.
Optional string response fields may be omitted when their value is empty. Clients should treat both
an omitted optional string field and an empty string value ("") as no value, not as a parsing
error.
Collection fields can still be returned as empty arrays when the schema documents an array.
Client parsers should:
- tolerate additive fields
- read IDs and codes from the documented fields
- avoid assuming that response objects can be sent back unchanged as write payloads
- use the returned aggregate as the current state after nested writes when the endpoint documents an aggregate response
Nested Element Writes
The element API is aggregate-oriented. Some element write requests can include nested tasks, publications, custom-field values, and task-publication links. These nested branches have their own field semantics.
Use:
- Resource Model for the aggregate model
- Elements for root element migration notes
- Element Tasks for standalone task field mapping
- Element Publications for standalone publication, schedule, CMS, and publish field mapping
- Task-Publication Link Migration for v1-to-v2 link field mapping
- Custom-Field Migration for definition, option, and value field mapping
- Configuration Resource Migration for platform, group, category, type, status, and task-format mapping
- Platform Schedule Configuration Migration for platform weekly/manual schedule and time-slot configuration
- People And Scheduling Migration for user, absence, shift, and shift-day-note mapping
- Task-Publication Linking guide for v2 link workflow details
- Publication Scheduling for schedule fields
- API reference for exact request and response schemas
Migration Rule
Do not transform v1 JSON mechanically
Do not transform v1 JSON mechanically.
For each endpoint, build an explicit mapping from the v2 schema:
| Question | Where to check |
|---|---|
| What field do I send? | Request schema in /api |
| Is it required? | Request schema and validation error behavior in /api |
| What happens if I omit it? | Field description and method guide |
What happens if I send null? | Field description and method guide |
| What response should I parse? | Success response schema in /api |
| How are errors reported? | Error response schema and Error Contract Changes |