# Breaking Changes

import { Card, CardHeader, CardTitle, CardDescription } from "zudoku/ui/Card.js";

This page tracks v1-to-v2 changes that can require integration work.

:::caution{title="Migration baseline"}

For the first v2 release, treat the list below as the migration baseline for the public v2 REST API.

:::

## Global Changes

| Area | v2 behavior | Client impact |
|------|-------------|---------------|
| Base path | Public REST endpoints use `/api/v2`. | Clients must call v2 paths explicitly. |
| Authentication | v2 token issuance uses OAuth2-style client credentials through `/api/v2/auth/token`; protected endpoints use bearer tokens. | Clients must use the v2 token contract and send `Authorization: Bearer ...`. |
| Error bodies | Errors use RFC 9457 Problem Details. Validation errors can include an `errors` array. | Clients should parse `type`, `status`, `detail`, and field-level issues instead of relying on old response text. |
| Write methods | `POST`, `PUT`, `PATCH`, and `DELETE` have documented semantics. | Clients should not treat `PUT` as partial update or `PATCH` as full replacement. |
| List pagination | Most list endpoints use a shared response shape with `content`, `size`, `hasMore`, optional `page`, and optional `nextCursor`; `GET /api/v2/elements` is cursor-only. | Clients should update list parsers and choose the pagination mode exposed by each endpoint. |
| Reference fields | Scalar references use explicit field names such as `...Id`, `...Ids`, `...Code`, and `...Codes`. | Clients should map payload fields by the v2 schema instead of assuming v1 names. |
| Response detail | v2 responses can expose richer embedded objects and metadata. | Clients should tolerate additive response fields and avoid strict unknown-field failures. |

## Resource-Specific Breaking Changes

Each resource family has its own breaking changes, documented on a dedicated page:

<div className="grid gap-4 sm:grid-cols-2 mt-6 not-prose">
  <a href="/docs/migration-from-v1/elements" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>Elements</CardTitle>
        <CardDescription>Explicit root write fields, command-based external linking.</CardDescription>
      </CardHeader>
    </Card>
  </a>
  <a href="/docs/migration-from-v1/tasks" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>Element Tasks</CardTitle>
        <CardDescription>Required format and confirmation fields, done-state action endpoint, 204 deletes.</CardDescription>
      </CardHeader>
    </Card>
  </a>
  <a href="/docs/migration-from-v1/publications" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>Element Publications</CardTitle>
        <CardDescription>Dedicated schedule subresource, read-only published state, explicit task links.</CardDescription>
      </CardHeader>
    </Card>
  </a>
  <a href="/docs/migration-from-v1/task-publication-linking" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>Task-Publication Link Migration</CardTitle>
        <CardDescription>Explicit task refs and IDs replace positional assignments.</CardDescription>
      </CardHeader>
    </Card>
  </a>
  <a href="/docs/migration-from-v1/custom-fields" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>Custom-Field Migration</CardTitle>
        <CardDescription>Paginated definitions, plural option paths, selected-option IDs, named type values.</CardDescription>
      </CardHeader>
    </Card>
  </a>
  <a href="/docs/migration-from-v1/configuration-resources" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>Configuration Resource Migration</CardTitle>
        <CardDescription>Paginated lists, platform-scoped categories and types, deferred 202 deletes.</CardDescription>
      </CardHeader>
    </Card>
  </a>
  <a href="/docs/migration-from-v1/platform-schedule-configuration" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>Platform Schedule Configuration Migration</CardTitle>
        <CardDescription>Weekly-or-manual schedule modes, PATCH instruction lists, time slots.</CardDescription>
      </CardHeader>
    </Card>
  </a>
  <a href="/docs/migration-from-v1/people-and-scheduling" className="no-underline">
    <Card className="h-full transition-colors hover:border-primary">
      <CardHeader>
        <CardTitle>People And Scheduling Migration</CardTitle>
        <CardDescription>Paginated users, plural absence paths, restricted shift writes.</CardDescription>
      </CardHeader>
    </Card>
  </a>
</div>

:::info{title="How to use this page"}

Use this page as an impact checklist, not as a schema reference. For exact request and response
shapes, use the [API reference](/api). For method-level behavior, use
[Write Semantics](/docs/guides/api-conventions/write-semantics).

:::