Trình xác thực JSON Schema

Các từ khóa được hỗ trợ

Cốt lõi: type, enum, const, multipleOf, maximum, minimum, exclusiveMaximum, exclusiveMinimum, maxLength, minLength, pattern, maxItems, minItems, uniqueItems, maxContains, minContains, maxProperties, minProperties, required, dependentRequired.

Tổ hợp: allOf, anyOf, oneOf, not.

Bộ áp dụng: properties, patternProperties, additionalProperties, items, prefixItems, contains, propertyNames.

Điều kiện: if, then, else, dependentSchemas.

Tham chiếu: $ref, $defs, $id, $anchor.

Định dạng (có xác thực khi được bật): date-time, date, time, duration, email, hostname, ipv4, ipv6, uri, uuid, regex.

Kết quả lỗi

FAIL  /user/email        format            "not-an-email" is not a valid "email"
FAIL  /user/age          minimum           -3 is less than the minimum 0
FAIL  /orders/0/total    type              "42" is not of type "number"
FAIL  /                  required          missing required property "shippingAddress"

Mỗi lỗi đều bao gồm đường dẫn và từ khóa bị lỗi, giúp bạn dễ dàng tìm thấy trong trình soạn thảo.

Những khác biệt giữa các bản nháp dễ gây rắc rối

Hãy thiết lập đúng bản nháp; việc xác thực một lược đồ bản nháp 04 dưới dạng 2020-12 sẽ diễn giải sai id và một số điểm tinh tế khác.

Các quy trình làm việc điển hình

• Kiểm thử hợp đồng API: Trước khi triển khai, hãy chạy lược đồ OpenAPI đã tạo hoặc cập nhật với các phản hồi mẫu thực tế.
• Tăng cường cấu hình: Kiểm tra từng tệp cấu hình YAML/JSON trong CI với một lược đồ trước khi hợp nhất.
• Nạp dữ liệu: Từ chối sớm các payload không khớp với hình thức mong đợi, kèm theo thông báo lỗi rõ ràng.

Các lỗi phổ biến

• Quên thực thi format. Theo mặc định, hầu hết các trình xác thực đều coi các định dạng không xác định chỉ là chú thích. Hãy bật xác thực định dạng nghiêm ngặt để thực sự từ chối các email và ngày tháng không hợp lệ.
• Lạm dụng oneOf. Nếu hai nhánh của oneOf chồng lấn nhau, tài liệu sẽ thất bại (nó phải khớp chính xác với đúng một nhánh). Hãy dùng anyOf hoặc các mẫu phân biệt.
• Lược đồ chặt chẽ với additionalProperties: false. Việc thêm một trường tùy chọn mới sẽ trở thành một thay đổi phá vỡ tương thích. Hãy bỏ qua nó trừ khi bạn thực sự muốn một đối tượng khép kín.