draft-07 atau 2020-12
Intinya: 2020-12 adalah versi terkini dan menambahkan $defs, prefixItems serta unevaluatedProperties, tetapi banyak alat masih hanya mengenal draft-07. Pilih berdasarkan apa yang didukung seluruh toolchain Anda.
Intinya: pakai 2020-12 untuk proyek baru, kembali ke draft-07 begitu ada validator, generator kode atau alat OpenAPI yang hanya mendukungnya, dan selalu patok draft dengan $schema.
Jawaban singkat: 2020-12 untuk pekerjaan baru, draft-07 saat komponen lama memaksanya.
Garis waktu
| Draft | Tahun | Catatan penting |
|---|---|---|
| draft-04 | 2013 | id alih-alih $id; masih umum di API lama |
| draft-06 | 2017 | const, propertyNames |
| draft-07 | 2018 | if/then/else, readOnly, contentMediaType; kompatibilitas terbaik |
| 2019-09 | 2019 | $defs menggantikan definitions, unevaluatedProperties |
| 2020-12 | 2020 | prefixItems, $dynamicRef; rekomendasi terkini |
Apa yang diperbaiki 2020-12
Tuple array tidak lagi menjadi kasus khusus. draft-07 mengungkapkan "elemen pertama adalah A, kedua adalah B" dengan items: [{...}, {...}] plus additionalItems. 2020-12 memakai prefixItems untuk schema per posisi dan items untuk sisanya.
$defs adalah nama standar. Tooling yang ditulis setelah 2019 mencarinya di sana secara default.
unevaluatedProperties bekerja dengan komposisi. Dengan allOf, additionalProperties: false menolak field yang didefinisikan cabang saudara. unevaluatedProperties: false hanya mempertimbangkan properti yang benar-benar dievaluasi oleh keseluruhan schema, yang memang dibutuhkan komposisi.
Kapan draft-07 adalah jawaban yang tepat
| Situasi | Alasan |
|---|---|
| OpenAPI 3.0 | Objek schema-nya adalah subset draft-04/07 |
| Validator lama (ajv 6, sebagian library Java) | Mereka tidak mengenal prefixItems atau $dynamicRef |
| Platform mewajibkan versi tertentu | Sebagian platform low-code dan gateway mematoknya |
| Generator kode yang berhenti di 07 | Keyword tak dikenal diabaikan secara senyap |
Uji kasus terakhir secara langsung: berikan schema dengan prefixItems ke validator Anda. Jika ia lolos tanpa keluhan alih-alih melaporkan keyword tak dikenal, ia mengabaikan batasan itu — hasil paling berbahaya dari semuanya.
Mencampur versi
Selalu nyatakan $schema. Default berbeda: ajv mengasumsikan draft-07, beberapa library Python mengasumsikan 2020-12. File yang sama kemudian tervalidasi berbeda di dua tempat.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/schemas/order.json",
"type": "object"
}
Jangan $ref antar draft. Perilakunya tidak terdefinisi.
Tingkatkan versi secara bertahap. Dua draft dalam satu repositori mengubah "aturan mana yang berlaku di sini" menjadi pengetahuan tribal.
FAQ
Bagaimana cara memeriksa apakah validator saya mendukung 2020-12?
Berikan schema yang memakai prefixItems ke validator. Error keyword tak dikenal berarti ia tidak mendukung draft itu; lolos secara senyap berarti ia mengabaikan batasan, yang lebih buruk.
Mengapa satu proyek sebaiknya memakai satu draft saja?
Dua draft dalam satu repositori mengubah "aturan mana yang berlaku di sini" menjadi pengetahuan tribal. Tingkatkan versi secara bertahap agar setiap file berbagi penafsiran yang sama.
Haruskah saya selalu menyatakan $schema?
Ya. Default berbeda: ajv mengasumsikan draft-07 sementara beberapa library Python mengasumsikan 2020-12, sehingga file yang sama bisa tervalidasi berbeda di dua tempat.