draft-07 atau 2020-12
Inti pati: 2020-12 ialah versi semasa dan menambah $defs, prefixItems dan unevaluatedProperties, tetapi banyak alat masih hanya menyokong draft-07. Pilih mengikut apa yang disokong oleh keseluruhan rantai alat anda.
Pokoknya: guna 2020-12 untuk projek baharu, kembali kepada draft-07 sebaik sahaja mana-mana pengesah, penjana kod atau alat OpenAPI hanya menyokongnya, dan sentiasa tetapkan draf dengan $schema.
Jawapan ringkas: 2020-12 untuk kerja baharu, draft-07 apabila komponen lama memaksa.
Garis masa
| Draf | Tahun | Ketara |
|---|---|---|
| draft-04 | 2013 | id dan bukannya $id; masih biasa dalam API lama |
| draft-06 | 2017 | const, propertyNames |
| draft-07 | 2018 | if/then/else, readOnly, contentMediaType; keserasian terbaik |
| 2019-09 | 2019 | $defs menggantikan definitions, unevaluatedProperties |
| 2020-12 | 2020 | prefixItems, $dynamicRef; saranan semasa |
Apa yang 2020-12 perbaiki
Tuple tatasusunan tidak lagi menjadi kes khas. draft-07 menyatakan "elemen pertama ialah A, kedua ialah B" dengan items: [{...}, {...}] serta additionalItems. 2020-12 menggunakan prefixItems untuk schema khusus kedudukan dan items untuk selebihnya.
$defs ialah nama piawai. Alat yang ditulis selepas 2019 mencarinya secara lalai.
unevaluatedProperties berfungsi dengan komposisi. Dengan allOf, additionalProperties: false menolak medan yang ditakrifkan oleh cabang seiring. unevaluatedProperties: false hanya mempertimbangkan sifat yang benar-benar dinilai oleh keseluruhan schema, iaitu apa yang diperlukan oleh komposisi.
Bila draft-07 ialah jawapan yang betul
| Situasi | Sebab |
|---|---|
| OpenAPI 3.0 | Objek schema-nya ialah subset draft-04/07 |
| Pengesah lama (ajv 6, sesetengah pustaka Java) | Ia tidak mengenali prefixItems atau $dynamicRef |
| Platform mewajibkan sesuatu versi | Sesetengah platform low-code dan gateway menetapkannya |
| Penjana kod yang berhenti pada 07 | Kata kunci tidak diketahui diabaikan secara senyap |
Uji kes terakhir secara langsung: berikan schema prefixItems kepada pengesah anda. Jika ia lulus tanpa aduan dan bukannya melaporkan kata kunci tidak diketahui, ia mengabaikan kekangan itu — hasil paling berbahaya daripada semua.
Mencampurkan versi
Sentiasa isytiharkan $schema. Lalai berbeza: ajv menganggap draft-07, beberapa pustaka Python menganggap 2020-12. Fail yang sama kemudian disahkan secara berbeza di dua tempat.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/order.json",
"type": "object"
}
Jangan $ref merentas draf. Tingkah laku tidak ditentukan.
Naik taraf secara berkumpulan. Dua draf dalam satu repositori menjadikan "peraturan mana yang terpakai di sini" sebagai pengetahuan lisan.
Soalan Lazim
Bagaimana saya menyemak sama ada pengesah saya menyokong 2020-12?
Berikan schema yang menggunakan prefixItems kepada pengesah. Ralat kata kunci tidak diketahui bermaksud ia tidak menyokong draf itu; lulus secara senyap bermaksud ia mengabaikan kekangan itu, yang lebih teruk.
Mengapa satu projek harus menggunakan satu draf sahaja?
Dua draf dalam satu repositori menjadikan "peraturan mana yang terpakai di sini" sebagai pengetahuan lisan. Naik taraf secara berkumpulan supaya setiap fail berkongsi tafsiran yang sama.
Patutkah saya sentiasa mengisytiharkan $schema?
Ya. Lalai berbeza: ajv menganggap draft-07 manakala beberapa pustaka Python menganggap 2020-12, jadi fail yang sama boleh disahkan secara berbeza di dua tempat.