JSON List

The JSON List layer connects a list of preset records, hosted as a single JSON file, so buyers pick one from a searchable dropdown instead of you building each option by hand. Add it to any artwork where you have many options that share the same fields, like a list of cities, schools, or teams.

1. What is a JSON layer

A JSON layer works similarly to an Additional Option: both let a buyer pick from a preset list. The difference is scale. With Additional Options, you build each choice one by one. With a JSON layer, you maintain one JSON file with all your presets, and every field in it (name, color, landmark, whatever you include) comes along with the buyer's selection, ready to use elsewhere in your artwork.

Right now, a JSON layer's selected data is mainly useful in two ways:

• Feeding a Text to Image prompt, so the buyer's pick fills in multiple prompt variables at once (city name, colors, landmark, and so on).
• Acting as a condition for other layers, so you can show or hide a field depending on which record the buyer picked.

2. Add a JSON layer

• On your Artwork Editor, click +Layer > under the Form Elements category, select JSON List.

3. Configure the Json layer settings

• Option Title: the label buyers see above the dropdown.
• JSON File URL: a link to your JSON file. Must start with https://, and the file must be a JSON array of records.

• Option display template: controls what's shown per item in the dropdown, e.g. {{name}} — {{country}}.

• Default value: pre-selects a record by name when the buyer opens the form with nothing chosen yet. It's matched against your JSON's name field; if nothing matches, the field just starts empty.

Sample record (from the cities example):

{
    "id": "city_004",
    "name": "Tokyo",
    "alias": "Eastern Capital",
    "country": "Japan",
    "continent": "Asia",
    "colors": "Red and White",
    "founded": "1603",
    "nickname": "Eastern Capital",
    "landmark": "Tokyo Tower",
    "famous_food": "Sushi",
    "popular_activity": "Cherry Blossom Viewing"
}

Only name needs to be unique. Every other field is entirely up to you, you decide what fields exist in your own file, and you can pull any of those fields into your Text to Image prompt.

4. Structure your JSON file

Your file needs to be a JSON array, a list of records wrapped in square brackets, where each record is one selectable option.

[
  {
    "id": "city_004",
    "name": "Tokyo",
    "alias": "Eastern Capital",
    "country": "Japan",
    "continent": "Asia",
    "colors": "Red and White",
    "founded": "1603",
    "nickname": "Eastern Capital",
    "landmark": "Tokyo Tower",
    "famous_food": "Sushi",
    "popular_activity": "Cherry Blossom Viewing"
  },
  {
    "id": "city_001",
    "name": "Paris",
    "alias": "City of Light",
    "country": "France",
    "continent": "Europe",
    "colors": "Blue, White and Red",
    "founded": "3rd Century BC",
    "nickname": "City of Love",
    "landmark": "Eiffel Tower",
    "famous_food": "Croissant",
    "popular_activity": "River Seine Cruise"
  }
]

Every record needs a name field, and its value must be different from every other record's name. Records with a blank or duplicate name value are skipped, they won't show up as a pickable option.

Every other field is entirely up to you. You decide what fields exist in your own file, and every field is available to reference elsewhere in your artwork (see the Text to Image article for how to pull specific fields into a prompt).

{
  "id": "school_005",
  "name": "University of California, Berkeley",
  "aliases": ["UC Berkeley", "Berkeley", "Cal"]
}

Neither will an array of objects:

{
  "id": "university-of-washington",
  "school_name": "University of Washington",
  "short_name": "UW",
  "colors": [
    {
      "name": "Husky Purple",
      "hex": "#32006E",
      "prompt_description": "rich deep warm collegiate purple"
    },
    {
      "name": "Husky Gold",
      "hex": "#B7A57A",
      "prompt_description": "muted warm antique collegiate gold"
    }
  ]
}

[
  {
    "id": 1,
    "username": "johndoe",
    "email": "john.doe@example.com",
    "name": {
      "first": "John",
      "last": "Doe"
    },
    "age": 32,
    "role": "admin",
    "active": true,
    "created": "2023-01-15"
  },
  {
    "id": 2,
    "username": "janesmith",
    "email": "jane.smith@example.com",
    "name": {
      "first": "Jane",
      "last": "Smith"
    },
    "age": 28,
    "role": "editor",
    "active": true,
    "created": "2023-02-20"
  }
]

You can target a field inside the nested name object by chaining another dot: {{Option Title.name.first}} pulls in "John" for the first record.

5. Known limitations

• A JSON List layer can be duplicated normally, but it can't be Duplicate & Linked to another artwork. Use regular duplication instead.
• JSON List doesn't currently support Global Options, you can't define one JSON List once and reuse it across multiple products the way you can with other layer types.
• The file must load within 15 seconds and must be a valid JSON array, otherwise the dropdown shows an error with a Retry button for the buyer.
• Field values must be strings, numbers, booleans, or a single nested object, arrays aren't supported.

Updated on: 07/09/2026