JSON Schema üretici
Bir ya da birden çok örnek JSON yapıştırın; araç tür, zorunlu alan, iç içe nesne ve dizi yapısını çıkarıp draft 2020-12 şeması yazar. Tarih, e-posta, URI ve UUID biçimlerini algılar, az sayıda tekrar eden metinler için enum önerir ve ürettiği şemayı örneklerinize karşı otomatik sınar.
Tek bir nesne, bir dizi ya da birden çok örnek yapıştırın. Birden çok örnek için bir dizi (her öğe bir örnek) ya da satır başına bir JSON belgesi kullanın; ne kadar çok örnek verirseniz zorunlu/isteğe bağlı ayrımı o kadar doğru olur.
Şema tarayıcınızda üretilir; örnek JSON'larınız hiçbir yere gönderilmez, saklanmaz.
Üretilen şema
Örnek JSON yapıştırın ya da örneği yükleyin.
Üretilen şema bir başlangıç taslağıdır: yalnızca örneklerde gördüklerini anlatır. Görülmeyen değerler, aralık sınırları (minimum, maxLength), desenler ve iş kuralları yoktur; enum önerisi geçerli ama görülmemiş değerleri dışlar, format algısı sezgiseldir. Şemayı kendi sistemlerinizin gerçek kurallarına göre gözden geçirip düzeltin, ardından kendi yığınınızdaki bir doğrulayıcıyla (ör. Ajv, jsonschema) kullanın.
Sistemleriniz arasındaki veri sözleşmelerini (şema, sürümleme, doğrulama ve hata yönetimi) birlikte tasarlamak ister misiniz?
Görüşme talep edin01
Nasıl kullanılır
A
Bir ya da birden çok örnek JSON yapıştırın (bir dizi ya da satır başına bir belge); ne kadar çok ve ne kadar çeşitli örnek verirseniz şema o kadar iyi olur.
B
Zorunlu alanlar, birden çok tür, biçim algısı, enum eşiği ve additionalProperties seçeneklerini ayarlayın; şema anında güncellenir.
C
Şemayı kopyalayın ya da indirin. "Kendini doğrulama" göstergesi, şemanın her örneği kabul edip etmediğini söyler; sonra şemayı gerçek kurallarınıza göre elden geçirin.
02
Şema örneklerden nasıl çıkarılır?
Araç tüm örnekleri tek bir yapıda birleştirir: her alan için hangi türlerin kaç kez görüldüğünü, nesnelerde hangi alanların hangi örneklerde bulunduğunu, dizilerde öğelerin neye benzediğini sayar. Sonra bu sayımı JSON Schema'ya çevirir: nesneler için properties ve required, diziler için items, değerler için type.
Tamsayı olan her sayı integer, kesirli sayı görülmüşse number yazılır (number, integer'ı da kapsar). JSON'da 1 ile 1.0 aynı sayıdır; ayrıştırıcı ikisini ayırt etmez. Boş diziler tür bilgisi taşımaz; yalnızca diğer örneklerdeki dizilerden öğe şeması çıkar.
03
required, null ve birden çok tür
Varsayılan davranışta bir alan, o nesnenin göründüğü her örnekte bulunuyorsa zorunludur; bir örnekte bile eksikse isteğe bağlı kalır. Bu yüzden tek bir örnek verirseniz her alan zorunlu çıkar: alanın isteğe bağlı olduğunu anlamak için onu içermeyen bir örnek de görmek gerekir. null değer görülürse tür listesine null eklenir ("type": ["string", "null"]); alan hiç yoksa bu başka bir şeydir ve required ile anlatılır.
Aynı konumda birden çok tür görülürse iki yazım seçeneği vardır: type dizisi (kısa; properties, items ve format yalnızca ilgili türe uygulanır) ya da anyOf (her tür ayrı bir şema). Diziler tuple değil liste sayılır: tüm öğeler tek bir items şemasında birleşir.
04
Üretilen şemayı gözden geçirin
Örnekler yalnızca gördüklerinizi anlatır. Üç yerde özellikle dikkatli olun: enum önerisi yalnızca az sayıda ve tekrar eden metin değerleri için yapılır, ama bu değerlerin gerçekten kapalı bir küme olup olmadığını siz bilirsiniz; format yalnızca konumdaki bütün metinler aynı biçime uyuyorsa eklenir ve sezgiseldir; additionalProperties: false karşı tarafın ileride alan eklemesini kırar.
Araç ürettiği şemayı, JSON Schema doğrulayıcısıyla her örneğe karşı sınar. Bu, şemanın örneklerinizi kabul ettiğinden emin olmanızı sağlar (ör. "Görülen her alan" gibi bir seçenek örnekleri dışarıda bırakıyorsa görürsünüz), ama şemanın iş kurallarınızı doğru ifade ettiğini kanıtlamaz.
Sık sorulanlar
- Tek bir örnek yeterli mi?
- Şema çıkar ama zayıf olur. Tek örnekte her alan zorunlu görünür, her tür tek tür sanılır ve null ya da farklı türlü değerler görülmez. Mümkün olduğunca çok ve çeşitli örnek verin: alanı olmayan, null olan, boş dizili, uç değerli örnekler.
- required listesi neden beklediğimden farklı?
- Varsayılanda yalnızca nesnenin göründüğü her örnekte bulunan alanlar zorunludur. Sizin sözleşmenizde zorunlu ama örneklerinizde hep dolu olan alanlar zaten zorunlu çıkar; isteğe bağlı olması gerekenleri ise ancak onları içermeyen bir örnekle anlatabilirsiniz. Gerekirse seçeneği "Hiçbiri" yapın ve zorunluları elle ekleyin.
- format ve enum önerilerine güvenebilir miyim?
- Taslak olarak. format yalnızca konumdaki bütün metinler date-time, date, uuid, e-posta ya da URI biçimine uyuyorsa eklenir; tek bir örnek bu kuralı tutturabilir. enum ise yalnızca az sayıda ve tekrar eden değerlerde önerilir ve örneklerde görülmeyen geçerli değerleri dışlar; gerçekten kapalı bir kümeyse tutun, değilse silin.
- Bir alan hem tam sayı hem kesirli geliyorsa ne olur?
- number yazılır; JSON Schema'da number, integer'ı da kapsar. Yalnızca tam sayı görülüyorsa integer yazılır. 1.0 gibi bir değer JSON'da 1 ile aynı sayıdır ve integer sayılır; kesirli değerlerin beklendiği bir alanı yalnızca 1, 2, 3 içeren örneklerle verirseniz integer çıkar.
- additionalProperties: false ne zaman doğru?
- Karşı tarafın gönderebileceği alanları tam olarak siz belirliyorsanız (kendi API'niz, içe aktarma dosyası). Başka bir sistemin yanıtını doğruluyorsanız genellikle yanlıştır: o sistem yeni bir alan eklediğinde doğrulamanız kırılır. Varsayılan olarak kapalıdır, yani bilinmeyen alanlara izin verilir.
- Dizinin öğeleri farklı türdeyse ne olur?
- Hepsi tek bir items şemasında birleşir: öğeler hem metin hem sayı içeriyorsa items için "type": ["integer", "string"] (ya da anyOf) yazılır. Konuma bağlı (tuple) diziler çıkarılmaz; bunun için prefixItems'ı elle yazmanız gerekir.
Veri sözleşmelerinizi birlikte tasarlayalım
CRM, ERP ve üçüncü taraf sistemler arasındaki veri akışları için şema, sürümleme ve hata yönetimi tasarlıyoruz. Ücretsiz keşif görüşmesinde mevcut akışınızı konuşalım.