Skema JSON. Menjadi atau tidak menjadi?

Arsitektur: seni membuat yang tidak perlu perlu.

Frederick Kiesler

Bukan rahasia lagi bagi siapa pun bahwa untuk layanan web apa pun yang menggunakan protokol SOAP dalam format XML, solusi yang andal dan telah teruji waktu adalah pengembangan awal Skema XML ( skema xsd) yang menggambarkan tipe data dan struktur pesan XML. Dengan pendekatan ini, pengembang memiliki keuntungan yang jelas: mereka memiliki aturan standar ketat untuk struktur pesan yang ditetapkan dalam skema, jumlah aturan terbatas, dan mereka memungkinkan Anda untuk mengotomatiskan verifikasi pesan baru dalam format XML.

Tetapi juga diketahui bahwa bahasa XML telah digantikan oleh bahasa markah JSON (JavaScript Object Notation) karena bobotnya yang lebih besar (bobot XML), serta penyebaran gaya arsitektur pengembangan perangkat lunak REST (Transfer Negara) untuk sistem terdistribusi. Meskipun gaya REST itu sendiri tidak memerlukan penggunaan JSON (dapat dikatakan tidak memerlukan apa-apa, tetapi "merekomendasikan"), tetapi sebagai praktik menunjukkan, lebih sering ketika mengembangkan REST API, JSON digunakan untuk menggambarkan isi pesan.

Jadi, praktik mengembangkan API REST dengan pesan JSON telah dengan kuat memasuki kehidupan TI di Rusia (dan bukan hanya milik kita), meskipun pengalaman dalam menggambarkan struktur pesan dalam bentuk Skema XML telah sangat menyederhanakan kehidupan pengembang layanan web pada satu waktu, terus-menerus diabaikan dalam kasus pesan JSON. Tapi tidak semua orang yang tidak bisa tidak bersuka cita.

Ketika pengembang yang akrab dengan Skema XML menghadapi kebutuhan untuk menemukan kembali roda setiap kali dengan parsing dokumen dan menemukan kembali logika validasi, draft Skema JSON yang serupa dibentuk . Ini tersedia di json-schema.org, serta sejumlah dokumen tentang sejarah perubahan dan contoh penggunaan. Dan terlepas dari kenyataan bahwa itu diterbitkan dalam status draf, sudah lama didukung oleh semua platform pengembangan populer dan perpustakaan dalam berbagai bahasa. Skema JSON

sendiri menyediakan kemampuan penataan pesan yang lebih sedikit daripada Skema XML . Apa yang dapat dengan mudah dijelaskan melalui Skema XML tidak akan selalu menjadi tugas sepele untuk diulang menggunakan Skema JSON, jika memungkinkan. Tapi di sini saya akan mempertimbangkan fakta ini sebagai keuntungan. Mengapa? Diketahui bahwa semakin sederhana dan semakin linier algoritma sistem, semakin dapat diandalkan, semakin sederhana struktur dokumen, semakin mudah untuk persepsi, dll. Saya tidak bisa tidak mengutip:



"Segala sesuatu yang cerdik itu sederhana, dan segala sesuatu yang sederhana itu cerdik . " Dan jika tidak mungkin untuk menggambarkan struktur dokumen yang kompleks dan sekumpulan opsi yang dapat diterima menggunakan skema, maka mungkin ada baiknya melihat ke arah penyederhanaan struktur dan logika pembentukan dokumen ini?

Kata pengantar


Jadi tentang apa artikel ini?

Saya ingin menarik lebih banyak manfaat dari menggambarkan pesan JSON yang dikirim oleh Skema JSON. Terlepas dari kenyataan bahwa "di pintu masuk", mengembangkan REST API tanpa skema JSON selalu lebih sederhana dan lebih cepat, tetapi dengan pertumbuhan sistem, ketidakhadirannya dengan satu atau lain cara mengarah pada peningkatan biaya pemeliharaan dan dukungan sistem. Juga, setiap studi awal dari struktur pesan berkontribusi pada organisasi yang lebih baik dari pertukaran pesan, tanpa duplikasi yang tidak perlu dalam pertukaran data dan aturan umum untuk pemrosesan mereka.

Juga, untuk menyebarluaskan informasi dalam komunitas berbahasa Rusia tentang kemungkinan Skema JSON dan aturan untuk bekerja dengannya, saya akan membagikan beberapa pengalaman saya dengan contoh-contoh spesifik dalam kerangka artikel ini.

Perumusan masalah


