JSON List

Layer JSON List giúp bạn kết nối một danh sách các bản ghi (record) có sẵn, được lưu trữ dưới dạng một file JSON duy nhất, để buyer chọn một mục từ dropdown có thể tìm kiếm thay vì bạn phải tự tạo từng option một. Hãy thêm layer này vào bất kỳ artwork nào có nhiều option dùng chung các field giống nhau, ví dụ như danh sách thành phố, trường học, hoặc đội nhóm.

1. JSON layer là gì

Một JSON layer hoạt động khá giống với Additional Option: cả hai đều cho phép buyer chọn từ một danh sách có sẵn. Điểm khác biệt nằm ở quy mô. Với Additional Options, bạn phải tạo từng lựa chọn một. Với JSON layer, bạn chỉ cần duy trì một file JSON chứa tất cả các preset, và mọi field trong đó (tên, màu sắc, địa danh, hay bất cứ thứ gì bạn thêm vào) sẽ tự động đi kèm theo lựa chọn của buyer, sẵn sàng để sử dụng ở những nơi khác trong artwork của bạn.

Hiện tại, dữ liệu được chọn từ JSON layer chủ yếu hữu ích theo 2 cách:

• Đưa vào prompt của Text to Image, để lựa chọn của buyer tự động điền vào nhiều biến (variable) trong prompt cùng lúc (tên thành phố, màu sắc, địa danh, v.v.).
• Làm điều kiện (condition) cho các layer khác, để bạn có thể ẩn/hiện một field tùy theo buyer đã chọn bản ghi (record) nào.

2. Thêm JSON layer

• Trên Artwork Editor của bạn, nhấn +Layer > trong mục Form Elements, chọn JSON List.

3. Cấu hình các setting của JSON layer

• Option Title: nhãn (label) buyer nhìn thấy phía trên dropdown.
• JSON File URL: đường link đến file JSON của bạn. Phải bắt đầu bằng https://, và file phải là một mảng (array) JSON chứa các record.

• Option display template: quyết định nội dung hiển thị cho mỗi mục trong dropdown, ví dụ: {{name}} — {{country}}.

• Default value: chọn sẵn một record theo tên khi buyer mở form mà chưa chọn gì. Giá trị này sẽ được đối chiếu với field name trong file JSON của bạn; nếu không khớp với record nào, field này sẽ để trống.

Ví dụ một record (từ ví dụ về thành phố):

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

Chỉ có name là cần phải duy nhất. Tất cả các field khác hoàn toàn tùy thuộc vào bạn, bạn tự quyết định file của mình sẽ có những field nào, và bạn có thể lấy bất kỳ field nào trong số đó để đưa vào prompt của Text to Image.

4. Cấu trúc file JSON của bạn

File của bạn cần phải là một mảng (array) JSON, tức là một danh sách các record được bọc trong dấu ngoặc vuông, trong đó mỗi record là một option có thể chọn.

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

Mỗi record cần có một field name, và giá trị của nó phải khác với name của mọi record khác. Các record có name để trống hoặc bị trùng sẽ bị bỏ qua, và sẽ không xuất hiện như một option có thể chọn.

Tất cả các field khác hoàn toàn tùy thuộc vào bạn. Bạn tự quyết định file của mình sẽ có những field nào, và mọi field đều có thể được tham chiếu (reference) ở những nơi khác trong artwork (xem bài viết Text to Image để biết cách lấy các field cụ thể đưa vào prompt).

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

Một mảng gồm các object cũng vậy:

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

Bạn có thể trỏ đến một field bên trong nested object name bằng cách nối thêm dấu chấm: {{Option Title.name.first}} sẽ lấy ra "John" cho record đầu tiên.

5. Các giới hạn hiện tại

• JSON List layer có thể được duplicate (nhân bản) bình thường, nhưng không thể Duplicate & Linked sang artwork khác. Hãy dùng cách duplicate thông thường thay thế.
• JSON List hiện chưa hỗ trợ Global Options, bạn không thể định nghĩa một JSON List một lần rồi dùng lại cho nhiều sản phẩm như với các loại layer khác.
• File phải load xong trong vòng 15 giây và phải là một mảng (array) JSON hợp lệ, nếu không dropdown sẽ hiển thị lỗi kèm nút Retry cho buyer.
• Giá trị của field phải là string, number, boolean, hoặc một nested object đơn lẻ, không hỗ trợ array.

Cập nhật vào: 08/09/2026