The document API currently does not return the document title (The name of the document as seen in the UI) in the response, however, the Migration API requires a title in the payload.
In the UI, a title will nomally be created automatically when you create a document, but it your are migrating many different documents of varying types, you'd have to do some pretty complex crawling of first the type definition to find the path where an element uses "useAsTitle": true and then try to locate the content at that path in the document being migrated.
Why can't the Migration API accept null for the title and then work it out automatically as it would in the UI?
Or alternatively, provide a way of retrieving the existing title from the document API or something else.
You’re absolutely right—this isn’t an ideal developer experience, and we’ve logged it as a feature request to improve in the future. The Document API doesn’t provide a built-in way to fetch the document title directly, which makes this process more cumbersome than it should be.
For now, your current approach of mapping another existing field (like uid, metatitle, or another identifier) to the title field in your migration script is the best workaround. This ensures your documents have a recognizable title in Prismic without requiring additional API calls or manual intervention.
Let us know if you run into any challenges or need help optimizing your workflow!
For now, thankfully I can consult the existing type definition for a useAsTitle and extract the text from the document, but it's pretty error prone.
It's odd that the migration api accepts an empty string for the title, but not a null - The empty string is my current fallback…
Another issue I've experienced is where an existing document has an image field left blank, the document api returns json such as {"imageFieldName": "sizeVariant": []}. The migration api rejects the value with:
{
"property": "data.imageFieldName.id",
"error": "The value must be a string"
},
{
"property": "data.imageFieldName.sizeVariant",
"value": [],
"error": "The value must be an object"
}
The problem is clear, but why reject input that the document api outputs? It would make more sense to filter empty image structs at your end considering that everything is optional on a read model.
So far this problem has occurred in slices (legacy), but I don't have the time to test it in other contexts
We agree that the current approach isn’t ideal, and relying on useAsTitle from the type definition adds extra complexity. The fact that the Migration API accepts an empty string but not null is an inconsistency we’ll bring up internally. Ideally, it should handle both or provide a clearer constraint. Your workaround: using an empty string as a fallback makes sense for now, but we’ll track this as an area for improvement.
Image Field Discrepancy
The issue with how the Document API outputs empty image fields versus how the Migration API validates them is definitely frustrating. You’re right—it would be more intuitive if the Migration API accepted the same format the Document API provides, rather than rejecting it. Filtering out empty image structures on our end would make migrations smoother, and we’ve flagged this internally.
So far, you’ve encountered this in legacy slices (and I think it might be isolated to legacy data), but if you do run into it elsewhere and have time to share details, that would be helpful. In the meantime, a potential workaround would be to pre-process documents in your migration script and normalize any empty image fields before sending them to the API.
Let us know if you hit any other roadblocks—we appreciate the detailed feedback!
A couple of other things that would make life better:
Accept the created/updated timestamps in Asset payloads to preserve the original times - this will keep ordering in the media library to most recent on top. But also accept nulls to ignore them and use the current timestamp
The same for documents - You could sort your initial document fetch by pub date ascending to retain the order, but preserving times would be easier for users. Mind you, I assume the timestamps would get updated when you publish the migration release anyhow.
Thanks again for this detailed feedback—these are great points that would definitely improve the migration experience.
Preserving Created/Updated Timestamps in Asset Payloads
Accepting created and updated timestamps in asset payloads makes a lot of sense, especially for maintaining the correct order in the Media Library. We’ll pass this along as a feature request. Allowing null values to ignore them and use the current timestamp by default would also be a flexible solution.
Preserving Timestamps for Documents
This is another solid suggestion. While sorting the initial document fetch by first_publication_date or last_publication_date can help maintain relative order, explicitly preserving timestamps in the migration process would be much cleaner. As you pointed out, timestamps would likely get updated upon publishing the migration release, but we’ll bring this up internally to see if there’s a way to retain original values for better continuity.
We really appreciate these insights. If you run into any other roadblocks, feel free to share—we’re always looking to improve the experience!