Sebelum mulai mempelajari JSON dan Skema JSON, saya akan menjelaskan tugas yang akan kami pertimbangkan semua contoh di bawah ini.

Pertimbangkan model manajemen peran dalam suatu organisasi. Kami berasumsi bahwa kami perlu mentransfer informasi referensi tentang model peran yang ada ke sistem yang bergantung pada pesan dalam format JSON dengan menghubungi layanan REST.

Deskripsi tugas:

Organisasi memiliki karyawan, mereka sering harus bekerja secara bersamaan dalam beberapa sistem. Pada saat yang sama, tingkat akses (otoritas) ke satu atau lain komponen sistem (sumber daya) untuk karyawan yang berbeda, tergantung pada peran mereka dalam organisasi, dapat berbeda, dan harus dikontrol selama otorisasi pengguna dalam sistem.

Misalnya, seorang akuntan (peran) akan memiliki akses baca dan edit (operasi / kredensial) ke penggajian (sumber daya) untuk upah semua karyawan, dan seorang analis (peran), misalnya, hanya akan memiliki akses baca (operasi / kredensial) saja sesuai slip pembayaran (sumber daya).

Penting untuk merancang dan menggambarkan model manajemen peran dalam suatu organisasi. Peran yang tersedia, satu set kekuatan yang mungkin dan sumber daya dalam sistem harus ditransfer ke sistem lain berdasarkan permintaan.


Gambar 1. Presentasi komponen model peran

Metode untuk menggambarkan dan menerapkan model peran dapat berbeda, tetapi terlepas dari implementasinya, paling sering dalam model peran dalam kasus ini, kita dapat membedakan komponen dasar berikut:

  1. Peran (mis. Manajer, akuntan, dll.).
  2. Sumberdaya (mis., Dokumen, properti, dll.).
  3. Operasi / otoritas (mis. Membaca, mencetak, membuat, dll.).

Ketika menggambarkan akses berbasis peran (sebagai salah satu opsi yang mungkin), mereka resor untuk membuat matriks akses diskrit berdasarkan entitas yang dipilih, misalnya:

Tabel 1. Matriks akses diskrit.
Sumber: dokumenSumber daya: objek
Peran: manajerbaca, cetakbaca, buat
Peran: akuntanbaca, buatBaca

Selanjutnya dalam artikel ini, pertama-tama kita akan membiasakan diri kita dengan komponen teoritis dari format teks untuk bertukar data JSON dan aturan untuk penataan mereka menggunakan Skema JSON, dan sebagai contoh saya akan memberikan deskripsi entitas referensi untuk peran, sumber daya dan operasi dalam bahasa JSON dan skema JSON mereka di dalam kita. mengatur tugas.

Notasi Objek JavaScript (JSON)


JSON (Notasi Objek JavaScript Bahasa Inggris) adalah format pertukaran data berbasis teks yang berbasis pada JavaScript.

Teori


Bahasa markup JSON mendefinisikan kumpulan tipe data terbatas. Untuk pasangan {"key": value} untuk "key" selalu menggunakan tipe string, untuk "nilai" jenisnya berlaku: string, angka, objek (tipe JSON), array, boolean (true atau false) dan null.


Gambar 2. Tipe data JSON

Gambar tersebut menunjukkan tipe dasar dan contoh penggunaannya. Cukup sederhana, menurut saya.

Sintaks JSON adalah bagian dari sintaks JavaScript, di mana:

  1. Data ditulis sebagai pasangan {"kunci": nilai}.
  2. Data dipisahkan oleh koma.
  3. Kurung kurawal merekam objek.
  4. Array ditulis dalam tanda kurung.
  5. Nama-nama "kunci" peka huruf besar-kecil.


Gambar 3. Sintaks JSON

Praktek


Pertimbangkan contoh direktori peran yang akan kami transfer dalam layanan:


Gambar 4. Deskripsi direktori peran dalam format json

Dari contoh, dapat dilihat bahwa meskipun sejumlah kecil tipe dasar, saat digabungkan, jika digabungkan, kita dapat membuat struktur pesan yang lebih kompleks jika perlu. Di sini, khususnya, saya menggambarkan direktori peran melalui objek array yang berisi objek lain (pada gambar 4 disorot oleh dua persegi panjang).

Dalam bentuk tabel menggunakan alat json-visualisasi, direktori dapat direpresentasikan sebagai berikut:


Gambar 5. Visualisasi direktori peran dalam format JSON

Direktori, secara relatif, mewakili 3 "tabel" untuk menetapkan peran dalam sekelompok administrator, akuntan, dan pekerja. Komposisi "atribut" dapat diperluas, jika perlu.

