مخطط JSON. أكون أو لا أكون؟

العمارة: فن صنع الضرورة.

فريدريك كيسلر

ليس سراً على أي شخص أنه بالنسبة لأي خدمة ويب تستخدم بروتوكول SOAP بتنسيق XML ، فإن الحل الموثوق والمختبر للوقت هو التطوير الأولي لمخطط XML ( مخطط xsd) الذي يصف أنواع البيانات وهيكل رسائل XML. باستخدام هذا النهج ، يتمتع المطورون بميزة واضحة: لديهم قواعد موحدة صارمة لهيكل الرسائل التي تم تعيينها في المخطط ، وعدد القواعد محدود ، ويسمح لك بأتمتة التحقق من أي رسالة جديدة بتنسيق XML.

ولكن من المعروف أيضًا أن لغة XML قد حلت محلها لغة ترميز JSON (JavaScript Object Notation) بسبب ثقلها الأكبر (ثقل XML) ، فضلاً عن انتشار النمط المعماري لتطوير برامج REST (نقل الحالة التمثيلية) للأنظمة الموزعة. على الرغم من أن أسلوب REST نفسه لا يتطلب استخدام JSON (يمكن القول أنه لا يتطلب أي شيء على الإطلاق ، ولكن "يوصي") ، ولكن كما يظهر من الممارسة ، في كثير من الأحيان عند تطوير REST API ، يتم استخدام JSON لوصف نص الرسالة.

لذا ، فإن ممارسة تطوير واجهة برمجة تطبيقات REST مع رسائل JSON قد دخلت بقوة في مجال تكنولوجيا المعلومات في روسيا (وليس فقط حياتنا) ، على الرغم من أن الخبرة في وصف هيكل الرسالة في شكل مخطط XML قد سهلت إلى حد كبير حياة مطوري خدمات الويب في وقت واحد ، تم تجاهلها باستمرار في حالة رسائل JSON. ولكن ليس كل من لا يسعه إلا أن يفرح.

عندما واجه المطورون المطلعون على مخطط XML الحاجة إلى إعادة اختراع العجلة في كل مرة مع تحليل المستند وإعادة اختراع منطق التحقق ، تم تشكيل مسودة مخطط JSON مماثلة . وهي متاحة على json-schema.orgبالإضافة إلى عدد من الوثائق حول تاريخ التغييرات وأمثلة الاستخدام. وعلى الرغم من حقيقة أنه تم نشره في حالة المسودة ، فقد تم دعمه منذ فترة طويلة من قبل جميع منصات التطوير والمكتبات الشعبية بلغات مختلفة. يوفر JSON Schema

نفسه إمكانات هيكلية رسائل أقل من XML Schema . ما يمكن وصفه بسهولة من خلال مخطط XML لن يكون دائمًا مهمة تافهة لتكرارها باستخدام مخطط JSON ، إن أمكن. ولكن هنا أعتبر هذه الحقيقة ميزة. لماذا ا؟ من المعروف أنه كلما كانت خوارزمية النظام أبسط وأكثر خطية ، كلما كانت أكثر موثوقية ، كلما كانت بنية الوثيقة أبسط ، كلما كان الإدراك أسهل ، إلخ. لا يسعني إلا أن أقتبس:



"كل شيء عبقري بسيط ، وكل شيء بسيط عبقري" . وإذا لم يكن من الممكن وصف البنية المعقدة للوثيقة ومجموعة الخيارات المقبولة باستخدام المخطط ، فربما يستحق الأمر النظر في اتجاه تبسيط هيكل ومنطق تكوين هذه الوثيقة؟

مقدمة


إذن ما هو هذا المقال؟

