Tùy chọn giá trị của field
Ba tùy chọn field nhỏ lấp các khoảng trống phổ biến so với những headless CMS
khác: lựa chọn đơn không cho xóa, độ dài văn bản cấu hình được, và chính sách
bộ ký tự cho slug. Cả ba nằm trong object options của field, cạnh các khóa
riêng của interface (choices, placeholder, rows, …), và đều:
- được kiểm tra khi ghi schema — mọi thao tác tạo, cập nhật, đổi tên field
và schema apply đều chạy Zod schema dùng chung trong
packages/contracts/src/schemas/field-options.ts(REST, config-as-code và MCP đều đi quaapps/cms/src/services/schema-service.ts). Tùy chọn không hợp lệ trả về422 INVALID_FIELD_OPTIONS, nêu tên field và khóa. - được thực thi khi ghi item — pipeline kiểm tra trong
apps/cms/src/services/validation.tschạy bên trongItemServicecho create, update, replace, bulk, revert revision, mutation GraphQL và công cụ MCP/agent. Vi phạm trả về400 VALIDATIONvới thông điệp nêu tên field và giới hạn. - tự chọn bật — field không có các khóa này hoạt động y như trước.
Trong Studio, mở một field, vào Interface → Value options. Phần kiểm tra giống hệt chạy ngay tại đó, và nút Save bị khóa khi còn tùy chọn không hợp lệ.
allowClear — lựa chọn đơn không cho xóa
Áp dụng cho interface lựa chọn đơn: select-radio và select-dropdown.
{ "choices": [{ "value": "draft" }, { "value": "final" }], "allowClear": false }
allowClear | Studio | API |
|---|---|---|
bỏ trống / true (mặc định) | radio hiện Clear selection khi đã có giá trị; dropdown giữ lựa chọn rỗng | chấp nhận null / "" |
false | không còn cách xóa khi đã có giá trị | update đặt null hoặc "" lên item có giá trị đã lưu khác rỗng bị từ chối (not_clearable) |
Quan hệ với required:
required: truevốn đã từ chối giá trị rỗng ở mọi lần ghi, nênallowClearkhông bổ sung gì ở đó (Studio luôn ẩn nút xóa với field bắt buộc).required: false+allowClear: falsenghĩa là "được phép bắt đầu rỗng, nhưng một khi đã chọn thì chỉ được đổi, không được xóa". Tạo item không có giá trị, và cập nhật item vẫn còn rỗng, đều được phép.
Đặt allowClear trên interface khác sẽ bị từ chối khi ghi schema.
minLength / maxLength — độ dài văn bản
Áp dụng cho field string và text (input, textarea, slug, …).
{ "maxLength": 2000, "minLength": 20 }
- Độ dài được đếm theo Unicode code point, không phải đơn vị UTF-16: một
emoji như
😀hay một chữ tiếng Việt dựng sẵn nhưệtính là một. Bộ đếm trong Studio dùng cùng cách đếm và không còn đặt thuộc tínhmaxLengthgốc của trình duyệt (vốn đếm theo UTF-16 và sẽ chặn cả dữ liệu hợp lệ). - Chuỗi rỗng được coi là "không có giá trị" với
minLength; dùngrequiredđể cấm giá trị rỗng. - Giới hạn: số nguyên,
minLength≥ 0,maxLength≥ 1, cả hai ≤ 1,000,000, vàminLength≤maxLength. - Nếu field khai báo
lengthlưu trữ,maxLengthkhông được vượt quá nó. - Với kiểu field không phải văn bản, các khóa này vẫn được chấp nhận (chúng đã tồn tại từ trước dưới dạng gợi ý lỏng của Studio) nhưng không được thực thi.
Ví dụ lỗi: excerpt: Field "excerpt" must be at most 2000 characters (Unicode code points); received 2001.
slug — chính sách bộ ký tự slug
Áp dụng cho field string / text, thường đi với interface slug.
{ "slug": { "charset": "ascii", "lowercase": true, "separator": "-" } }
| Khóa | Giá trị | Mặc định |
|---|---|---|
charset | ascii, unicode, custom | — (bắt buộc) |
pattern | pattern giới hạn, chỉ dùng với custom | — |
lowercase | true / false | true |
separator | -, _, . | - |
ascii— chuyển dấu Latin về chữ gốc, rồi giữ các cụm[a-z0-9]nối bằng separator. Tiếng Việt được chuyển đúng:Tiếng Việt→tieng-viet,Đà Nẵng→da-nang,Straße→strasse.unicode— giữ chữ cái, chữ số và dấu kết hợp của mọi hệ chữ (lớp Unicode\p{L},\p{N},\p{M}), chuẩn hóa NFC:Tiếng Việt→tiếng-việt,東京 タワー→東京-タワー.custom— sinh giốngunicode, sau đó phải khớppattern.
Studio định dạng slug khi rời ô nhập bằng hàm slugify dùng chung trong
packages/contracts/src/field/slug.ts và hiện gợi ý khi giá trị vi phạm chính
sách. API chỉ kiểm tra, không viết lại: slug không đúng chính sách bị từ
chối (invalid_slug) nên giá trị được lưu luôn đúng là thứ client gửi lên.
slugify có tính idempotent — chạy lại trên kết quả của chính nó không đổi gì.
Pattern custom an toàn trước ReDoS
pattern custom không bao giờ được engine biểu thức chính quy kiểu backtracking
chạy trên toàn bộ giá trị. Nó phải dùng một tập con giới hạn:
- cho phép: ký tự thường, dấu câu đã escape,
.,\d \w \svà dạng phủ định,\p{…}/\P{…}, lớp ký tự như[a-z0-9-], mỗi thành phần có thể kèm một lượng từ* + ? {n} {n,} {n,m}(cận ≤ 100); chấp nhận^ở đầu và$ở cuối (dù sao toàn bộ giá trị cũng phải khớp); - từ chối: nhóm
( ), phép hoặc|, backreference, lookaround,\b, lượng từ chồng nhau nhưa**, pattern dài hơn 200 ký tự hoặc mở rộng quá 512 vị trí của bộ so khớp.
Mỗi thành phần được biên dịch thành phép thử một ký tự và cả chuỗi được so khớp
bằng mô phỏng Thompson-NFA, nên thời gian so khớp tuyến tính theo độ dài giá trị
(O(length × positions)) bất kể pattern. Pattern như (a+)+$ bị từ chối khi
ghi schema kèm lý do.
{ "slug": { "charset": "custom", "pattern": "^[a-z]{2}/[a-z0-9-]+quot; } }
Hành vi mặc định
Khi không có options.slug, API không kiểm tra slug (giữ nguyên như cũ), còn
Studio định dạng khi rời ô nhập theo ascii / chữ thường / - với giới hạn 80
code point (hoặc options.maxLength). Studio giờ cũng chuyển đ/Đ thành d
thay vì bỏ mất.