Updating your document-based app
Migrate an existing app to adopt URL-based document reading and writing with Swift concurrency.
Overview
If you have an existing document-based app, you can adopt the Document protocol to take advantage of direct URL access, Swift concurrency integration, and modern observation. The Document protocol separates reading and writing into dedicated types, which gives you more control over file I/O and enables partial reads and writes for complex document formats.
In releases before iOS 27, iPadOS 27, macOS 27, and visionOS 27, you create a document type by conforming to either FileDocument or ReferenceFileDocument. In these and later releases, you can either conform to the Document protocol or to the ReadableDocument and WritableDocument protocols, depending on what your app does. Although FileDocument and ReferenceFileDocument remain available, they’re no longer supported for new document types.
The following table highlights the differences between these three protocols to help you choose the right migration path:
Type | Value ( | Reference ( | Reference ( |
Reading | |||
Writing | |||
Reading and writing execution | Synchronous | Synchronous |
|
File access | Filewrapper only | Filewrapper only | URL or Filewrapper |
Undo | Automatic (value semantics) | Manual (Undomanager) | Manual (Undomanager) |
Observation | N/A (value type) |
Update your app
Depending on which deprecated protocol your app uses, select the appropriate tab and follow the checklist to update your app:
If your existing document-based app uses FileDocument or ReferenceFileDocument, the following table shows how concepts map to the Document protocol:
The following example shows a complete text document before and after migrating from FileDocument:
The key structural change is the shift from value to reference semantics. With FileDocument, SwiftUI tracks mutations through the Binding to the structure and manages undo automatically. With Document, you use @Observable for change tracking and register undo actions explicitly — but gain async I/O, URL-based file access, and clear separation between state capture and serialization.
The following example shows a complete text document before and after migrating from ReferenceFileDocument:
The migrated document cleanly separates concerns, supports URL access for advanced use cases, adopts the Observation framework, and integrates Swift concurrency.