أود أن أسترعي المزيد من الانتباه إلى مزايا وصف رسائل JSON التي تم إرسالها بواسطة مخطط JSON. على الرغم من حقيقة أنه "عند المدخل" ، فإن تطوير واجهة برمجة تطبيقات REST بدون أي مخطط JSON يكون دائمًا أبسط وأسرع ، ولكن مع نمو النظام ، فإن غيابه بطريقة أو بأخرى يؤدي إلى ارتفاع في تكلفة صيانة النظام ودعمه. كما أن أي دراسة أولية لهيكل الرسالة تساهم في تنظيم أفضل لتبادل الرسائل ، دون ازدواجية غير ضرورية في تبادل البيانات والقواعد العامة لمعالجتها.

أيضًا ، من أجل نشر المعلومات في المجتمع الناطق باللغة الروسية حول إمكانيات مخطط JSON وقواعد العمل معها ، سأشارك تجربتي مع أمثلة محددة في إطار هذه المقالة.

صياغة المشكلة


قبل البدء في دراسة مخطط JSON و JSON ، سأصف المهمة التي سننظر فيها في جميع الأمثلة أدناه.

خذ بعين الاعتبار نموذج إدارة الأدوار في المنظمة. نفترض أننا سنحتاج إلى نقل المعلومات المرجعية حول نموذج الدور الحالي إلى الأنظمة التابعة في الرسائل بتنسيق JSON عن طريق استدعاء خدمة REST.

وصف المهمة:

لدى المنظمة موظفين ، وغالبًا ما يتعين عليهم العمل في وقت واحد في عدة أنظمة. علاوة على ذلك ، قد يختلف مستوى الوصول (السلطة) إلى مختلف مكونات النظام (الموارد) لمختلف الموظفين ، اعتمادًا على دورهم في المنظمة ، ويجب التحكم فيه أثناء ترخيص المستخدم في النظام.

على سبيل المثال ، سيكون للمحاسب (الدور) حق الوصول للقراءة والتحرير (العمليات / أوراق الاعتماد) إلى كشوف المرتبات (المورد) لأجور جميع الموظفين ، وسيحصل المحلل (الدور) ، على سبيل المثال ، على حق الوصول للقراءة (العملية / أوراق الاعتماد) فقط وفقا لقسيمة الأجر (المورد).

من الضروري تصميم ووصف نموذج إدارة الأدوار في المنظمة. الأدوار المتاحة ، يجب نقل مجموعة من السلطات والموارد المحتملة في النظام إلى أنظمة أخرى عند الطلب.


الشكل 1. عرض مكونات نموذج

الدور يمكن أن تختلف طرق وصف نموذج القدوة وتنفيذه ، ولكن بغض النظر عن التنفيذ ، في معظم الأحيان في نموذج الدور في هذه الحالة ، يمكننا تمييز المكونات الأساسية التالية:

  1. الدور (مثل المدير والمحاسب وما إلى ذلك).
  2. المورد (على سبيل المثال ، المستند ، الملكية ، إلخ.).
  3. العملية / السلطة (مثل القراءة والطباعة والإنشاء ، وما إلى ذلك).

عند وصف الوصول المستند إلى الدور (كأحد الخيارات الممكنة) ، يلجأون إلى إنشاء مصفوفة وصول منفصلة قائمة على كيانات محددة ، على سبيل المثال:

الجدول 1. مصفوفة الوصول المنفصلة.
المصدر: وثائقالموارد: كائنات
الدور: مديرقراءة وطباعةاقرأ وخلق
الدور: محاسباقرأ وخلقاقرأ

علاوة على ذلك ، في المقالة ، سنتعرف أولاً على المكون النظري لتنسيق النص لتبادل بيانات JSON وقواعد تنظيمها باستخدام مخطط JSON ، وعلى سبيل المثال ، سأصف كيانات الكيانات للأدوار والموارد والعمليات في لغة JSON ومخططات JSON الخاصة بهم داخل حدد المهمة.

تدوين كائن جافا سكريبت (JSON)


JSON (تدوين كائن جافا سكريبت بالإنجليزية) هو تنسيق لتبادل البيانات يستند إلى نص يستند إلى جافا سكريبت.

