Import JSON Reference
This article defines the JSON structure for every field for Prismic imports.
We recommend that you publish and export a sample document to get the full JSON object for that Custom Type. You can then use this JSON file as your template when you generate your JSON files for import.
"type": "post"An array of strings representing tags. Even if you are only adding one tag, it must be in an array. Tags that do not already exist in the repository will be created.
"tags": ["foo", "bar"] The UID is a unique identifier for the document. Each UID must be unique to its Custom Type.
The value required for the UID field is a string that must not contain any spaces or special characters (only dashes and underscores). If you attempt to import a UID with special characters or spaces, it will be automatically be formatted (spaces are replaced by dashes, and special characters are removed).
If you try to add a document with a UID that is already used on an existing document in the repository, an incremented number will automatically be appended at the end of the UID. (For example, "my-new-page" will automatically become "my-new-page1").
"uid": "my-unique-identifier""subtitle_text": "This is my subtitle text!"A string that matches one of the options configured for the Select field in the Custom Type.
If the value provided does not match an available option, no value will be set for the imported content.
"author": "John Doe"Warning: Even if an invalid color code is given, it will still be imported.
"title_color": "#62a9c4"A valid timestamp as a string. If the timestamp format is not valid, no value will be loaded into the field.
"event_time": "2016-09-15T22:00:00+00:00"A date in the format YYYY-MM-DD as a string. If the date format is not correct, no value will be entered for the field.
"release_date": "2016-09-16"Either true or false. This value is boolean, not a string, so it does not require quotation marks.
"my_boolean": true"price": "19"To import a Rich Text field, you must provide an array of one object per paragraph. Each paragraph has a type property that defines the paragraph's formatting option. Learn about the type options.
Warning: The content you input will be imported regardless of whether or not it complies with the configuration of the Rich Text field. If your Rich Text field is defined in the Custom Type only to have the type heading1, the importer will not prevent you from uploading text of the type paragraph or heading2 to that field.
Here is a simple example of a Rich Text field with the API ID of "title". This field takes only a single line of text, which we've defined as a heading1 element.
"title": [
{
"type": "heading1",
"content": {
"text": "This is the document title",
"spans": []
}
}
]The following is an example of a multi-paragraph Rich Text field with the API ID of desc. This assumes that the target field is configured for multiple paragraphs.
"desc": [
{
"type": "heading1",
"content": {
"text": "This is my section title",
"spans": []
}
},
{
"type": "paragraph",
"content": {
"text": "Here is the text for that section.",
"spans": []
}
}
]The following is an example of a paragraph that contains a link element. The link element is defined with an object in the spans array.
{
"type": "paragraph",
"content": {
"text": "Donec quis dui at dolor tempor interdum.",
"spans": [
{
"type": "hyperlink",
"start": 0,
"end": 40,
"data": {
"url": "https://prismic.io",
"preview": {
"title": "https://prismic.io"
}
}
}
]
}
} {
"type": "embed",
"data": {
"type": "video",
"embed_url": "https://www.youtube.com/watch?v=y6y_4_b6RS8"
},
"content": {
"text": "",
"spans": []
}
} The following is an example of a paragraph section with a hyperlink to an image in the Media Library.
{
"type": "paragraph",
"content": {
"text": "Cras iaculis ultricies nulla.",
"spans": [
{
"type": "hyperlink",
"start": 5,
"end": 12,
"data": {
"wioUrl": "wio://medias/V9vEGhgAABgAn8s7",
"url": "https://prismic-io.s3.amazonaws.com/import-test%2Fb5fe9b43-894f-4028-aad7-a00c8d3ef3e2_technics-q-c-640-480-7.jpg",
"kind": "image",
"id": "V9vEGhgAABgAn8s7",
"height": "480",
"width": "640",
"size": "41298",
"date": "09/16/16 10:03",
"name": "technics-q-c-640-480-7.jpg",
"preview": {
"title": "technics-q-c-640-480-7.jpg",
"image": "https://prismic-io.s3.amazonaws.com/import-test%2Fb5fe9b43-894f-4028-aad7-a00c8d3ef3e2_technics-q-c-640-480-7.jpg"
}
}
}
]
}
}You have a Content Relationship field with the API ID of categoty_link. In JSON, there will be two different values id and wioUrl for the object.
An object with two properties:
- id: the ID of the linked document
- wioUrl: a string that takes the format wio://documents/${filename}
To import a Content Relationship field, the page that you want to link must be already available in your repo.
The filename is the value that comes before $ sign in an exported file, for example, if the JSON file is called YEoT0BEAACMA6dKT$954b6ddd-31e5-45a1-8b60-d215f0e17a5e.json, then the id is YEoT0BEAACMA6dKT.
"category_link": {
"id": "YEoUChEAACMA6dOX",
"wioUrl": "wio://documents/YEoUChEAACMA6dOX"
},{
"type": "image",
"content": {
"text": "",
"spans": []
},
"data": {
"origin": {
"url": "https://prismic-io.s3.amazonaws.com/import-test%2Fb5fe9b43-894f-4028-aad7-a00c8d3ef3e2_technics-q-c-640-480-7.jpg"
}
}
}You can bulk upload images from the Media Library UI, or you can import images along with Import jobs. To bulk upload images in the Media Library UI, select all your images and drag and drop them into the Media Library.
There are three ways to reference image files in your import:
- Include images in your ZIP archive
- Reference images in your Media Library
- Include a URL for an image hosted elsewhere
If you include the image in your ZIP archive or link to an external URL, the importer will add the image to your Media Library. If you reference an asset multiple times in one import batch, it will only be added to your Media Library once.
Below is the basic data you need to include in your JSON files to import images without any resizing or cropping options.
In your JSON file, provide the reference URL of the online image.
{
"image_field1":{
"origin":{
"url":"https://images.ladepeche.fr/api/v1/images/view/5c37588b3e454652f74478af/large/image.jpg"
}
}
}{
"image_field2":{
"origin":{
"url":"toto.jpg"
}
}
}{
"hero_image":{
"origin":{
"url":"https://prismic-io.s3.amazonaws.com/slicemachine-blank/6b2bf485-aa12-44ef-8f06-dce6b91b9309_dancing.png"
}
}
}"location": {
"position": {
"lat": 47.6205063,
"lng": -122.3492774
}
}A type property, with a string specifying the type of the embed, and an embed_url property with a URL for the embed.
Refer to a JSON export example of the type of embed you are trying to include to find the embed type.
"soundcloud-player": {
"type": "rich",
"embed_url": "https://soundcloud.com/seacastle-1"
} The following example would add a link to an existing document in the repository of the type page with the document ID of V-p_rx4AAB4AmyHa.
"document_link": {
"id": "V-p_rx4AAB4AmyHa",
"mask": "page"
}"web_link": {
"url": "http://seacastleband.com"
}The following example would add a link to an existing asset in the repository's Media Library with the ID of V9vHXBgAABgAn9hF.
"media-link": {
"wioUrl": "wio://medias/V9vHXBgAABgAn9hF",
"url": "https://prismic-io.s3.amazonaws.com/import-test%2F0fcf1760-dce7-4d12-8e20-a3e11472c797_city-q-c-640-480-4.jpg",
"kind": "image",
"id": "V9vHXBgAABgAn9hF",
"height": "480",
"width": "640",
"size": "34769",
"date": "09/16/16 10:04",
"name": "city-q-c-640-480-4.jpg"
}It is only possible to upload and link to an Image file. You must manually upload other file types.
The following example would add a link to a new asset to be loaded into the repository's Media Library. You need to include the asset file in the import ZIP file.
The import module will upload the asset into the Media Library and add the link to this field.
"media_link": {
"url": "image.png",
"kind": "image",
"name": "image name",
"id": "",
"size": "",
"height": "",
"width": ""
} Let's say that you have a repeatable Group field with the API ID of "links-group". Inside that group, you have a Key Text field with the API ID of "label" and a Link field with the API ID of "link".
The following example would add two sets of links with labels.
"links-group": [
{
"label": "Link This!",
"link": {
"url": "http://css-tricks.com"
}
},
{
"label": "Link That!",
"link": {
"url": "http://jurassicpark.com"
}
}
] Slices are content blocks that can be freely organized within a Slice Zone. A single Slice can contain several repeatable and non-repeatable items.
If you look at the exported JSON for a Slice that contains several items within a group, you’ll see the following property for each item.
"key": "alternated-highlights$b0b1de36-ffb7-406d-86ca-0855dae17c7e", If you want to import several items within a Slice, this property should just contain the Slice ID like this:
"key": "alternated-highlights",The hash after the $ will be automatically assigned by the importer. Other than that, refer to the exported JSON for each of your Slice types to see what the import JSON code needs to be imported.
Was this article helpful?
Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.