Hướng dẫn thực tế

Trình tạo JSON Schema — Hướng dẫn sử dụng và nguyên lý kỹ thuật

Tự động tạo JSON Schema từ dữ liệu JSON với suy luận kiểu thông minh

Mở công cụ

Tổng quan

JSON Schema là bộ từ vựng dùng để chú thích và xác thực tài liệu JSON. Nó đóng vai trò như hợp đồng dữ liệu, định nghĩa cấu trúc mong đợi, kiểu dữ liệu và quy tắc kiểm tra. JSON Schema được ứng dụng rộng rãi trong tài liệu API, xác thực dữ liệu, sinh mã và kiểm thử, giúp đảm bảo chất lượng và tính nhất quán của dữ liệu giữa các hệ thống.

Khái niệm chính

Đặc tả JSON Schema

JSON Schema là ngôn ngữ khai báo mô tả cấu trúc và quy tắc kiểm tra của dữ liệu JSON. Các từ khóa như "Loại", "properties", "Bắt buộc", "Các mục", "additionalProperties" giúp định nghĩa ràng buộc. Đặc tả phát triển qua nhiều bản Draft, trong đó Draft 2020-12 là phiên bản ổn định mới nhất. Bản thân schema là tài liệu JSON hợp lệ dùng cho xác thực, tài liệu và sinh mã.

Thuật toán suy luận kiểu

Trình tạo phân tích giá trị JSON để suy luận kiểu tương ứng. Với kiểu nguyên thủy, công cụ nhận diện chuỗi, số, số nguyên, boolean hoặc null. Với chuỗi, thuật toán dùng regex để phát hiện email, URI, ngày, giờ, IPv4, IPv6 và các định dạng chuẩn khác. Với đối tượng, công cụ sinh schema lồng nhau theo từng thuộc tính; với mảng, suy luận dựa trên phần tử đầu tiên.

Từ khóa xác thực

JSON Schema cung cấp hệ từ khóa phong phú: "Loại" cho kiểu dữ liệu, "Bắt buộc" cho trường bắt buộc, "properties" cho đối tượng, "Các mục" cho mảng, "minimum"/"maximum" cho số, "minLength"/"maxLength" cho chuỗi, "pattern" cho regex, "enum" cho danh sách giá trị, "Định dạng" cho kiểm tra ngữ nghĩa như email hoặc URL. Kết hợp các từ khóa này giúp xây dựng bộ quy tắc toàn diện.

Phiên bản Schema

JSON Schema đã phát triển qua nhiều Draft: Draft-04 (2013, phổ biến), Draft-07 (2018, bổ sung if/then/else), Draft 2019-09 (giới thiệu $recursiveRef) và Draft 2020-12 (mới nhất với $dynamicRef và hệ từ vựng cải tiến). Mỗi phiên bản giữ khả năng tương thích ngược và bổ sung tính năng mới. Từ khóa $schema xác định schema đang dùng phiên bản nào.

Tính năng

Suy luận kiểu thông minh

Tự động nhận diện kiểu dữ liệu từ giá trị JSON như chuỗi, số, boolean, mảng, đối tượng và null; phát hiện định dạng email, URL, ngày giờ

Hỗ trợ đa phiên bản

Tương thích JSON Schema Draft 2020-12, 2019-09, Draft-07 và Draft-04 với $schema URI chuẩn và tính năng đặc thù từng phiên bản

Quy tắc kiểm tra

Cấu hình trường bắt buộc, ràng buộc kiểu, kiểm tra định dạng và chế độ nghiêm ngặt với additionalProperties để xây dựng schema vững chắc

Tùy chỉnh linh hoạt

Chủ động thêm/bớt mô tả trường, ví dụ và quy tắc kiểm tra phù hợp nhu cầu tài liệu API và xác thực dữ liệu

Câu hỏi thường gặp

JSON Schema là gì và vì sao nên dùng?

JSON Schema là bộ từ vựng để chú thích và xác thực tài liệu JSON. Nó mô tả cấu trúc dữ liệu, ràng buộc và quy tắc bằng chính định dạng JSON. Lợi ích gồm: tự động kiểm tra dữ liệu, tài liệu API rõ ràng, hỗ trợ sinh mã, cải thiện trải nghiệm dev và phát triển dựa trên hợp đồng. JSON Schema được dùng rộng rãi trong thiết kế API, kiểm tra cấu hình và tạo biểu mẫu.

Công cụ có tạo schema từ mọi JSON không?

Có. Công cụ phân tích bất kỳ JSON hợp lệ nào và sinh schema tương thích Draft-07. Nó xử lý đầy đủ các kiểu: đối tượng, mảng, chuỗi, số, boolean và null; suy luận kiểu, trường bắt buộc và mẫu cơ bản từ dữ liệu mẫu. Với trường hợp phức tạp, bạn có thể cần tinh chỉnh thêm schema.

Schema sinh ra chính xác tới mức nào?

Schema được sinh dựa trên dữ liệu mẫu nên nhận diện đúng kiểu và cấu trúc, nhưng ràng buộc được giả định ở mức an toàn. Ví dụ, công cụ không thể biết số phải dương hay chuỗi phải tuân theo pattern cụ thể nếu điều đó không xuất hiện trong mọi mẫu. Hãy luôn rà soát và bổ sung quy tắc đặc thù miền nghiệp vụ.

Có thể dùng schema sinh ra để xác thực không?

Hoàn toàn được. Schema tạo ra tương thích với các trình xác thực JSON Schema như Ajv, joi hoặc json-schema library. Bạn có thể dùng để kiểm tra request/response API, tệp cấu hình hay dữ liệu đầu vào. Schema tuân theo đặc tả Draft-07 và tích hợp tốt với Node.js, Python, Java hoặc bất kỳ ngôn ngữ nào hỗ trợ JSON Schema.

Khác biệt giữa các bản Draft JSON Schema là gì?

JSON Schema phát triển qua nhiều Draft (Draft-04, Draft-06, Draft-07, 2019-09, 2020-12). Công cụ sinh schema Draft-07 vì phổ biến và ổn định. Điểm khác biệt: Draft-07 bổ sung if/then/else, Draft 2019-09 giới thiệu hệ từ vựng và $recursiveRef, Draft 2020-12 thêm $dynamicRef và unevaluatedProperties. Với đa số trường hợp, Draft-07 đáp ứng tốt cả tính năng lẫn khả năng tương thích.

Tài liệu liên quan

Trình tạo JSON Schema

Mở công cụ để trải nghiệm các tính năng này.

Mở công cụ