نظرية


تحدد لغة ترميز JSON مجموعة محدودة من أنواع البيانات. بالنسبة إلى الزوج {"key": value} ، استخدم "type" دائمًا سلسلة النوع ، وبالنسبة إلى "value" ، تنطبق الأنواع: سلسلة ، رقم ، كائن (نوع JSON) ، صفيف ، منطقي (صواب أو خطأ) وقيمة فارغة.


الشكل 2. أنواع بيانات JSON

يوضح الشكل الأنواع الأساسية وأمثلة لاستخدامها. بسيطة بما يكفي ، في رأيي.

بناء جملة JSON هو مجموعة فرعية من بنية JavaScript ، حيث:

  1. تتم كتابة البيانات كأزواج {"key": value}.
  2. يتم فصل البيانات بفواصل.
  3. الأقواس المتعرجة تسجل الأشياء.
  4. تتم كتابة المصفوفات بين قوسين معقوفين.
  5. أسماء "المفاتيح" حساسة لحالة الأحرف.


الشكل 3. صيغة JSON

ممارسة


ضع في اعتبارك مثالاً على دليل الأدوار الذي


سننقله في الخدمة: الشكل 4. وصف دليل الأدوار بتنسيق json

من المثال ، يمكن ملاحظة أنه حتى على الرغم من هذا العدد الصغير من الأنواع الأساسية ، عند دمجها ، يمكننا إنشاء هياكل رسائل أكثر تعقيدًا إذا لزم الأمر. هنا ، على وجه الخصوص ، أصف دليل الأدوار من خلال كائن من المصفوفات التي تحتوي على كائنات أخرى (في الشكل 4 يتم تمييزها بواسطة مستطيلين).

في شكل جدولي باستخدام أدوات تصور json ، يمكن تمثيل الدليل على النحو التالي:


الشكل 5. تصور دليل الأدوار في تنسيق JSON

يمثل الدليل ، نسبياً ، 3 "جداول" لتعيين الأدوار في مجموعة من الإداريين والمحاسبين والعمال. يمكن توسيع تكوين "السمات" ، إذا لزم الأمر.

إن التمثيل المرئي ، في رأيي ، يبسط مفهوم وصف النص. سنضع بنية مماثلة للدليلين الآخرين. سأعطي أدناه مثالاً فقط على طريقة عرض جدول لدليل السلطة (العمليات) والموارد.


الشكل 6. تصور الدليل من الأذونات في تنسيق JSON


الشكل 7. تصور الدليل من الموارد في JSON

الرسائل المصدر في تنسيق JSON نص الدليل من الأدوار ، الموارد و أذونات يمكن تحميل / ينظر اليها من الارتباط .
الآن دعنا ننتقل إلى الأكثر إثارة للاهتمام: دراسة مخطط JSON وإنشاء مخطط لكتبنا المرجعية!

مخطط JSON


نظرية


نظرًا لأن مخطط json مكتوب بتنسيق JSON ، فإنه يدعم جميع أنواع JSON بالإضافة إلى الإضافة: نوع العدد الصحيح ، وهو نوع فرعي من نوع الرقم. المخطط نفسه هو كائن JSON ويهدف إلى وصف البيانات بتنسيق JSON. فيما يلي مخطط لأنواع البيانات المستخدمة لإنشاء المخطط نفسه:


الشكل 8. أنواع بيانات مخطط JSON

كما ترى من الشكل ، يستخدم المخطط جميع أنواع البيانات نفسها ، بالإضافة إلى نفس مبادئ النحو المستخدمة في مستند JSON العادي ، كما هو موضح في الشكل 3.

الآن سنأخذ بعين الاعتبار الأهم - القواعد المستخدمة في مخطط تحديد القيود وهيكلة رسائل JSON.

يتيح لك مخطط JSON ما يلي:

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

