Build Custom Types with JSON

On this page, you will learn how to use the JSON editor to build your Custom Types.


In Prismic, all of your Custom Types are stored as simple JSON. The JSON editor is a tool inside the Custom Type Builder that allows you to build your Custom Types. This is useful if for versioning and adding advanced configurations.

It uses JSON syntax, as its name says, to structure the Slices and Fields.

The JSON editor gives you additional customization options for your Custom Types. You'll use it if you're faced with any of the following cases:

  • You need to change the API ID of a Custom Type
  • You need to change the API ID of a Slice
  • You need to add additional configuration for a Field.

Custom Type JSON structure

Here's an example of the JSON for a very simple Custom Type:

Copy
{
  "Example First Tab": {
    "example_number": {
      "type": "Number",
      "config": {
        "label": "Example Number",
        "placeholder": "3.14159..."
      }
    },
    "body": {
      "type": "Slices",
      "fieldset": "Slice zone",
      "config": {
        "labels": {
          "example_first_slice": []
        },
        "choices": {
          "example_first_slice": {
            "type": "Slice",
            "fieldset": "Example First Slice",
            "description": "This is the first example slice.",
            "icon": "adb",
            "display": "list",
            "non-repeat": {
              "example_slice_key_text": {
                "type": "Text",
                "config": {
                  "label": "Example Slice Key Text",
                  "placeholder": "Massa sapien faucibus..."
                }
              }
            },
            "repeat": {}
          }
        }
      }
    }
  },
  "Example Second Tab": {
    "example_color": {
      "type": "Color",
      "config": {
        "label": "Example Color"
      }
    }
  }
}

Let's break down that structure. Here's a simplified overview of the JSON for a Custom Type. Each node in the tree is the key in a key-value pair. Keys in [square brackets] are user-defined.

Copy
.
├── [tab name] <!-- Key should be display name of the tab, e.g. "Main" -->
│   ├── [field api id] <!-- Key should be API ID of the Field, e.g. "featured" -->
│   │   ├── type <!-- Value should be type of field, e.g. "Boolean" -->
│   │   └── config <!-- Value is a config object -->
│   ├── [field id]
│   │   ├── type
│   │   └── config
│   ├── <!-- More fields... -->
│   └── [slicezone api id] <!-- Key should be API ID of the SliceZone, e.g. "body" -->
│       ├── type <!-- Value must be "Slices" -->
│       └── config
│           └── choices
│               └── [slice api id] <!-- Key should be API ID of Slice, e.g. "image_row" -->
│                   ├── type <!-- Value must be "Slice" -->
│                   ├── fieldset <!-- Value should be display name for Slice, e.g. "Image Row" -->
│                   ├── ... <!-- Add'l config options, such as "icon", "display" -->
│                   ├── non-repeat <!-- Non-repeatable zone -->
│                   │   ├── [field api id] <!-- Value should be API ID of the Field -->
│                   │   │   ├── type
│                   │   │   └── config
│                   │   └── <!-- More fields... -->
│                   └── repeat // <!-- Repetable zone, similar to a "group" field -->
│                       ├── [field api id]
│                       │   ├── type
│                       │   └── config
│                       └── <!-- More fields... -->
└── [tab name]
    ├── [field api id]
    │   ├── type
    │   └── config
    └── <!-- More fields... -->

What is an API ID?

API IDs are names used to identify Custom Types, Slices, and Fields. When you first create a Custom Type; when you add and configure a Field; and when you first create a Slice and give it a name.

For all of these, this name is formatted with the following rules:

  • All spaces are replaced with underscores. For example, Price Number Image converts to price_number
  • All uppercase characters are converted to lowercase. For example, FullWidthImage converts to fullwidthimage
  • Duplicate API IDs automatically append a number at the end. For example, if you have a field called text_field and try to repeat it in another field, it will be text_field1

Change a Custom Type API ID

It isn't possible to change the API ID of a Custom Type after it has been created. If you need a new API ID, create a new Custom Type with the correct API ID.

Here are the steps to duplicate a Custom Type with a new API ID:

  1. Open the JSON editor from the original Custom Type
  2. Copy all the JSON
  3. Create a new Custom Type with the correct API ID
  4. Paste the JSON into the JSON editor of the new Custom Type

Change the API ID of a Slice

Please note that when you change the API ID of a slice, all the existing content you have for that slice will disappear.

Here are the steps to change the API ID:

  1. Go to the edit page for the Custom Type that has the slice.
  2. Click on the JSON editor tab. This will bring up the JSON definition of the Custom Type.
  3. Find the Slice that you would like to modify in the JSON code.
  4. Edit the API ID
Screenshot that shows where a Slice name is found in the JSON editor

Change the API ID of a field

Renaming fields is not supported. If you ever rename the API ID of a field, The API will interpret this as deleting the initial field and creating a new one.

If you change a title API ID to new_title, you'll see a new field with the same configuration as the first one, but the data returned from the API will be empty. The content added to the old field will not migrate to the new one.

Recover lost data

You can recover data in a field that has been removed from a Custom Type. To achieve this:

  • Add the old field back to your Custom Type: Use the same field type and API ID previously used.
  • Restore the version: If you made a publication after removing the field from the Custom Type, the data will not appear on the document's editor UI of the published document. You can find this by browsing the history, click Restore and then publish the desired version.
  • In case you didn't publish: If you did not publish after removing the field, the data will be displayed on the latest published version of the document.

Add extra configuration to a field

Most of the time, you'll only need to access the basic configuration located in the gear icon ⚙️ of each field. This step is only relevant when you need to add additional settings to your Content Fields that are not available in the initial configuration.

Some examples of this are:

  • Adding min and max values to a Number field
  • Adding labels to a Rich Text field

To see the JSON model specifications for each field, read each field's reference.


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.