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

The API ID of a Custom Type in the destination repository.

Copy
"type": "post"

Tags

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.

Copy
"tags": ["foo", "bar"]  

UID

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").

Copy
"uid": "my-unique-identifier"

Key Text

A string containing the content of the Key Text field.

Copy
"subtitle_text": "This is my subtitle text!"

Select

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.

Copy
"author": "John Doe"

Color

A hex color value as a string.

Warning: Even if an invalid color code is given, it will still be imported.

Copy
"title_color": "#62a9c4"

Timestamp

A valid timestamp as a string. If the timestamp format is not valid, no value will be loaded into the field.

Copy
"event_time": "2016-09-15T22:00:00+00:00"

Date

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.

Copy
"release_date": "2016-09-16"

Boolean

Either true or false. This value is boolean, not a string, so it does not require quotation marks.

Copy
"my_boolean": true

Number

A number as a string. If the value given is not a number, no value will be imported.

Copy
"price": "19"

Rich Text

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. The type options are described here.

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 to only have the type heading1, the importer will not prevent you from uploading text of the type paragraph or heading2 to that field.

Single paragraph

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.

Copy
"title": [
  {
    "type": "heading1",
    "content": {
      "text": "This is the document title",
      "spans": []
    }
  }
]

Multiple paragraphs

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.

Copy
"desc": [
  {
    "type": "heading1",
    "content": {
      "text": "This is my section title",
      "spans": []
    }
  },
  {
    "type": "paragraph",
    "content": {
      "text": "Here is the text for that section.",
      "spans": []
    }
  }
]

Inline elements

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.

Copy
{
  "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"
          }
        }
      }
    ]
  }
}   

Embed

The following is an example of an embed element in a Rich Text field.

Copy
{
  "type": "embed",
  "data": {
    "type": "video",
    "embed_url": "https://www.youtube.com/watch?v=y6y_4_b6RS8"
  },
  "content": {
    "text": "",
    "spans": []
  }
}   

Paragraph with an inline link to a media library item

The following is an example of a paragraph section with a hyperlink to an image in the media library.

Copy
{
  "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"
          }
        }
      }
    ]
  }
}

Content Relationship

Let's say that 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 which 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.

Copy
"category_link": {
    "id": "YEoUChEAACMA6dOX",
    "wioUrl": "wio://documents/YEoUChEAACMA6dOX"
  },

Image

The following is an example of an image element in a Rich Text field.

Copy
{
  "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.

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.

Link to images hosted elsewhere

In your JSON file, provide the reference URL of the online image.

Copy
{
    "image_field1": {
        "origin": {
            "url": "https://images.ladepeche.fr/api/v1/images/view/5c37588b3e454652f74478af/large/image.jpg"
        }
    }
}

Include images in your ZIP archive

In your import JSON, reference the image with a local path.

Copy
{
    "image_field2": {
        "origin": {
            "url": "toto.jpg"
        }
    }
}

Use images from your Media Library

Provide the URL of the image in your Media Library.

Copy
{
    "hero_image": {
        "origin": {
            "url": "https://prismic-io.s3.amazonaws.com/slicemachine-blank/6b2bf485-aa12-44ef-8f06-dce6b91b9309_dancing.png"
        }
    }
}

GeoPoint

An object with lat and lng properties, each with numbers for their values.

Copy
"location": {
  "position": {
    "lat": 47.6205063,
    "lng": -122.3492774
  }
}

Embed

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.

Copy
"soundcloud-player": {
  "type": "rich",
  "embed_url": "https://soundcloud.com/seacastle-1"

Links

To an internal document

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.

Copy
"document_link": {
  "id": "V-p_rx4AAB4AmyHa",
  "mask": "page"
}

To the web

The following example would add a link to the web.

Copy
"web_link": {
  "url": "http://seacastleband.com"
}

To a media library asset

The following example would add a link to an existing asset in the repository's media library with the ID of V9vHXBgAABgAn9hF.

Copy
"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"
}

To a local asset

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.

Copy
"media_link": {
  "url": "image.png",
  "kind": "image",
  "name": "image name",
  "id": "",
  "size": "",
  "height": "",
  "width": ""
}   

Group

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.

Copy
"links-group": [
  {
    "label": "Link This!",
    "link": {
      "url": "http://css-tricks.com"
    }
  },
  {
    "label": "Link That!",
    "link": {
      "url": "http://jurassicpark.com"
    }
  }
] 

Slices

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.

Copy
"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:

Copy
"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?
Not really
Yes, Thanks

Can't find what you're looking for? Get in touch with us on our Community Forum.