Trình Tạo JSON Schema

JSON Schema Dùng Để Làm Gì

JSON Schema là một cách khai báo để mô tả một tài liệu JSON nên trông như thế nào: nó có những thuộc tính gì, các thuộc tính đó giữ kiểu nào, cái gì bắt buộc và cái gì tùy chọn, và những giá trị nào hợp lệ. Đó là tương đương trong thế giới JSON của XSD đối với XML hay một định nghĩa bảng cơ sở dữ liệu. Dự án chính thức nằm ở json-schema.org.

Nơi bạn sẽ gặp nó trong thực tế:

• Hợp đồng API. OpenAPI 3.1 (phát hành tháng 2 năm 2021) nhúng JSON Schema trực tiếp: mọi thân yêu cầu và thân phản hồi trong một spec API hiện đại được mô tả bằng một mảnh JSON Schema.
• Autocomplete và kiểm chứng trong IDE. settings.json của VS Code, package.json và tsconfig.json của dự án bạn, tệp workflow.yml của GitHub Actions đều autocomplete và lint dựa vào các JSON Schema đã công bố.
• Kiểm chứng phía máy chủ. Express / Fastify / Spring / Flask / FastAPI / Echo đều tích hợp với các trình kiểm chứng JSON Schema (AJV, jsonschema, fastjsonschema) để từ chối thân yêu cầu sai dạng trước khi chúng chạm tới logic nghiệp vụ.
• Sinh mã. Công cụ như quicktype, json-schema-to-typescript, và datamodel-code-generator biến lược đồ thành struct Go, kiểu TypeScript, dataclass Python, POJO Java, v.v., cung cấp các kiểu không phụ thuộc ngôn ngữ từ một nguồn duy nhất.
• Tài liệu. Một lược đồ đồng thời cũng là tài liệu có thể đọc được bằng máy cho bất kỳ dữ liệu hình dạng JSON nào bạn công bố.

Các Bản Nháp Bạn Sẽ Thấy Trong Thực Tế

Đặc tả JSON Schema đã được công bố như một loạt bản nháp. Bản nháp ổn định hiện tại là 2020-12 (theo trang đặc tả chính thức: "The current version is 2020-12"). Các bản nháp bạn có thể gặp:

• Draft 4, cũ nhưng vẫn còn dùng; OpenAPI 3.0 đã dùng một tập con mở rộng của JSON Schema Specification Wright Draft 00 (đôi khi được gọi không chính thức là Draft 5), gần nhưng không giống hệt Draft 4.
• Draft 6, Draft 7, Draft 7 (2018) là bản nháp sản phẩm chiếm ưu thế suốt nhiều năm và vẫn rất phổ biến trong các công cụ kế thừa.
• Draft 2019-09, bản nháp đầu tiên dùng quy ước định danh năm-tháng; giới thiệu $defs bên cạnh từ khóa definitions cũ.
• Draft 2020-12, bản nháp ổn định hiện hành và là thứ mà trình sinh này phát ra. Đồng bộ với OpenAPI 3.1.

Khi nghi ngờ, hãy chọn bản nháp phù hợp với trình kiểm chứng của bạn. AJV (trình kiểm chứng JavaScript phổ biến nhất) hỗ trợ Draft 04, 06, 07, 2019-09, và 2020-12 với opt-in tường minh. jsonschema trong Python cũng vậy. Nếu bạn không biết người tiêu thụ ở dưới muốn gì, 2020-12 là mặc định an toàn cho công việc mới.

Các Kiểu Tích Hợp

JSON Schema mô tả bảy kiểu cơ bản tương ứng với các loại giá trị của JSON:

Các từ khóa ghép cho phép bạn pha trộn-kết hợp: oneOf (chính xác một), anyOf (ít nhất một), allOf (tất cả), not (đảo ngược). Cộng thêm enum cho một danh sách hữu hạn các giá trị được phép và const cho một giá trị cố định duy nhất.

Một Lược đồ Tự Sinh Có Thể và Không Thể Cho Bạn Biết Điều Gì

Suy luận một lược đồ từ một ví dụ JSON duy nhất là mạnh nhưng có giới hạn. Trình sinh có thể phát hiện:

• Kiểu của mọi giá trị lá (chuỗi vs số vs boolean vs mảng vs đối tượng).
• Cấu trúc của các đối tượng và mảng lồng nhau.
• Các khóa xuất hiện trong ví dụ (và đánh dấu required nếu bạn chọn).

Không thể phát hiện:

• Trường tùy chọn. Một khóa trong ví dụ của bạn có thể là tùy chọn trong spec thật, nhưng một ví dụ duy nhất không nói cho bạn biết là khóa nào. Theo mặc định mọi thứ trông như bắt buộc.
• Gợi ý định dạng. Chuỗi "2024-04-12" trông giống ngày, nhưng cũng có thể là nhãn văn bản tự do tình cờ có hình dạng ngày. Hãy thêm format: date bằng tay nếu trường đó thật sự là ngày.
• Ràng buộc kiểm chứng. Độ dài tối đa, các giá trị enum được phép, mẫu regex: tất cả đều cần đầu vào của con người.
• Chuỗi tài liệu. title, description, và examples trên mỗi trường cải thiện trải nghiệm lập trình viên nhưng cần hiệu chỉnh thủ công.
• Các biến thể. Nếu một trường có thể là chuỗi hoặc số tùy ngữ cảnh, một ví dụ duy nhất sẽ chọn một và bỏ qua cái kia. Hãy kết hợp nhiều ví dụ hoặc dùng oneOf thủ công.

Hãy coi đầu ra như một điểm bắt đầu đã hoàn tất 70%. Những bổ sung có giá trị (trường nào thực sự bắt buộc, định dạng chuỗi nào áp dụng, khoảng giá trị nào được phép, ý nghĩa của từng trường) là bước hiệu chỉnh thủ công của con người.

Hai Cạm Bẫy Tinh Tế Đáng Biết

• format mang tính tham vấn theo mặc định trong 2020-12. Bộ từ vựng format-annotation đánh dấu format: email như một gợi ý, không phải quy tắc kiểm chứng cứng, trừ khi trình kiểm chứng của bạn chủ động bật format-assertion. Vì vậy một chuỗi không khớp regex email vẫn lọt theo mặc định. Chế độ strict của AJV và gói ajv-formats thêm kiểm chứng định dạng đầy đủ; hãy kiểm tra mặc định của trình kiểm chứng trước khi dựa vào kiểm tra định dạng cho đầu vào quan trọng về bảo mật.
• additionalProperties: false không phối hợp tốt với allOf. Nếu bạn ghép các lược đồ với allOf để kiểm chứng kiểu kế thừa, additionalProperties: false trên một nhánh không thấy các property được định nghĩa ở nhánh anh em, nên các trường hợp lệ vẫn rớt kiểm chứng. Cách sửa trong Draft 2019-09+ là unevaluatedProperties: false, vốn nhận biết được sự ghép nối.

JSON Schema so với Zod / Joi / Yup so với kiểu TypeScript

Nhiều công nghệ chồng lấn với vai trò của JSON Schema; mỗi cái có điểm mạnh riêng:

• JSON Schema. JSON khai báo, kiểm chứng tại thời gian chạy, không phụ thuộc ngôn ngữ. Thắng thế khi hợp đồng API vượt qua ranh giới ngôn ngữ (ví dụ một máy chủ Go, một đường ống dữ liệu Python và một frontend TypeScript cùng tiêu thụ một API).
• Kiểu TypeScript. Chỉ tại thời gian biên dịch. Đẹp cho an toàn kiểu trong tiến trình bên trong một codebase TS nhưng biến mất tại thời gian chạy, không cung cấp kiểm chứng cho JSON đến. Công cụ như json-schema-to-typescript sinh kiểu từ một lược đồ để có cả hai mặt tốt nhất.
• Zod, Joi, Yup. Kiểm chứng tại thời gian chạy theo lối code-first trong JavaScript hoặc TypeScript, có suy luận TypeScript tích hợp. Một ngôn ngữ duy nhất, nhưng trải nghiệm lập trình viên xuất sắc bên trong ngôn ngữ đó. Lược đồ là đối tượng JS, không phải JSON di động.
• Pydantic và Marshmallow. Các phiên bản Python tương đương: kiểm chứng tại thời gian chạy theo lớp với type hint của Python.

Nếu lược đồ của bạn cần được tiêu thụ bởi nhiều ngôn ngữ hoặc nhiều công cụ (IDE, tooling OpenAPI, trình sinh mã), JSON Schema là nơi phù hợp. Nếu bạn ở trong một ngôn ngữ duy nhất, lựa chọn native của ngôn ngữ đó thường viết dễ chịu hơn.

Trường Hợp Sử Dụng Phổ Biến

• Khởi tạo một spec OpenAPI. Dán một phản hồi API thật, sinh lược đồ, thả vào components.schemas của bạn.
• Sinh kiểu TypeScript / Go / Python qua quicktype hoặc tương tự, cung cấp các kiểu không phụ thuộc ngôn ngữ từ một nguồn duy nhất.
• Kiểm chứng đầu vào không tin cậy tại một endpoint máy chủ với AJV / jsonschema / Pydantic.
• Viết autocomplete cho IDE cho một định dạng cấu hình tùy chỉnh. VS Code, các IDE của JetBrains và những công cụ khác đọc JSON Schema để cung cấp autocomplete cho file JSON.
• Tài liệu hóa hình dạng của một tệp cấu hình cho người tiêu thụ ở dưới.
• Di chuyển giữa các định dạng dữ liệu. Một JSON Schema sinh ra từ một nguồn có thể điều phối kiểm chứng, biến đổi, hoặc tài liệu hóa ở dưới.

Sai Lầm Thường Gặp

1. Coi lược đồ tự sinh như spec cuối cùng. Đó chỉ là điểm khởi đầu. Hãy thêm gợi ý định dạng, đánh dấu các trường thật sự tùy chọn, thêm tài liệu, đặt khoảng giá trị.
2. Thiếu khai báo $schema. Các trình kiểm chứng dùng nó để biết áp dụng bản nháp nào. Hãy luôn đặt ở đầu lược đồ.
3. Coi required như một thuộc tính của từng property. Khác với XSD hay lược đồ Mongoose, required trong JSON Schema là một mảng ở cấp đối tượng cha liệt kê tên các property bắt buộc.
4. Quên additionalProperties: false khi bạn muốn kiểm chứng nghiêm ngặt. Mặc định là true, nghĩa là các khóa lạ được im lặng cho phép.
5. Nhầm enum với examples. enum = danh sách giá trị được phép (kiểm chứng). examples = giá trị mẫu chỉ để dùng làm tài liệu (không ảnh hưởng kiểm chứng).
6. Giả định rằng format được cưỡng chế. Theo mặc định trong Draft 2020-12 nó là chú thích, không phải khẳng định; regex email của bạn sẽ không chạy trừ khi bạn chủ động bật.
7. Suy luận tính tùy chọn từ một ví dụ duy nhất. Mỗi khóa trong ví dụ của bạn trở thành bắt buộc theo mặc định. Spec thật hầu như luôn có trường tùy chọn; hãy gỡ chúng khỏi mảng required như một phần của bước hiệu chỉnh.

Thêm Câu Hỏi Thường Gặp

Lược đồ có hoạt động với OpenAPI 3.1 không?

Có. OpenAPI 3.1 (phát hành tháng 2 năm 2021) đã đồng bộ ngôn ngữ lược đồ hoàn toàn với JSON Schema Draft 2020-12, đó chính là thứ trình sinh này phát ra. Hãy thả lược đồ vào components.schemas trong tài liệu OpenAPI của bạn và tham chiếu qua $ref. OpenAPI 3.0 cũ hơn dùng một tập con trước đó; bạn có thể cần điều chỉnh nếu nhắm tới 3.0.

Tôi có thể sinh kiểu trong ngôn ngữ của mình từ lược đồ này không?

Có. quicktype sinh TypeScript, Go, Python, Java, C#, Swift, Kotlin, Rust, Elm và nhiều ngôn ngữ khác từ một JSON Schema. json-schema-to-typescript là một lựa chọn dành riêng cho JS. Hầu hết các ngôn ngữ hiện đại có ít nhất một công cụ chuyển từ lược đồ sang kiểu; lược đồ được sinh ra hoạt động như đầu vào cho tất cả.

Khác biệt giữa $defs và definitions là gì?

Cả hai đều là nơi đặt các sub-schema có thể tái dùng mà bạn có thể $ref ở nơi khác trong tài liệu. definitions là tên kế thừa, dùng trong Draft 04, 06, và 07. $defs là tên hiện hành, được giới thiệu trong Draft 2019-09 và tiếp tục trong 2020-12. Tương đương về mặt chức năng, nhưng hãy dùng $defs cho công việc mới.

JSON của tôi có được gửi đi đâu không?

Không. Việc sinh lược đồ chạy hoàn toàn trong trình duyệt của bạn. JSON được dán vào được phân tích cục bộ, duyệt qua và phát ra dưới dạng lược đồ trong textarea đầu ra. Không có gì được tải lên máy chủ, ghi log, hay giữ lại sau khi bạn đóng tab. Điều này quan trọng vì ví dụ JSON thường chứa dữ liệu thật (hồ sơ khách hàng, phản hồi API nội bộ, thông tin nhân viên) mà bạn không muốn chảy qua bên thứ ba.

Tại sao lược đồ mảng của tôi chỉ mô tả phần tử đầu tiên?

Suy luận từ một ví dụ duy nhất coi mảng là đồng nhất: nó nhìn phần tử đầu tiên và cho rằng phần còn lại cũng vậy. Nếu mảng thật của bạn có thể giữ các hình dạng khác nhau, bạn sẽ cần viết items dưới dạng { "oneOf": [...] } bằng tay. Hoặc chạy trình sinh trên mỗi biến thể riêng biệt và kết hợp các lược đồ.

Tôi có nên dùng trình sinh hay không, hay viết lược đồ bằng tay?

Với một lược đồ nhỏ mà bạn kiểm soát từ đầu đến cuối, viết bằng tay dạy bạn spec nhanh hơn. Với một phản hồi API lớn có hàng chục đối tượng lồng nhau, sinh giúp bạn có bản nháp trong vài giây và bạn dành thời gian tiết kiệm được để hiệu chỉnh ràng buộc, mô tả và mảng required. Hầu hết lập trình viên thực tế làm cả hai: sinh, rồi hiệu chỉnh.