بعض "الكلمات الرئيسية" وصفية بحتة ، مثل: "العنوان" و "الوصف" وما إلى ذلك ، والتي تصف ببساطة الغرض من النظام. يستخدم البعض الآخر لتعريف الوثيقة: "مخطط دولار". يتم استخدام هذه الكلمة الرئيسية للإشارة إلى الإصدار المطلوب من المخطط. يجب أن تكون قيمة هذه الكلمة الرئيسية سلسلة تمثل URI ، على سبيل المثال: "$ schema": " json-schema.org/draft-04/schema# ".

من المهم جدًا ملاحظة هنا أنه لا يمكن دعم جميع الإصدارات بواسطة أداة الدائرة الخاصة بك. لكن المسودة الرابعة مدعومة من قبل الجميع تقريبًا. يمكن الاطلاع على أحدث التغييرات (ملاحظات إصدار مخطط JSON 2019-09) للإصدارات المختلفة على json-schema.org/draft/2019-09/release-notes.html .

يتم استخدام الكلمات الرئيسية المتبقية مباشرةً للتحقق من صحة مستند JSON. سننظر فيها الآن.

الجدول 2. تحليل هيكل مخطط JSON. الكلمات الرئيسية وأمثلة استخدامها.
نوعالكلمات الدالة)مثال / وصف
"الكلمات الأساسية" لوصف المخطط"$schema"
"$schema": http://json-schema.org/draft-04/schema#

تستخدم لتعيين نسخة مسودة من المخطط.
"$id"
"$id": "http://archi-blair.com/schemas/RolesDictionaryDef.json#"

يُستخدم للإشارة إلى معرف فريد لمستند أو دائرته الفرعية.
"title"
"description"
"examples"
"comment"

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

عام "الكلمات الأساسية للتحقق" مستقلة عن نوع بيانات العنصر"enum"
{"enum": [ "administrator", "superuser" ]}

يتم إجراء تحقق لمطابقة قيمة واحدة على الأقل.
"const"
{"const": "user" }

يتم التحقق من الامتثال الدقيق للقيمة المحددة.
"type"
{"type": ["number", "string", "null", "boolean"]}
{"type": "array"}

يحدد نوع البيانات التي سيستخدمها المخطط. هذه الكلمة الأساسية اختيارية ، ويمكن أن تكون قيمة الكلمة الأساسية سلسلة تمثل نوع بيانات صالح أو مجموعة من السلاسل التي تمثل أنواع بيانات صالحة.
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"

, .
, .

لقد فحصنا الكلمات الرئيسية لمخطط JSON ، والتي تسمح لنا بوصف البنية المستقبلية لرسائلنا بتنسيق JSON.

هنا يمكنك العثور على مزيد من الأمثلة على استخدام الكلمات الرئيسية.

ممارسة


عند النظر في أمثلة لمخططات JSON المكتملة ، سنشرع بالمثل في أمثلة العمل مع الرسائل نفسها بتنسيق JSON. أولئك. سنستخدم التمثيل المرئي في شكل شجرة وشكل جدولي لمخططات أدلة الأدوار والموارد والسلطات (العمليات) ، ومع نص المخططات التي أقترحها لقراءة القراء المهتمين بمفردهم في بوابة .

فيما يلي رسم بياني لمرجع الدور.


الشكل 9. مثال على مخطط JSON لدليل الأدوار

كما نرى في الشكل ، المخطط هو كائن JSON ويصف رسالتنا لإرسال دليل الأدوار في JSON ، والذي تم عرضه في الشكل 4. في المثال الحالي ، يمكن إظهار كيفية استخدام مخطط JSON يوصف كائن صفيف يتكون من كائنات.

مخططات الدللين الآخرين (السلطة والموارد) متطابقة في الهيكل مع مخطط دليل الأدوار ، لذلك لن أعطيهم هنا ، ولكن سأقدم مخططًا يجمع بين الدلائل الثلاثة.