Representasi visual, menurut pendapat saya, menyederhanakan persepsi deskripsi teks. Kami akan menetapkan struktur serupa untuk dua direktori lainnya. Saya akan memberikan di bawah ini contoh hanya tampilan tabel untuk direktori otoritas (operasi) dan sumber daya.


Gambar 6. Visualisasi direktori izin dalam format JSON


Gambar 7. Visualisasi direktori sumber daya di JSON

Sumber pesan dalam teks Format JSON untuk direktori peran , sumber daya dan izin dapat diunduh / dilihat dari tautan .
Sekarang mari kita beralih ke yang paling menarik: mempelajari Skema JSON dan membuat skema untuk buku referensi kami!

Skema JSON


Teori


Karena skema json ditulis dalam format JSON, ia mendukung semua tipe JSON ditambah tambahan: tipe integer, yang merupakan subtipe dari tipe angka. Skema itu sendiri adalah objek JSON dan dimaksudkan untuk menggambarkan data dalam format JSON. Berikut ini adalah skema tipe data yang digunakan untuk membuat skema itu sendiri:


Gambar 8. JSON Tipe data skema

Seperti yang Anda lihat dari gambar, skema menggunakan semua tipe data yang sama, serta prinsip sintaksis yang sama seperti untuk dokumen JSON biasa, ditunjukkan pada gambar 3.

Sekarang kita akan mempertimbangkan yang paling penting - aturan yang digunakan dalam skema untuk menetapkan batasan dan penataan pesan JSON.

Skema JSON memungkinkan Anda untuk:

  1. JSON.
  2. , — «keywords», .

Beberapa "kata kunci" bersifat deskriptif murni, seperti: "judul", "deskripsi", dll., Yang hanya menggambarkan tujuan skema. Yang lain digunakan untuk mengidentifikasi dokumen: "$ schema". Kata kunci ini digunakan untuk menunjukkan versi skema yang diinginkan. Nilai kata kunci ini harus berupa string yang mewakili URI, misalnya: "$ schema": " json-schema.org/draft-04/schema# ".

Penting untuk dicatat di sini bahwa tidak semua versi dapat didukung oleh alat rangkaian Anda. Tetapi draft ke-4 didukung oleh hampir semua orang. Perubahan terbaru (Skema JSON 2019-09 Catatan Rilis) untuk versi yang berbeda dapat ditemukan di json-schema.org/draft/2019-09/release-notes.html .

Kata kunci yang tersisa digunakan secara langsung untuk memvalidasi dokumen JSON. Kami sekarang akan mempertimbangkannya.

Tabel 2. Analisis struktur Skema JSON. Kata kunci dan contoh penggunaannya.
Sebuah tipeKata kunciContoh / Deskripsi
"Kata kunci" untuk menggambarkan skema"$schema"
"$schema": http://json-schema.org/draft-04/schema#

Digunakan untuk mengatur versi konsep skema.
"$id"
"$id": "http://archi-blair.com/schemas/RolesDictionaryDef.json#"

Digunakan untuk menunjukkan pengidentifikasi unik untuk dokumen atau subcircuits-nya.
"title"
"description"
"examples"
"comment"

{
"title": "JSON schema for dictionary",
"description": " ",
"examples": ["user", "manager"],
"comment": "     ))"
}

Umum "Kata kunci validasi" independen dari jenis data item"enum"
{"enum": [ "administrator", "superuser" ]}

Cek dibuat untuk mencocokkan setidaknya 1 nilai.
"const"
{"const": "user" }

Pemeriksaan dilakukan untuk kepatuhan yang tepat dengan nilai yang ditetapkan.
"type"
{"type": ["number", "string", "null", "boolean"]}
{"type": "array"}

Menentukan jenis data yang akan digunakan skema. Kata kunci ini adalah opsional, dan nilai kata kunci dapat berupa string yang mewakili tipe data yang valid atau array string yang mewakili tipe data yang valid.
Keywords, ,"type": "string"

minLength
maxLength
pattern
contentEncoding
contentMediaType

{
"type": "string",
"minLength": 3,
"maxLength": 10,
"pattern": "^test\\/[a-z-]+$",
"contentEncoding": "base64",
"contentMediaType": "application/json"
}

.
"type": "number" "type": "integer"

minimum
exclusiveMinimum
maximum
exclusiveMaximum
multipleOf

{
  "type": "number",
  "minimum": 1.5,
   "exclusiveMinimum": true,
   "maximum": 12.3,
   "exclusiveMaximum": true,
   "multipleOf": 0.5
}

