# JSON Model Changes

:::info{title="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 `null` is 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](/docs/guides/api-conventions/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](/docs/getting-started/data-model) for the aggregate model
- [Elements](/docs/migration-from-v1/elements) for root element migration notes
- [Element Tasks](/docs/migration-from-v1/tasks) for standalone task field mapping
- [Element Publications](/docs/migration-from-v1/publications) for standalone publication,
  schedule, CMS, and publish field mapping
- [Task-Publication Link Migration](/docs/migration-from-v1/task-publication-linking) for v1-to-v2 link
  field mapping
- [Custom-Field Migration](/docs/migration-from-v1/custom-fields) for definition, option, and value field
  mapping
- [Configuration Resource Migration](/docs/migration-from-v1/configuration-resources) for platform, group,
  category, type, status, and task-format mapping
- [Platform Schedule Configuration Migration](/docs/migration-from-v1/platform-schedule-configuration) for
  platform weekly/manual schedule and time-slot configuration
- [People And Scheduling Migration](/docs/migration-from-v1/people-and-scheduling) for user, absence, shift,
  and shift-day-note mapping
- [Task-Publication Linking guide](/docs/guides/editorial-workflows/task-publication-linking) for v2 link workflow details
- [Publication Scheduling](/docs/guides/editorial-workflows/publication-scheduling) for schedule fields
- [API reference](/api) for exact request and response schemas

## Migration Rule

:::caution{title="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](/docs/migration-from-v1/errors-status-codes) |