لسوء الحظ ، لا يتناسب مخطط الدليل بأكمله أثناء التوسيع مع الشاشة ، لذلك سننظر في جزء منه.


الشكل 10. مثال على دليل مخطط JSON الذي يجمع بين دليل الأدوار والأذونات والموارد

في الشكل ، نرى أن بعض الكائنات في مجموعة الأدلة مرتبطة باستخدام الكلمة الأساسية "anyOf".

ربما أيضًا ، سيكون التمثيل المجدول للدليل أكثر وضوحًا.

ضع في اعتبارك ميزة أخرى مهمة في مخططنا:


الشكل 11. مثال على مخطط JSON لمجلد يجمع بين دليل الأدوار والأذونات والموارد في عرض جدول

من الشكل نرى أن دليل الجمع لا يكرر التعليمات البرمجية من أدلة الأدوار والأذونات والموارد التي تم تطويرها مسبقًا ، ولكنه يستخدم الكلمة الأساسية "$ ref "

الدلائل التي تم النظر فيها في الأمثلة موجودة في نفس الدليل ، ولكن ، إذا لزم الأمر ، لا يمكن ملاحظة هذه القاعدة ، ولكن يمكن وضعها في أدلة مختلفة ، تشير إلى المسار الصحيح لها عند الاتصال. هذه الميزة مفيدة للغاية ، لأنها تتيح لك إعادة استخدام المخططات التي تم إنشاؤها مسبقًا ، وتوصيلها فقط بالهيكل المطلوب.

بهذا نختتم مراجعتي لمخطط JSON و JSON. آمل أن تكون المادة المعروضة هنا والأمثلة التي تمت مناقشتها مفيدة في استكشاف قدرات JSON Schema.

بدلا من الاستنتاج


أعتقد أن الوقت قد حان للتقييم. إذن ما الذي يمكن أن يقدمه لنا مخطط JSON في النهاية؟

  1. يمكن أن يجعل الحياة أسهل للمطورين وتحسين التعليمات البرمجية للتحقق من صحة رسائل JSON.
    وبعبارة أخرى ، فإنه يبسط دعم البرامج والتكامل.
  2. يسمح لك بتطوير الخدمات ، والعمل على تنسيقات البيانات وتكوينها مع "احتياطي" لتطوير النظام في المستقبل.
  3. تطبيق التحقق من الوثائق في قواعد البيانات الموجهة نحو المستندات.
  4. يمكن أن يساعد مخطط JSON في توفير اختبار الوقت وتوثيق واجهة برمجة التطبيقات.
  5. تبسيط دعم API التوافق مع الإصدارات السابقة.
  6. يتيح لك إدارة تدفقات البيانات.
  7. التحقق المرن عند إنشاء مخطط JSON في وقت التشغيل بقيم "التعداد" التي تم الحصول عليها في مرحلة تنفيذ البرنامج.
    يمكن استخدامه لآلة الحالة أو سير العمل مع الحالات في "تعداد" (مثال التطبيق منتصدق و VolCh)
  8. يمكن تطبيق مخطط JSON في تنفيذ DTO
    (مثال للاستخدام منamarkevich)

يقرر كل منا "أن يكون أو لا يكون مخطط JSON" في مشاريع تكنولوجيا المعلومات لدينا. أعلاه ، قدمت قائمة بما أعتبره الميزة الرئيسية لاستخدام الدوائر ، ومن أجل ما يستحق التفكير في تطبيقه في المشاريع.

ربما يريد القراء مساعدتي في متابعة هذه القائمة؟
سأكون ممتنًا :) سأقدم

أيضًا قائمة روابط ، في رأيي ، مفيدة للعمل مع JSON و JSON Schema

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

ورابط إلى مستودع git ، حيث يمكنك التعرف على الملفات المصدر المقدمة للمراجعة في هذه المقالة: مستودع مع ملفات المصدر من الأمثلة .

مهندس النظام
© ايرينا بلازينا

All Articles