JSON Schema là cách mô tả cấu trúc của một tài liệu JSON nên như thế nào, bằng cách sử dụng một tài liệu JSON khác. Thay vì xác thực dữ liệu thủ công bằng các điều kiện trong mã, bạn có thể mô tả khai báo các kiểu dữ liệu mong đợi, trường bắt buộc và ràng buộc giá trị, sau đó kiểm tra dữ liệu tự động.
Các từ khóa chính của draft-07
type— kiểu giá trị mong đợi (object, string, number, array, v.v.).required— danh sách các trường của object bắt buộc phải có.properties— mô tả schema cho từng trường của object riêng biệt.enum— giới hạn giá trị trong một tập hợp tùy chọn cụ thể.pattern— xác thực chuỗi bằng biểu thức chính quy, ví dụ cho định dạng số điện thoại.
Ví dụ: pattern cho số điện thoại di động Việt Nam sau đợt đổi đầu số 2018
Năm 2018, các nhà mạng Việt Nam chuyển toàn bộ thuê bao di động từ đầu số 11 chữ số (như 0120, 0121...) sang đầu số 10 chữ số mới (070, 076-079, 081-089...). Một schema viết cho API đăng ký tài khoản mà vẫn dùng pattern cũ chấp nhận số 11 chữ số sẽ âm thầm cho qua những số điện thoại không còn tồn tại thực tế. Pattern hiện tại nên mô tả đúng 10 chữ số bắt đầu bằng 0: "phone": {"type": "string", "pattern": "^0(3|5|7|8|9)\\d{8}$"} — một ví dụ nhắc rằng schema cho định dạng quốc gia cần được cập nhật khi quy định đầu số thay đổi, chứ không phải viết một lần rồi để mãi mãi.
Khác gì với xác thực cú pháp
Xác thực JSON thông thường chỉ kiểm tra xem văn bản có đúng cú pháp hay không — ngoặc, dấu nháy, dấu phẩy đúng chỗ. JSON Schema kiểm tra nhiều hơn thế: một object có trường bắt buộc email không, giá trị của age có phải là số chứ không phải chuỗi, status có nằm trong danh sách giá trị cho phép hay không.
Vì sao cần đến điều này
- Kiểm tra xem phản hồi của một API bên thứ ba có khớp với hợp đồng đã được ghi lại hay không.
- Xác thực tệp cấu hình trước khi triển khai để phát hiện lỗi sớm.
- Ghi lại cấu trúc dữ liệu mong đợi ở một định dạng có thể được kiểm tra tự động ngay lập tức.
additionalProperties: có được thêm trường thừa không
Theo mặc định, JSON Schema cho phép object chứa bất kỳ trường nào ngoài những trường được mô tả trong properties — required và properties chỉ thiết lập mức tối thiểu, chứ không phải danh sách đầy đủ. Nếu cần cấm các trường không xác định, phải thêm rõ ràng "additionalProperties": false — nếu thiếu cờ này, schema vẫn ở trạng thái "mở".