Skip to content

System Field Integration #25

Closed
Closed

Description

@leogdion
No description provided.

Activity

  1. added this to the milestone on Sep 15, 2020
  2. leogdion commented on Nov 27, 2025

    @leogdion
    MemberAuthor

    Status Update: System field integration is partially implemented.

    Currently Implemented ✅

    In RecordInfo.swift (lines 47-54):

    • recordName - Unique identifier
    • recordType - Schema name
    • recordChangeTag - For optimistic locking
    • fields - User-defined fields

    Missing System Fields ❌

    CloudKit provides additional system fields that are NOT currently exposed:

    • created - Creation timestamp and user info
    • modified - Last modification timestamp and user info
    • deleted - Deletion flag (used in change tracking)

    What Needs to be Done

    1. Verify OpenAPI Spec

    Check if openapi.yaml includes these system fields in the Record schema. If not, they may need to be added based on Apple's CloudKit Web Services documentation.

    2. Update Generated Types

    If the fields are in the OpenAPI spec but not being used, the issue is in how we map from Components.Schemas.Record to RecordInfo.

    3. Add System Fields to RecordInfo

    public struct RecordInfo {
        // Existing fields...
        public let recordName: String
        public let recordType: String
        public let recordChangeTag: String?
        public let fields: [String: FieldValue]
        
        // Add these:
        public let created: SystemFieldTimestamp?
        public let modified: SystemFieldTimestamp?
        public let deleted: Bool?
    }
    
    public struct SystemFieldTimestamp {
        public let timestamp: Date
        public let userRecordName: String?
        public let deviceID: String?
    }

    4. Update CloudKitRecord Protocol

    Consider if CloudKitRecord protocol needs read-only system field accessors:

    protocol CloudKitRecord {
        // ... existing requirements ...
        
        // Optional system field support
        var created: SystemFieldTimestamp? { get }
        var modified: SystemFieldTimestamp? { get }
    }

    Priority

    Medium - These fields are useful for:

    • Displaying creation/modification dates in UIs
    • Auditing and tracking changes
    • Change detection without full fetchRecordChanges calls
    • Debugging and troubleshooting

    However, the core CRUD operations work without them.

    Related Issues

  3. modified the milestones: , v1.0.0-alpha.3 on Nov 27, 2025
  4. leogdion commented on Jan 8, 2026

    @leogdion
    MemberAuthor

    CONFIRMED: createdTimestamp IS an Automatic System Field

    Definitive Evidence from CelestraCloud

    Feed+MistKit.swift analysis proves createdTimestamp is automatic:

    1. Line 59 - READS createdTimestamp:

      let addedAt = record.date(forKey: "createdTimestamp", default: Date())
    2. Lines 100-138 - toFieldsDict() NEVER writes createdTimestamp:

      public func toFieldsDict() -> [String: FieldValue] {
        var fields: [String: FieldValue] = [
          "feedURL": .string(feedURL),
          "title": .string(title),
          // ... many fields ...
          "verifiedTimestamp": .date(lastVerified),  // ✅ Custom field - written
          "attemptedTimestamp": .date(lastAttempted), // ✅ Custom field - written
          // ❌ NO createdTimestamp assignment!
        ]
        return fields
      }

    Conclusion: They read a field they never write → CloudKit must populate it automatically.

    System Fields Behavior

    CloudKit appears to provide automatic metadata fields in the fields dictionary:

    • createdTimestamp - Automatically populated on record creation
    • modifiedTimestamp - Automatically updated on modification
    • Plus other metadata fields

    These are separate from user-defined custom fields like:

    • verifiedTimestamp (custom - manually set)
    • attemptedTimestamp (custom - manually set)

    What MistKit Needs

    MistKit's RecordInfo should expose these automatic system fields that CloudKit provides:

    1. createdTimestamp - Read-only, automatic
    2. modifiedTimestamp - Read-only, automatic
    3. Other metadata fields CloudKit provides

    Currently, MistKit only exposes the fields dictionary where these appear, but doesn't distinguish between:

    • Automatic system fields (CloudKit-managed)
    • User-defined custom fields (developer-managed)

    Implementation Path

    Option 1: Add computed properties to RecordInfo:

    public struct RecordInfo {
      public let recordName: String
      public let recordType: String
      public let recordChangeTag: String?
      public let fields: [String: FieldValue]
      
      // System field accessors
      public var createdTimestamp: Date? {
        fields["createdTimestamp"]?.dateValue
      }
      
      public var modifiedTimestamp: Date? {
        fields["modifiedTimestamp"]?.dateValue
      }
    }

    Option 2: Update OpenAPI spec and regenerate (if REST API includes these in responses)

    Sources:

    • CelestraCloud/Sources/CelestraCloudKit/Extensions/Feed+MistKit.swift:59 (reads createdTimestamp)
    • CelestraCloud/Sources/CelestraCloudKit/Extensions/Feed+MistKit.swift:100-138 (doesn't write createdTimestamp)
    • Core Data with CloudKit Dashboard - Lists system metadata fields
  5. leogdion commented on Jan 9, 2026

    @leogdion
    MemberAuthor

    This issue is now tracked as part of parent issue #199 - Complete CloudKit API Coverage

  6. leogdion commented on Apr 29, 2026

    @leogdion
    MemberAuthor

    Completed and verified in codebase.

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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions