CalConverters

JSON sang JSON Schema

Dán một tài liệu vào và nhận về schema mô tả nó — một bản nháp để bạn sửa, không phải đặc tả hoàn chỉnh. Chạy trong trình duyệt, không tải gì lên.

File không bao giờ rời khỏi thiết bị của bạn
0

Bật khi tài liệu mẫu CHÍNH LÀ hợp đồng. Tắt khi nó chỉ là một ví dụ trong nhiều ví dụ, lúc đó thiếu một khóa không chứng minh được điều gì.

Ngồi viết tay JSON Schema từ một phản hồi API dài là việc nhọc và rất dễ sai một cách khó thấy. Trang này làm phần máy móc: đọc tài liệu mẫu rồi viết ra cấu trúc và kiểu dữ liệu quan sát được, để lại cho bạn phần phán đoán mà một tài liệu mẫu không cung cấp nổi.

Mẫu chứng minh được gì và không chứng minh được gì

Ranh giới này chính là toàn bộ câu chuyện dùng schema sinh tự động cho đúng:

Mẫu chứng minh đượcMẫu không chứng minh được
Có những khóa nàyCó được phép thêm khóa khác không
Giá trị này là chuỗiNó có phải khớp mẫu hay format nào không
Giá trị này bằng 42Khoảng hợp lệ là 1–100 hay không giới hạn
Khóa này có mặtNó bắt buộc, hay chỉ tình cờ có mặt lần này
Mảng này chứa objectNó có được rỗng không, có giới hạn độ dài không

Công cụ cố ý chỉ đứng ở cột bên trái. Mọi thứ ở cột phải để dành cho bạn thêm vào, vì bịa ra ràng buộc chính là cách một schema sinh tự động bắt đầu từ chối tài liệu hợp lệ sau đó ba tháng.

Integer và number

Kiểu được quyết bởi cách con số được viết, không phải bởi giá trị của nó:

  • 42 thành integer
  • 42.0 thành number
  • 4.2e1 thành number
  • 123456789012345678901234567890 thành integer

Trường hợp cuối là chỗ tách công cụ này khỏi phần lớn công cụ khác. Vì số giữ nguyên văn bản gốc thay vì bị parse sang double trước, một mã định danh 30 chữ số vẫn được nhận là số nguyên, thay vì bị hạ cấp ngay khi nó không còn vừa.

Mảng có phần tử lẫn lộn

Mọi phần tử đều được mô tả, rồi các mô tả được gộp thành một schema items duy nhất:

  • Object hợp nhất thuộc tính. Khóa xuất hiện ở vài phần tử mà không có ở phần tử khác vẫn được ghi nhận, nên không mất gì.
  • Danh sách bắt buộc chỉ giữ khóa có mặt ở mọi phần tử. Vắng một lần là bằng chứng khóa đó tùy chọn, và đó là suy luận mạnh nhất mà một tài liệu mẫu cho phép.
  • Giá trị thường khác kiểu thì nới thành kiểu hợp, nên [1, "two"] ra {"type": ["integer", "string"]} chứ không đoán theo phần tử đầu.
  • Mảng rỗng không sinh ra items nào cả.
Mẹo: Hãy đưa vào tài liệu mẫu rộng nhất bạn có — nhiều bản ghi thay vì một, kể cả những bản thiếu khóa tùy chọn. Chính phép gộp mảng ở trên biến độ rộng đó thành một danh sách bắt buộc chính xác.

Về công tắc bắt buộc, và khi nào nên tắt

Công tắc quyết định mọi khóa có mặt trong mẫu có được liệt vào required hay không:

  • Bật khi tài liệu mẫu chính là hợp đồng — một file cấu hình, một fixture, một request body do bạn kiểm soát.
  • Tắt khi mẫu chỉ là một phản hồi trong vô số phản hồi. Một khóa tình cờ lần này không nhận được sẽ vĩnh viễn thành bắt buộc nếu không tắt.

Bên trong mảng, công cụ tự áp luật chặt hơn bất kể công tắc: khóa nào vắng ở dù chỉ một phần tử thì không bao giờ bị đánh dấu bắt buộc cho phần tử đó.

Rồi đem ra đối chiếu

Một schema sinh tự động chỉ đáng giá sau khi bạn đã sửa nó — thêm format, siết khoảng giá trị, quyết định cái gì thật sự tùy chọn. Trang kiểm tra bên cạnh sẽ đối chiếu tài liệu với nó và báo mọi luật bị vi phạm, cũng hoàn toàn trong trình duyệt của bạn.

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

Tài liệu mẫu của tôi có bị tải lên đâu không?
Không. Tài liệu được đọc ngay trong tab trình duyệt bằng engine viết bằng Rust biên dịch sang WebAssembly, và không request nào mang nó rời khỏi máy. Điều này quan trọng hơn vẻ ngoài của nó: cách tự nhiên nhất để dùng một công cụ sinh schema là dán một phản hồi API thật vào, mà đó đúng là thứ bạn không nên dán lên máy chủ của người khác.
Schema sinh ra dùng ngay được chưa?
Hãy coi nó là bản nháp đầu tiên. Tài liệu mẫu chỉ mô tả được thứ nó tình cờ chứa, nên kết quả không có format, không có khoảng giá trị, không có mẫu chuỗi, và không biết gì về những khóa mà mẫu chưa từng cho thấy. Nó làm đúng phần cấu trúc và kiểu dữ liệu, vốn là phần nhọc công, rồi để phần phán đoán lại cho bạn.
Sao một khóa tùy chọn lại bị đánh dấu bắt buộc?
Vì nó có mặt trong mẫu, và sự có mặt là bằng chứng duy nhất mà một tài liệu đơn lẻ đưa ra được. Hãy tắt công tắc đánh dấu tất cả khi mẫu của bạn chỉ là một ví dụ trong nhiều ví dụ chứ không phải bản hợp đồng. Riêng với mảng thì công cụ đã cẩn thận sẵn: khóa nào vắng ở bất kỳ phần tử nào sẽ bị loại khỏi danh sách bắt buộc của phần tử đó.
Nó phân biệt integer với number thế nào?
Dựa vào văn bản gốc, không dựa vào giá trị. Số viết không có dấu chấm thập phân và không có số mũ thì thành integer; còn lại thành number. Nhờ vậy số nguyên 30 chữ số vẫn được gọi là integer, trong khi công cụ nào parse sang double trước sẽ hạ cấp nó ngay khi giá trị không còn vừa.
Mảng có các phần tử không giống nhau thì sao?
Các schema phần tử được gộp lại. Object thì hợp nhất thuộc tính, còn danh sách bắt buộc chỉ giữ những khóa có mặt ở mọi phần tử. Giá trị thường mà khác kiểu thì nới thành kiểu hợp, nên mảng lẫn số với chuỗi sẽ ra một schema phần tử nhận cả hai, thay vì đoán theo phần tử đầu tiên.
Sao mảng rỗng lại không sinh ra schema phần tử?
Vì mảng rỗng không chứng minh được gì cả. Viết một luật cho phần tử của nó là bịa ra ràng buộc mà mẫu chưa từng cho thấy, và bịa ràng buộc chính là cách một schema sinh tự động bắt đầu từ chối những tài liệu vốn hợp lệ.
Nó viết theo bản draft nào?
Mặc định 2020-12, và có sẵn Draft 07 cho những hệ thống chưa chuyển. Lựa chọn này chỉ đổi khóa schema được khai báo và bộ từ vựng dùng kèm; phần cấu trúc suy ra từ mẫu của bạn thì giống nhau ở cả hai.