BusinessCard/CLOUDKIT_SCHEMA_GUARDRAILS.md

CloudKit Schema Guardrails (SwiftData)

Use this checklist before changing any @Model used by SwiftData + CloudKit.

Why

CloudKit-backed SwiftData is additive-first. Breaking schema edits can stop sync or cause migration failures on user devices with existing data.

Safe Changes

• Add a new model type.
• Add a new property that is optional or has a default value.
• Add a new optional relationship.
• Add new computed properties (no storage impact).
• Add new methods/helpers/extensions.

Risky / Avoid Changes

• Do not use @Attribute(.unique).
• Do not remove stored properties that have shipped.
• Do not rename stored properties that have shipped.
• Do not change stored property types after shipping.
• Do not make optional relationships non-optional.

If You Need a Breaking Change

1. Add a new property with a new name (keep old property).
2. Migrate values in app code lazily at runtime.
3. Ship at least one version with both old+new properties.
4. Only consider cleanup after all active users have migrated.

Model Rules for This App

• Every stored property in @Model should be optional or have a default.
• Relationships must stay optional for CloudKit compatibility.
• Keep derived state computed (single source of truth).

Pre-merge Checklist

• xcodebuild ... build succeeds.
• Existing sample/create/edit/delete flows still work.
• At least one device signed into iCloud verifies sync behavior.
• No schema-breaking edits were introduced.

Operational Notes

• First sync on a fresh install can take time.
• CloudKit conflicts are generally last-writer-wins.
• Keep mutation methods centralized in state/store types to reduce conflict bugs.