.
"type": "object"

properties
required
dependencies
minProperties
maxProperties
propertyNames
patternProperties
additionalProperties


"employees": {
 "description": "",
 "type": "array",
  "uniqueItems": true,
   "items": {
     "type": "object",
     "properties": {
           "name": {
               "type": "string",
               "enum": ["employee"],
               "enumNames": [""]
	    },
            "enabled": {
                "type": "boolean",
                "default": true
             }
    },
 "additionalProperties": false
 }
}

, ( ).
"type": "array"

minItems
maxItems
uniqueItems
contains
items
additionalItems


"employees": {
 "description": "",
 "type": "array",
 "uniqueItems": true,
 "items": {
    "type": "object",
    "properties": {
          "name": {
               "type": "string",
               "enum": ["employee"],
               "enumNames": [""]
            },
          "enabled": {
                "type": "boolean",
                "default": true
            }
     },
 "additionalProperties": false
 }
}

, ( ).
"type": "boolean"

{"type": "boolean"}

boolean (true false).
"type": "null"

{"type": "null"}

null «» .
"type": "____"
"format": "____"

{
  "type": "string",
  "format": "date"
}

format . , .. -, , , .
"type": "____"
"default": "____"

{
"enabled": {
	"type": "boolean",
	"default": true
}	

.

, .
"not"
"if-then-else"

{
  "not": {
    "type": "string"
  }
}

, .
,"anyOf"
"oneOf"
"allOf"

{
  "type": "string",
  "anyOf": [
    {"const": "user"},
    {"const": "manager" }
  ]
}

, .
,"$id" "$ref"RolesDictionaryDef.json:

{
"$id": http://archi-blair.com/schemas/RolesDictionaryDef.json#
}

1 $ref ( ):


"items": {
"type": "object",
"minLength": 1,
"properties": {
  "name": {
  "description": "  ",
  "type": "string"
   },
"description": {
  "description": " ",
  "type": "string"
 },
"dictionaryGroup": {
  "$ref": "RolesDictionaryDef.json#/definitions/roles"
    }
},
"additionalProperties": false
}

2 JSON. , $ref .
"$ref" "definitions""$ref": "#/definitions/roles" , «definitions»:

{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": " ",
"type": "object",
"properties": {
"dictionaries": {
   "description": "",
   "type": "array",
   "maxItems": 1,
   "items": {
      "type": "object",
      "minLength": 1,
      "properties": {
               "name": {
                  "description": " ",
                  "type": "string",
                  "enum": [
                     "Roles Dictionary"
                     ]
                 }
       "dictionaryGroups": {
             "$ref": "#/definitions/roles",
             "description": " "
          }
      },
 "additionalProperties": false
   }
  }
 },
 "additionalProperties": false,
     "definitions": {
          "roles": {
             "description": "",
             "type": "object",
             "properties": {
             "administrators": {
             "description": "",
             "type": "array",
             "uniqueItems": true,
             "items": {
             "type": "object",
             "properties": {
                   "name": {
                      "type": "string",
                      "enum": [
                         "administrator", 
                         "superuser"
                          ],
                        "enumNames": [
                          "", 
                          "-   "
                           ]
                         },
                    "enabled": {
                    "type": "boolean",
                    "default": true
                  }
              },
    "additionalProperties": false
      }
    }			
   },
  "additionalProperties": false
  }
 },
 "$id": "http://archi-blair.com/schemas/RolesDictionaryDef.json#"
}

, . $ref definitions.
"$ref"
.
"$ref": " #/definitions/roles"
"$ref": "RolesDictionaryDef.json#/definitions/roles"

, .
, .

Kami memeriksa kata kunci skema JSON, yang memungkinkan kami untuk menggambarkan struktur pesan kami di masa depan dalam format JSON.

Di sini Anda dapat menemukan lebih banyak contoh menggunakan kata kunci.

Praktek


Saat mempertimbangkan contoh skema JSON yang telah dilengkapi, kami akan melanjutkan dengan cara yang sama dengan contoh bekerja dengan pesan sendiri dalam format JSON. Itu kami akan menggunakan representasi visual dalam bentuk pohon dan tabel untuk skema kami direktori peran, sumber daya dan otoritas (operasi), dan dengan teks skema saya mengusulkan untuk membaca pembaca yang tertarik sendiri di git .

Berikut ini adalah diagram untuk referensi peran.


Gambar 9. Contoh Skema JSON untuk direktori peran

Seperti yang kita lihat dalam gambar, skema adalah objek JSON dan menjelaskan pesan kami untuk mengirimkan direktori peran di JSON, yang ditunjukkan pada Gambar 4. Dalam contoh saat ini, dapat ditunjukkan bagaimana menggunakan skema JSON Objek array yang terdiri dari objek dijelaskan.

Skema dari dua direktori lainnya (otoritas dan sumber daya) memiliki struktur yang identik dengan skema untuk direktori peran, jadi saya tidak akan memberikannya di sini, tetapi saya akan memberikan skema yang menggabungkan ketiga direktori.

Sayangnya, skema seluruh direktori selama ekspansi tidak sesuai di layar, jadi kami akan mempertimbangkannya.


Gambar 10. Contoh direktori Skema JSON yang menggabungkan direktori peran, izin dan sumber daya.

Pada gambar, kita melihat bahwa beberapa objek dalam array direktori terhubung menggunakan kata kunci "anyOf".

Juga, mungkin, representasi tabular dari direktori akan lebih visual.

Pertimbangkan fitur penting lain dari skema kami:


Gambar 11. Contoh JSON Schema dari sebuah direktori yang menggabungkan direktori peran, izin dan sumber daya dalam tampilan tabel

Dari gambar tersebut kita melihat bahwa direktori gabungan tidak menggandakan kode dari direktori peran, izin dan sumber daya yang dikembangkan sebelumnya, tetapi menggunakan kata kunci "$ ref "

Direktori yang dipertimbangkan dalam contoh berada di direktori yang sama, tetapi, jika perlu, aturan ini tidak dapat diamati, tetapi dapat ditempatkan di direktori yang berbeda, yang menunjukkan jalur yang benar ke sana ketika menghubungkan. Fitur ini sangat berguna, karena memungkinkan Anda untuk menggunakan kembali skema yang dibuat sebelumnya, hanya menghubungkannya ke struktur yang diinginkan.

Ini menyimpulkan ulasan saya tentang JSON dan Skema JSON. Saya berharap bahwa materi yang disajikan di sini dan contoh-contoh yang dibahas akan berguna dalam mengeksplorasi kemampuan Skema JSON.

Alih-alih sebuah kesimpulan


Saya pikir sudah waktunya untuk mengambil stok. Jadi, apa yang akhirnya dapat diberikan Skema JSON?

  1. Ini dapat membuat hidup lebih mudah bagi pengembang dan meningkatkan kode untuk memvalidasi pesan JSON.
    Dengan kata lain, ini menyederhanakan dukungan dan integrasi perangkat lunak.
  2. Memungkinkan Anda mengembangkan layanan, mengerjakan format dan komposisi data dengan "cadangan" untuk pengembangan sistem di masa depan.
  3. Terapkan verifikasi dokumen dalam database yang berorientasi pada dokumen, berorientasi objek.
  4. Skema JSON dapat membantu menghemat waktu menguji dan mendokumentasikan API.
  5. Sederhanakan dukungan API kompatibilitas mundur.
  6. Memungkinkan Anda mengelola aliran data.
  7. Validasi yang fleksibel saat membuat Skema JSON dalam run-time dengan nilai-nilai dalam "enum" yang diperoleh pada tahap pelaksanaan program.
    Ini dapat digunakan untuk mesin negara atau alur kerja dengan status dalam "enum" (contoh aplikasi dariTsdk dan VolCh)
  8. Skema JSON dapat diterapkan dalam implementasi DTO
    (contoh penggunaan dariamarkevich)

Masing-masing dari kita memutuskan "Menjadi atau tidak menjadi Skema JSON" di proyek-proyek TI kita. Di atas, saya memberikan daftar apa yang saya anggap sebagai keuntungan utama menggunakan sirkuit, dan demi apa yang sudah layak dipikirkan tentang penerapannya dalam proyek.

Mungkin pembaca ingin membantu saya melanjutkan daftar ini?
Saya akan berterima kasih :) Saya

juga akan memberikan daftar tautan, menurut pendapat saya, berguna untuk bekerja dengan JSON dan JSON Schema

  1. .
  2. .
  3. ().
  4. ( ).
  5. - JSON-Schema.
  6. JSON Schema
  7. JSON Schema , ( alemiks), angular ngx-schema-form, AJSF ( anotherpit).

Dan tautan ke repositori git, tempat Anda dapat berkenalan dengan file sumber yang disediakan untuk ditinjau dalam artikel ini: repositori dengan file sumber dari contoh .

Arsitek sistem,
© Irina Blazhina

All Articles