JSON Schema thực sự giải quyết điều gì
Kết luận: Schema quản lý cấu trúc và kiểu dữ liệu, không quản lý ý nghĩa nghiệp vụ. Nó chặn trường thiếu, kiểu sai và enum ngoài phạm vi, còn những quy tắc như số tiền phải lớn hơn 0 vẫn nằm trong mã.
Tóm lại: hãy để JSON Schema thực thi cấu trúc, kiểu, phạm vi và định dạng, còn quy tắc xuyên trường, bất biến nghiệp vụ và trạng thái bên ngoài nằm trong mã; hãy áp dụng nó cho API công khai và payload dùng chung, không phải cho một dịch vụ nội bộ năm trường.
Nó trả lời "dữ liệu này có đúng hình dạng không", chứ không phải "dữ liệu này có hợp lý không".
Nó làm tốt việc gì
Tính đầy đủ về cấu trúc. Trường nào bắt buộc phải có, có cho phép trường thừa không (required, additionalProperties).
Kiểu. port là số hay chuỗi, tags là mảng hay vô hướng. Chỉ riêng điều này đã loại bỏ rất nhiều mã phòng vệ trong hệ thống đa ngôn ngữ.
Phạm vi. enum, minimum/maximum, độ dài chuỗi và mảng.
Định dạng. format cho ngày, email, URI và UUID, với các validator thực thi chúng.
Lồng nhau. Mỗi tầng của đối tượng và mảng có ràng buộc riêng, và lỗi mang theo đường dẫn chính xác.
Tài liệu. Schema chính là hợp đồng. Thay đổi một trường và diff cho thấy phạm vi ảnh hưởng. Nó còn sinh ra kiểu và biểu mẫu, nên một định nghĩa phục vụ nhiều bên tiêu thụ.
Nó không thể làm gì
Phụ thuộc xuyên trường. "Thời điểm kết thúc phải sau lúc bắt đầu" có thể diễn đạt bằng if/then/else, nhưng kết quả dài và khó đọc hơn ba dòng mã.
Bất biến nghiệp vụ. "Tồn kho không được âm" phụ thuộc vào trạng thái bên ngoài. Schema chỉ thấy một tài liệu.
Ngữ nghĩa. price: -100 thỏa mãn {"type": "number"} một cách hoàn hảo. Liệu đó có phải một mức giá hợp lệ thì nằm ngoài hiểu biết của Schema.
Một cách phân chia khả thi
| Tầng | Bên chịu trách nhiệm |
|---|---|
| Cú pháp: đây có phải JSON hợp lệ | Bộ phân tích |
| Cấu trúc: trường, kiểu, phạm vi, định dạng | JSON Schema |
| Ngữ nghĩa: xuyên trường, quy tắc nghiệp vụ, trạng thái bên ngoài | Mã ứng dụng |
| An toàn: kích thước, độ sâu, tần suất | Gateway / middleware |
Gộp tất cả vào một chỗ và Schema sẽ phình tới hàng trăm dòng với năm tầng if/then. Đến lúc đó người ta sẽ tìm cách lách qua nó.
Khi nào nó đáng dùng
- API công khai có bên tiêu thụ chưa biết
- Nhiều dịch vụ cùng đọc một payload
- Hệ thống cấu hình điều khiển, nơi lỗi chính tả phải thất bại nhanh
- Sinh kiểu hoặc biểu mẫu từ hợp đồng
Với một dịch vụ nội bộ nhỏ năm trường và một giao diện, kiểm tra viết tay dễ bảo trì hơn. Đưa Schema vào đó là công việc âm.
Câu hỏi thường gặp
Làm sao quyết định có nên áp dụng JSON Schema không?
Hãy cân nhắc bên tiêu thụ công khai, nhiều dịch vụ cùng đọc một payload, và nhu cầu sinh kiểu hoặc biểu mẫu. Với một dịch vụ nội bộ nhỏ năm trường và một giao diện, kiểm tra viết tay dễ bảo trì hơn.
Vì sao quy tắc xuyên trường nên nằm trong mã?
"Thời điểm kết thúc phải sau lúc bắt đầu" có thể nhồi vào if/then/else, nhưng kết quả dài và khó đọc hơn vài dòng mã. Schema cũng không thấy được trạng thái bên ngoài.
Schema có nên validate kích thước payload và độ sâu lồng nhau không?
Không. Schema mô tả cấu trúc, không mô tả kích thước hay độ sâu; những giới hạn đó thuộc về tầng gateway hoặc middleware.