draft-07 หรือ 2020-12
สรุปสำคัญ: 2020-12 เป็นเวอร์ชันปัจจุบันและเพิ่ม `$defs`, `prefixItems` และ `unevaluatedProperties` แต่เครื่องมือจำนวนมากยังรู้จักแค่ draft-07 เลือกตามสิ่งที่ toolchain ทั้งหมดของคุณรองรับ
สรุปสั้น ๆ: ใช้ 2020-12 สำหรับโปรเจกต์ใหม่ ถอยไปใช้ draft-07 ทันทีเมื่อ validator, code generator หรือเครื่องมือ OpenAPI ตัวใดรองรับแค่ draft-07 และปักหมุด draft ด้วย $schema เสมอ
คำตอบสั้น: 2020-12 สำหรับงานใหม่, draft-07 เมื่อมีส่วนประกอบเก่าบังคับ
เส้นเวลา
| Draft | ปี | จุดเด่น |
|---|---|---|
| draft-04 | 2013 | id แทน $id; ยังพบได้ใน API เก่า |
| draft-06 | 2017 | const, propertyNames |
| draft-07 | 2018 | if/then/else, readOnly, contentMediaType; ความเข้ากันได้ดีที่สุด |
| 2019-09 | 2019 | $defs แทน definitions, unevaluatedProperties |
| 2020-12 | 2020 | prefixItems, $dynamicRef; คำแนะนำปัจจุบัน |
สิ่งที่ 2020-12 ดีขึ้น
tuple ของอาร์เรย์ไม่ใช่กรณีพิเศษอีกต่อไป draft-07 แสดง "สมาชิกตัวแรกคือ A ตัวที่สองคือ B" ด้วย items: [{...}, {...}] บวก additionalItems ส่วน 2020-12 ใช้ prefixItems สำหรับ schema ตามตำแหน่ง และใช้ items สำหรับส่วนที่เหลือ
$defs คือชื่อมาตรฐาน เครื่องมือที่เขียนหลังปี 2019 มองหาที่นี่โดยค่าเริ่มต้น
unevaluatedProperties ทำงานร่วมกับการประกอบ schema เมื่อใช้ allOf นั้น additionalProperties: false จะปฏิเสธฟิลด์ที่นิยามโดยสาขาข้างเคียง แต่ unevaluatedProperties: false พิจารณาเฉพาะพร็อพเพอร์ตี้ที่ทั้ง schema ประเมินจริง ซึ่งเป็นสิ่งที่การประกอบ schema ต้องการ
เมื่อไหร่ที่ draft-07 คือคำตอบที่ถูก
| สถานการณ์ | เหตุผล |
|---|---|
| OpenAPI 3.0 | schema object ของมันเป็นเซตย่อยของ draft-04/07 |
| Validator เก่า (ajv 6, ไลบรารี Java บางตัว) | ไม่รู้จัก prefixItems หรือ $dynamicRef |
| แพลตฟอร์มกำหนดเวอร์ชันตายตัว | low-code platform และ gateway บางตัวปักหมุดไว้ |
| Code generator ที่หยุดอยู่ที่ 07 | คีย์เวิร์ดที่ไม่รู้จักถูกเพิกเฉยเงียบ ๆ |
ทดสอบกรณีสุดท้ายโดยตรง: ป้อน schema ที่ใช้ prefixItems ให้ validator ถ้ามันผ่านโดยไม่บ่นแทนที่จะรายงานคีย์เวิร์ดที่ไม่รู้จัก แสดงว่ามันเพิกเฉยข้อจำกัด — ผลลัพธ์ที่อันตรายที่สุดในทั้งหมด
การผสมเวอร์ชัน
ประกาศ $schema เสมอ ค่าเริ่มต้นต่างกัน: ajv ถือว่าเป็น draft-07 ขณะที่ไลบรารี Python หลายตัวถือว่าเป็น 2020-12 ไฟล์เดียวกันจึง validate ต่างกันในสองที่
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/order.json",
"type": "object"
}
อย่า $ref ข้าม draft พฤติกรรมไม่มีการนิยาม
อัปเกรดเป็นชุด draft สองตัวใน repository เดียวเปลี่ยนคำถาม "กฎไหนใช้ที่นี่" ให้กลายเป็นความรู้เฉพาะตัวของคนในทีม
คำถามที่พบบ่อย
จะตรวจสอบได้อย่างไรว่า validator ของฉันรองรับ 2020-12?
ป้อน schema ที่ใช้ prefixItems ให้ validator error เรื่องคีย์เวิร์ดที่ไม่รู้จักหมายความว่าไม่รองรับ draft; ผ่านเงียบ ๆ หมายความว่ากำลังเพิกเฉยข้อจำกัด ซึ่งแย่กว่า
ทำไมโปรเจกต์หนึ่งควรใช้ draft เดียว?
draft สองตัวใน repository เดียวเปลี่ยนคำถาม "กฎไหนใช้ที่นี่" ให้กลายเป็นความรู้เฉพาะตัวของคนในทีม อัปเกรดเป็นชุดเพื่อให้ทุกไฟล์ตีความเหมือนกัน
ควรประกาศ $schema เสมอไหม?
ควร ค่าเริ่มต้นต่างกัน: ajv ถือว่าเป็น draft-07 ขณะที่ไลบรารี Python หลายตัวถือว่าเป็น 2020-12 ไฟล์เดียวกันจึง validate ต่างกันในสองที่