Skip to content

Zone schemas only model { zoneID } — enrich with sync/atomic metadata + create options #386

Closed

Description

@leogdion

Background

Follow-up to the zone endpoint tickets #43 (zones/list), #44 (zones/lookup), #45 (zones/modify), #48 (zones/changes) — all CLOSED. A gap review found every zone response models a zone as just { zoneID }, and there's no way to express zone-creation options.

Current state

  • ZonesListResponse, ZonesLookupResponse, ZonesModifyResponse, ZoneChangesResponse (openapi.yaml:1296-1340) each model a zone as { zoneID } only.
  • ZoneOperation (openapi.yaml:1215-1225) has no zone create options.
  • zones/modify request has no atomic flag.

What needs to be done

  • Add zone metadata to the response zone objects: syncToken, atomic, isEager.
  • Add zone create options to ZoneOperation (e.g. atomic).
  • Add an atomic flag to the zones/modify request.

⚠️ Needs live verification

webservices.md is abbreviated on zone payloads, so the exact field names/shape above should be confirmed against a live zones/list / zones/modify response before encoding them. Flagged for confirmation, not asserted as confirmed.

Implementation notes

  • Edit openapi.yaml only, then regenerate via ./Scripts/generate-openapi.sh. Never hand-edit Sources/MistKitOpenAPI/.
  • Map new fields onto the domain ZoneInfo / zone result types in Sources/MistKit/Models/Zones/.

Activity

  1. leogdion commented on Aug 20, 2026

    @leogdion
    MemberAuthor

    Moving from the v1.0.0-beta.3 milestone to v1.0.0-beta.4 — work not yet complete.

  2. leogdion commented on Aug 20, 2026

    @leogdion
    MemberAuthor

    Verification results (PR #427)

    Verified the proposed fields against Apple's archived CloudKit Web Services Reference before encoding them. Three of the five proposed changes could not be confirmed, so PR #427 implements only the confirmed subset.

    Confirmed and implemented — the "Zone Dictionary" documents exactly three keys, and all four zone endpoints route their success payload through it:

    • zoneID
    • syncToken — "The current point in the zone's change history."
    • atomic — "A Boolean value indicating whether this zone supports atomic operations."

    Not confirmed, omitted:

    • isEager — appears in no primary source. Not in the Zone Dictionary, nowhere in the archived reference, and absent from both .claude/docs/webservices.md and .claude/docs/cloudkitjs.md. If this came from an observed live response, please paste it and I'll model it; otherwise there's no basis for a name or type.
    • atomic on the zones/modify request — ModifyZones.html documents the body as operations only. Notably records/modify does document atomic, so the asymmetry appears deliberate.
    • Zone create options on ZoneOperation — same page: the operation's zone is "A dictionary representing the zone to modify. It has a single zoneID key."

    Follow-ups found during verification (not in PR #427)

    1. modifyZones drops per-zone failures. Apple documents a "Zone Fetch Error Dictionary" (zoneID, reason, serverErrorCode, retryAfter, redirectURL) returned inline for failed zones in zones/list, zones/lookup, and zones/modify. modifyZones returns [ZoneInfo] and silently discards those entries — the exact gap .claude/memory/feedback_record_result_pattern_throughout.md describes, previously fixed for records and subscriptions. Fix needs a ZoneOperationFailure schema, a oneOf response, and a return-type change (a source break), so it wants its own issue.

    2. zones/changes may use the wrong token key. GetZoneChanges.html documents the request and response token as metaSyncToken; MistKit sends and reads syncToken. If the doc is right, fetchZoneChanges pagination is silently broken. Holding off because Apple's page contradicts itself — the moreComing description refers back to "the included syncToken key" — so this needs a live-response check, not a doc-driven change.

    3. zones/changes is documented as deprecated in favor of changes/database.

  3. leogdion commented on Aug 20, 2026

    @leogdion
    MemberAuthor

    Two follow-ups split out of this issue

    The verification comment above narrowed #427 to the confirmed subset. Two things surfaced during that verification that are out of scope for #427 and are now tracked separately, so they don't get lost when this closes:

    One more thing worth recording

    ZoneID's owner key is ownerRecordName in Apple's archived reference, but ownerName in both MistKit's domain ZoneID and its wire schema. Left alone as out of scope, but if the wire name is genuinely ownerRecordName, then owner-qualified zone addressing — shared zones — would not work, which touches #146's shared-zone support. I did not verify which is correct; flagging it rather than asserting it. Say the word and I'll open an issue.

    Also note the deliberate omissions in #427, so they aren't mistaken for oversights: isEager (appears in no primary source), atomic on the zones/modify request (Apple documents that body as operations only), and zone create options on ZoneOperation (documented as a single zoneID key, now pinned by a regression test). Each needs a doc update or a live payload before it can be added.

    🤖 Generated with Claude Code

  4. leogdion commented on Aug 28, 2026

    @leogdion
    MemberAuthor

    Resolved on v1.0.0-beta.4 via #427 (commit 5a65bf3). Shared Zone schema added and reused across all four zone responses; syncToken and atomic surfaced on ZoneInfo.

    Scope note: only the fields confirmed against Apple's primary reference were implemented. isEager and the proposed zones/modify request options were not confirmed and were deliberately left out rather than guessed. The two follow-ups this surfaced are tracked separately in #430 (metaSyncToken on zones/changes) and #431 (modifyZones RecordResult pattern).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions