json schema validator Download تنزيل - json schema validator CODE Download

هذا هو تنفيذ Java لمواصفات JSON Schema Core V4 و V6 و V7 و V2019-09 و V2020-12 للتحقق من صحة مخطط JSON. يدعم هذا التنفيذ تخصيص schemas meta والمفردات والكلمات الرئيسية والتنسيقات.

بالإضافة إلى ذلك ، يتم دعم التحقق من صحة طلب OpenAPI 3 باستخدام SCHEMA المناسبة. للمستخدمين الذين يرغبون في جمع المعلومات من عقدة JSON استنادًا إلى المخطط ، يمكن للمشاة المساعدة. محلل JSON المستخدم هو محلل جاكسون. نظرًا لأنه مكون رئيسي في إطار الخدمات الدقيقة Light-4J الخاصة بنا للتحقق من صحة الطلب/الاستجابة مقابل مواصفات OpenAPI لمخطط Light-Rest-4J و RPC لـ Light-Hybrid-4J في وقت التشغيل ، فإن الأداء هو الجانب الأكثر أهمية في التصميم.

توافق مواصفات مخطط JSON

يمكن العثور على معلومات حول دعم التوافق لكل إصدار ، بما في ذلك المشكلات المعروفة ، في التوافق مع وثيقة إصدارات مخطط JSON.

منذ مسودة 2019-09 ، تقوم الكلمة الرئيسية format فقط بإنشاء التعليقات التوضيحية بشكل افتراضي ولا تولد تأكيدات.

يمكن تجاوز هذا السلوك لإنشاء تأكيدات من خلال تعيين setFormatAssertionsEnabled إلى true في SchemaValidatorsConfig أو ExecutionConfig .

الترقية إلى إصدارات جديدة

يمكن أن تحتوي هذه المكتبة على تغييرات كسر في إصدارات الإصدار minor قد تتطلب تغييرات رمز.

يمكن العثور على معلومات حول التغييرات البارزة أو كسر عند ترقية المكتبة في وثيقة الترقية إلى الإصدارات الجديدة.

ستحتوي صفحة الإصدارات على معلومات حول أحدث الإصدارات.

مقارنة مع التطبيقات الأخرى

يمتلك مشروع مقارنة التحقق من صحة مخطط JSON من Creek مقارنة إعلامية لتطبيقات التحقق من المخططات القائمة على JVM والتي تقارن بين كل من الخصائص الوظيفية والأداء لعدد من تطبيقات JAVA المختلفة.

مقارنة وظيفية
مقارنة الأداء

يحتوي مشروع Bowtie على تقرير يقارن الخصائص الوظيفية للتطبيقات المختلفة ، بما في ذلك التطبيقات غير Java ، ولكنها لا تقوم بأي معايير أداء.

لماذا هذه المكتبة

أداء

يجب أن يكون هذا أسرع تنفيذ التحقق من مخطط Java JSON.

فيما يلي النتائج المعيارية من مشروع التحقق من مخطط JSON الذي يستخدم تسخير Java Microbenchmark.

لاحظ أن النتائج القياسية تعتمد اعتمادًا كبيرًا على أعباء عمل بيانات الإدخال والمخططات المستخدمة للتحقق من الصحة.

في هذه الحالة ، يستخدم عبء العمل هذا مواصفات المسودة 4 ويختبر إلى حد كبير أداء الكلمة الرئيسية لتقييم properties . يمكنك الرجوع إلى نتائج مقارنة الأداء لتطبيقات التحقق من صحة مخطط JSON القائمة على JVM للحصول على نتائج قياسية لمزيد من أعباء العمل النموذجية

إذا كان الأداء بمثابة اعتبار مهم ، فيجب أن تكون أعباء عمل العينة المحددة مؤشرًا ، حيث توجد خصائص أداء مختلفة عند استخدام كلمات رئيسية معينة. على سبيل المثال ، سيؤثر استخدام الكلمة الرئيسية unevaluatedProperties أو الكلمة الرئيسية unevaluatedItems على جمع التعليقات التوضيحية في المدققين ذوي الصلة ، مثل properties أو items ، وسيؤثر جمع التعليقات التوضيحية بشكل سلبي على الأداء.

Networknt 1.4.1

 Benchmark                                            Mode  Cnt      Score    Error   Units
NetworkntBenchmark.testValidate                     thrpt   10   8352.126 ± 61.870   ops/s
NetworkntBenchmark.testValidate:gc.alloc.rate       thrpt   10    721.296 ±  5.342  MB/sec
NetworkntBenchmark.testValidate:gc.alloc.rate.norm  thrpt   10  90560.013 ±  0.001    B/op
NetworkntBenchmark.testValidate:gc.count            thrpt   10     61.000           counts
NetworkntBenchmark.testValidate:gc.time             thrpt   10     68.000               ms

ايفرت 1.14.1

 Benchmark                                            Mode  Cnt       Score    Error   Units
EveritBenchmark.testValidate                        thrpt   10    3775.453 ± 44.023   ops/s
EveritBenchmark.testValidate:gc.alloc.rate          thrpt   10    1667.345 ± 19.437  MB/sec
EveritBenchmark.testValidate:gc.alloc.rate.norm     thrpt   10  463104.030 ±  0.003    B/op
EveritBenchmark.testValidate:gc.count               thrpt   10     140.000           counts
EveritBenchmark.testValidate:gc.time                thrpt   10     158.000               ms

الوظيفة

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

التطبيقات	إجمالي	Draft_03	Draft_04	Draft_06	Draft_07	Draft_2019_09	draft_2020_12
networknt	PASS: R: 4803 (100.0 ٪) O: 2372 (100.0 ٪) FAIL: R: 0 (0.0 ٪) O: 0 (0.0 ٪)		PASS: R: 610 (100.0 ٪) O: 251 (100.0 ٪) FAIL: R: 0 (0.0 ٪) O: 0 (0.0 ٪)	PASS: R: 822 (100.0 ٪) O: 318 (100.0 ٪) FAIL: R: 0 (0.0 ٪) O: 0 (0.0 ٪)	PASS: R: 906 (100.0 ٪) O: 541 (100.0 ٪) FAIL: R: 0 (0.0 ٪) O: 0 (0.0 ٪)	PASS: R: 1220 (100.0 ٪) O: 625 (100.0 ٪) FAIL: R: 0 (0.0 ٪) O: 0 (0.0 ٪)	PASS: R: 1245 (100.0 ٪) O: 637 (100.0 ٪) FAIL: R: 0 (0.0 ٪) O: 0 (0.0 ٪)

لاحظ أن هذا يستخدم JoniRegularExpressionFactory لاختبارات regex pattern format

جاكسون محلل

تستخدم هذه المكتبة جاكسون وهو محلل Java Json يستخدم على نطاق واسع في مشاريع أخرى. إذا كنت تستخدم بالفعل محلل جاكسون في مشروعك ، فمن الطبيعي اختيار هذه المكتبة على الآخرين للتحقق من صحة المخطط.

دعم YAML

تعمل المكتبة مع JSON و YAML على كل من تعريفات المخطط وبيانات الإدخال.

دعم Openapi

تستخدم مواصفات OpenAPI 3.0 مخطط JSON للتحقق من صحة الطلب/الاستجابة ، ولكن هناك بعض الاختلافات. مع ملف التكوين ، يمكنك تمكين المكتبة من العمل مع التحقق من صحة OpenAPI 3.0.

الحد الأدنى من التبعيات

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

التبعيات المطلوبة

فيما يلي التبعيات التي سيتم تضمينها تلقائيًا عند تضمين هذه المكتبة.

< dependency >
    <!-- Used for logging -->
    < groupId >org.slf4j</ groupId >
    < artifactId >slf4j-api</ artifactId >
    < version >${version.slf4j}</ version >
</ dependency >

< dependency >
    <!-- Used to process JSON -->
    < groupId >com.fasterxml.jackson.core</ groupId >
    < artifactId >jackson-databind</ artifactId >
    < version >${version.jackson}</ version >
</ dependency >

< dependency >
    <!-- Used to process YAML -->
    < groupId >com.fasterxml.jackson.dataformat</ groupId >
    < artifactId >jackson-dataformat-yaml</ artifactId >
    < version >${version.jackson}</ version >
</ dependency >

< dependency >
    <!-- Used to validate RFC 3339 date and date-time -->
    < groupId >com.ethlo.time</ groupId >
    < artifactId >itu</ artifactId >
    < version >${version.itu}</ version >
</ dependency >

تبعيات اختيارية

فيما يلي التبعيات الاختيارية التي قد تكون مطلوبة لبعض الخيارات.

لا يتم تضمينها تلقائيًا وإعداد الخيار ذي الصلة دون إضافة المكتبة سيؤدي إلى ClassNotFoundException .

< dependency >
    <!-- Used to validate ECMA 262 regular expressions -->
    <!-- Approximately 50 MB in dependencies -->
    <!-- GraalJSRegularExpressionFactory -->
    < groupId >org.graalvm.js</ groupId >
    < artifactId >js</ artifactId >
    < version >${version.graaljs}</ version >
</ dependency >

< dependency >
    <!-- Used to validate ECMA 262 regular expressions -->
    <!-- Approximately 2 MB in dependencies -->
    <!-- JoniRegularExpressionFactory -->
    < groupId >org.jruby.joni</ groupId >
    < artifactId >joni</ artifactId >
    < version >${version.joni}</ version >
</ dependency >

تبعيات مستبعدة

فيما يلي تبعيات مطلوبة يتم تضمينها تلقائيًا ، ولكن يمكن استبعادها بشكل صريح إذا لم تكن مطلوبة.

يمكن استبعاد تبعية YAML إذا لم يكن هذا مطلوبًا. محاولة معالجة المخططات أو المدخلات التي هي YAML سوف تؤدي إلى ClassNotFoundException .

< dependency >
    < groupId >com.networknt</ groupId >
    < artifactId >json-schema-validator</ artifactId >
    < exclusions >
        < exclusion >
            < groupId >com.fasterxml.jackson.dataformat</ groupId >
            < artifactId >jackson-dataformat-yaml</ artifactId >
        </ exclusion >
    </ exclusions >
</ dependency >

يمكن استبعاد التبعية Ethlo Time إذا لم يكن التحقق الدقيق لتنسيق date-time مطلوبًا. سيستخدم تنسيق date-time java.time.OffsetDateTime لتحديد ما إذا كان date-time صالحًا.

< dependency >
    < groupId >com.networknt</ groupId >
    < artifactId >json-schema-validator</ artifactId >
    < exclusions >
        < exclusion >
            < groupId >com.ethlo.time</ groupId >
            < artifactId >itu</ artifactId >
        </ exclusion >
    </ exclusions >
</ dependency >

مجتمع

هذه المكتبة نشطة للغاية مع الكثير من المساهمين. يتم التعامل مع الميزات الجديدة وإصلاحات الأخطاء بسرعة من قبل أعضاء الفريق. نظرًا لأنه تبعية أساسية لإطار Light-4J في نفس منظمة GitHub ، فسيتم تطوره وصيانته مع الإطار.

المتطلب السابق

تدعم المكتبة Java 8 وما فوق. إذا كنت ترغب في الإنشاء من الرمز المصدر ، فأنت بحاجة إلى تثبيت JDK 8 محليًا. لدعم نسخة متعددة من JDK ، يمكنك استخدام Sdkman

الاستخدام

إضافة التبعية

هذه الحزمة متوفرة على Maven Central.

مافن:

< dependency >
    < groupId >com.networknt</ groupId >
    < artifactId >json-schema-validator</ artifactId >
    < version >1.5.3</ version >
</ dependency >

Gradle:

 dependencies {
    implementation ( group : 'com.networknt' , name : 'json-schema-validator' , version : '1.5.3' );
}

التحقق من صحة المدخلات مقابل المخطط

يوضح المثال التالي كيف يتم التحقق من صحة المدخلات مقابل مخطط. ويتضمن الخطوات التالية.

إنشاء مصنع مخطط مع لهجة المخطط الافتراضية وكيف يمكن استرداد المخططات.
- تكوين تعيين $id إلى URI استرجاع باستخدام schemaMappers .
- تكوين كيفية تحميل المخططات باستخدام URI الاسترجاع باستخدام schemaLoaders . على سبيل المثال ، يمكن Map<String, String> schemas تحتوي على رسم خرائط للاسترجاع إلى بيانات المخطط String عن طريق تكوينها باستخدام builder.schemaLoaders(schemaLoaders -> schemaLoaders.schemas(schemas)) . هذا يقبل أيضًا Function<String, String> schemaRetrievalFunction .
إنشاء تكوين للتحكم في سلوك المدقق.
تحميل مخطط من موقع المخطط جنبا إلى جنب مع تكوين المدقق.
باستخدام المخطط للتحقق من صحة البيانات إلى جانب تعيين أي تكوين محدد للتنفيذ مثل على سبيل المثال ، تم تمكين التأكيدات على التنسيق.

 // This creates a schema factory that will use Draft 2020-12 as the default if $schema is not specified
// in the schema data. If $schema is specified in the schema data then that schema dialect will be used
// instead and this version is ignored.
JsonSchemaFactory jsonSchemaFactory = JsonSchemaFactory . getInstance ( VersionFlag . V202012 , builder -> 
    // This creates a mapping from $id which starts with https://www.example.org/ to the retrieval URI classpath:schema/
    builder . schemaMappers ( schemaMappers -> schemaMappers . mapPrefix ( "https://www.example.org/" , "classpath:schema/" ))
);

SchemaValidatorsConfig . Builder builder = SchemaValidatorsConfig . builder ();
// By default the JDK regular expression implementation which is not ECMA 262 compliant is used
// Note that setting this requires including optional dependencies
// builder.regularExpressionFactory(GraalJSRegularExpressionFactory.getInstance());
// builder.regularExpressionFactory(JoniRegularExpressionFactory.getInstance());
SchemaValidatorsConfig config = builder . build ();

// Due to the mapping the schema will be retrieved from the classpath at classpath:schema/example-main.json.
// If the schema data does not specify an $id the absolute IRI of the schema location will be used as the $id.
JsonSchema schema = jsonSchemaFactory . getSchema ( SchemaLocation . of ( "https://www.example.org/example-main.json" ), config );
String input = "{ r n "
    + "  " main " : { r n "
    + "    " common " : { r n "
    + "      " field " : " invalidfield " r n "
    + "    } r n "
    + "  } r n "
    + "}" ;

Set < ValidationMessage > assertions = schema . validate ( input , InputFormat . JSON , executionContext -> {
    // By default since Draft 2019-09 the format keyword only generates annotations and not assertions
    executionContext . getExecutionConfig (). setFormatAssertionsEnabled ( true );
});

التحقق من صحة المخطط ضد SCHEMA

يوضح المثال التالي كيف يتم التحقق من صحة المخطط مقابل SCHEMA.

هذا في الواقع هو نفسه التحقق من صحة المدخلات مقابل مخطط إلا في هذه الحالة ، فإن المدخلات هي المخطط والمخطط المستخدم هو SCHEMA.

لاحظ أن Meta-Schemas للمسودة 4 ، المسودة 6 ، المسودة 7 ، المسودة 2019-09 ومسودة 2020-12 يتم تجميعها مع المكتبة وسيتم استخدام موارد ClassPath هذه افتراضيًا.

 JsonSchemaFactory jsonSchemaFactory = JsonSchemaFactory . getInstance ( VersionFlag . V202012 );

SchemaValidatorsConfig . Builder builder = SchemaValidatorsConfig . builder ();
// By default the JDK regular expression implementation which is not ECMA 262 compliant is used
// Note that setting this requires including optional dependencies
// builder.regularExpressionFactory(GraalJSRegularExpressionFactory.getInstance());
// builder.regularExpressionFactory(JoniRegularExpressionFactory.getInstance());
SchemaValidatorsConfig config = builder . build ();

// Due to the mapping the meta-schema will be retrieved from the classpath at classpath:draft/2020-12/schema.
JsonSchema schema = jsonSchemaFactory . getSchema ( SchemaLocation . of ( SchemaId . V202012 ), config );
String input = "{ r n "
    + "  " type " : " object " , r n "
    + "  " properties " : { r n "
    + "    " key " : { r n "
    + "      " title " : " My key " , r n "
    + "      " type " : " invalidtype " r n "
    + "    } r n "
    + "  } r n "
    + "}" ;
Set < ValidationMessage > assertions = schema . validate ( input , InputFormat . JSON , executionContext -> {
    // By default since Draft 2019-09 the format keyword only generates annotations and not assertions
    executionContext . getExecutionConfig (). setFormatAssertionsEnabled ( true );
});

النتائج وتنسيقات الإخراج

نتائج

يتم إنشاء الأنواع التالية من النتائج بواسطة المكتبة.

يكتب وصف

التأكيدات أخطاء التحقق من الصحة التي تم إنشاؤها بواسطة كلمة رئيسية على مثيل بيانات إدخال معين. هذا موصوف بشكل عام في ValidationMessage أو في OutputUnit . لاحظ أنه منذ مسودة 2019-09 ، لم تعد الكلمة الرئيسية format تنشئ تأكيدات افتراضيًا وبدلاً من ذلك لا تنشئ سوى التعليقات التوضيحية ما لم يتم تكوينها بخلاف ذلك باستخدام خيار التكوين أو باستخدام Schema التعويضي الذي يستخدم المفردات المناسبة.

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

يكتب	وصف
التأكيدات	أخطاء التحقق من الصحة التي تم إنشاؤها بواسطة كلمة رئيسية على مثيل بيانات إدخال معين. هذا موصوف بشكل عام في `ValidationMessage` أو في `OutputUnit` . لاحظ أنه منذ مسودة 2019-09 ، لم تعد الكلمة الرئيسية `format` تنشئ تأكيدات افتراضيًا وبدلاً من ذلك لا تنشئ سوى التعليقات التوضيحية ما لم يتم تكوينها بخلاف ذلك باستخدام خيار التكوين أو باستخدام Schema التعويضي الذي يستخدم المفردات المناسبة.
التعليقات التوضيحية	معلومات إضافية تم إنشاؤها بواسطة كلمة رئيسية لمثيل بيانات إدخال معين. هذا موصوف بشكل عام في `OutputUnit` . يتم إيقاف تشغيل جمع التعليقات التوضيحية وإعداد التقارير افتراضيًا. يتم دائمًا جمع التعليقات التوضيحية المطلوبة بواسطة الكلمات الرئيسية مثل `unevaluatedProperties` أو `unevaluatedItems` أجهزة التقييم ولا يمكن تعطيلها ولكن لن يتم الإبلاغ عنها ما لم يتم تكوينها للقيام بذلك.

يتم استخدام المعلومات التالية لوصف كلا النوعين من النتائج.

يكتب	وصف
مسار التقييم	هذه هي مجموعة المفاتيح من الجذر الذي يمر من خلاله التقييم للوصول إلى المخطط لتقييم المثيل. وهذا يشمل `$ref` و `$dynamicRef` . على سبيل المثال. `/properties/bar/$ref/properties/bar-prop`
موقع المخطط	هذا هو IRI الكنسي للمخطط بالإضافة إلى جزء مؤشر JSON إلى المخطط الذي تم استخدامه لتقييم المثيل. على سبيل المثال. `https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop`
موقع مثيل	هذا هو جزء مؤشر JSON إلى بيانات المثيل التي تم تقييمها. على سبيل المثال. `/bar/bar-prop`

تحتوي التأكيدات على المعلومات الإضافية التالية

يكتب	وصف
رسالة	رسالة خطأ التحقق من الصحة.
شفرة	رمز الخطأ.
مفتاح الرسالة	مفتاح الرسالة المستخدم لإنشاء رسالة للتوطين.
الحجج	الحجج المستخدمة لإنشاء الرسالة.
يكتب	الكلمة الرئيسية التي ولدت الرسالة.
ملكية	اسم الخاصية التي تسبب في خطأ التحقق من الصحة على سبيل المثال للكلمة الرئيسية `required` . لاحظ أن هذا ليس جزءًا من موقع المثيل حيث يشير إلى عقدة المثيل.
عقدة المخطط	أشار `JsonNode` إلى موقع المخطط. هذه هي بيانات المخطط التي تسببت في فشل بيانات الإدخال. من الممكن الحصول على معلومات الموقع من خلال تكوين `JsonSchemaFactory` مع `JsonNodeReader` الذي يستخدم `LocationJsonNodeFactoryFactory` واستخدام `JsonNodes.tokenLocationOf(schemaNode)` .
عقدة مثيل	أشار `JsonNode` إلى موقع المثيل. هذه هي بيانات الإدخال التي فشلت التحقق من الصحة. من الممكن الحصول على معلومات الموقع من خلال تكوين `JsonSchemaFactory` مع `JsonNodeReader` الذي يستخدم `LocationJsonNodeFactoryFactory` واستخدام `JsonNodes.tokenLocationOf(instanceNode)` .
خطأ	الخطأ.
تفاصيل	التفاصيل الإضافية التي يمكن تعيينها عن طريق تطبيقات مخصصة للمصلحة الكلمات الرئيسية. هذا لا يستخدم من قبل المكتبة.

تحتوي التعليقات التوضيحية على المعلومات الإضافية التالية

يكتب	وصف
قيمة	تم توليد قيمة التعليقات التوضيحية

معلومات الخط والعمود

يمكن تكوين المكتبة لتخزين معلومات الخط والعمود في مثيلات JsonNode للمثال وعقد المخطط. سيؤثر هذا سلبًا على الأداء ولا يتم تكوينه افتراضيًا.

يتم ذلك عن طريق تكوين JsonNodeReader الذي يستخدم LocationJsonNodeFactoryFactory على JsonSchemaFactory . يمكن بعد ذلك استرداد معلومات JsonLocation باستخدام JsonNodes.tokenLocationOf(jsonNode) .

 String schemaData = "{ r n "
                + "  " $id " : " https://schema/myschema " , r n "
                + "  " properties " : { r n "
                + "    " startDate " : { r n "
                + "      " format " : " date " , r n "
                + "      " minLength " : 6 r n "
                + "    } r n "
                + "  } r n "
                + "}" ;
String inputData = "{ r n "
                + "  " startDate " : " 1 " r n "
                + "}" ;
JsonSchemaFactory factory = JsonSchemaFactory . getInstance ( VersionFlag . V202012 ,
        builder -> builder . jsonNodeReader ( JsonNodeReader . builder (). locationAware (). build ()));
SchemaValidatorsConfig config = SchemaValidatorsConfig . builder (). build ();
JsonSchema schema = factory . getSchema ( schemaData , InputFormat . JSON , config );
Set < ValidationMessage > messages = schema . validate ( inputData , InputFormat . JSON , executionContext -> {
    executionContext . getExecutionConfig (). setFormatAssertionsEnabled ( true );
});
List < ValidationMessage > list = messages . stream (). collect ( Collectors . toList ());
ValidationMessage format = list . get ( 0 );
JsonLocation formatInstanceNodeTokenLocation = JsonNodes . tokenLocationOf ( format . getInstanceNode ());
JsonLocation formatSchemaNodeTokenLocation = JsonNodes . tokenLocationOf ( format . getSchemaNode ());
ValidationMessage minLength = list . get ( 1 );
JsonLocation minLengthInstanceNodeTokenLocation = JsonNodes . tokenLocationOf ( minLength . getInstanceNode ());
JsonLocation minLengthSchemaNodeTokenLocation = JsonNodes . tokenLocationOf ( minLength . getSchemaNode ());

assertEquals ( "format" , format . getType ());
assertEquals ( "date" , format . getSchemaNode (). asText ());
assertEquals ( 5 , formatSchemaNodeTokenLocation . getLineNr ());
assertEquals ( 17 , formatSchemaNodeTokenLocation . getColumnNr ());
assertEquals ( "1" , format . getInstanceNode (). asText ());
assertEquals ( 2 , formatInstanceNodeTokenLocation . getLineNr ());
assertEquals ( 16 , formatInstanceNodeTokenLocation . getColumnNr ());
assertEquals ( "minLength" , minLength . getType ());
assertEquals ( "6" , minLength . getSchemaNode (). asText ());
assertEquals ( 6 , minLengthSchemaNodeTokenLocation . getLineNr ());
assertEquals ( 20 , minLengthSchemaNodeTokenLocation . getColumnNr ());
assertEquals ( "1" , minLength . getInstanceNode (). asText ());
assertEquals ( 2 , minLengthInstanceNodeTokenLocation . getLineNr ());
assertEquals ( 16 , minLengthInstanceNodeTokenLocation . getColumnNr ());
assertEquals ( 16 , minLengthInstanceNodeTokenLocation . getColumnNr ());

تنسيقات الإخراج

تنفذ هذه المكتبة تنسيقات العلم والقائمة والتسلسل الهرمي المحدد في مواصفات الإخراج القابل للقراءة الآلي للتحقق من صحة مخطط JSON والشرح.

إن تنسيقات القائمة والتسلسل الهرمي مفيد بشكل خاص لفهم كيفية وصول النظام إلى نتيجة معينة.

تنسيق الإخراج	وصف
تقصير	يولد قائمة التأكيدات.
منطقية	إرجاع `true` إذا كان التحقق من الصحة ناجحًا. لاحظ أنه يتم تشغيل خيار FAIL Fast بشكل افتراضي لتنسيق الإخراج هذا.
علَم	إرجاع كائن `OutputFlag` `true` `valid` كان التحقق من الصحة ناجحًا. لاحظ أنه يتم تشغيل خيار FAIL Fast بشكل افتراضي لتنسيق الإخراج هذا.
قائمة	إرجاع كائن `OutputUnit` مع `details` مع قائمة كائنات `OutputUnit` مع التأكيدات والشروح. لاحظ أن التعليقات التوضيحية لا يتم جمعها افتراضيًا ويجب تمكينها لأنه سيؤثر على الأداء.
التسلسل الهرمي	إرجاع كائن `OutputUnit` مع تسلسل هرمي للكائنات `OutputUnit` لمسار التقييم مع التأكيدات والشروح. لاحظ أن التعليقات التوضيحية لا يتم جمعها افتراضيًا ويجب تمكينها لأنه سيؤثر على الأداء.

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

 JsonSchemaFactory factory = JsonSchemaFactory . getInstance ( VersionFlag . V202012 );
SchemaValidatorsConfig config = SchemaValidatorsConfig (). builder (). formatAssertionsEnabled ( true ). build ();
JsonSchema schema = factory . getSchema ( SchemaLocation . of ( "https://json-schema.org/schemas/example" ), config );
        
OutputUnit outputUnit = schema . validate ( inputData , InputFormat . JSON , OutputFormat . HIERARCHICAL , executionContext -> {
    executionContext . getExecutionConfig (). setAnnotationCollectionEnabled ( true );
    executionContext . getExecutionConfig (). setAnnotationCollectionFilter ( keyword -> true );
});

فيما يلي عينة إخراج من التنسيق الهرمي.

{
  "valid" : false ,
  "evaluationPath" : " " ,
  "schemaLocation" : " https://json-schema.org/schemas/example# " ,
  "instanceLocation" : " " ,
  "droppedAnnotations" : {
    "properties" : [ " foo " , " bar " ],
    "title" : " root "
  },
  "details" : [ {
    "valid" : false ,
    "evaluationPath" : " /properties/foo/allOf/0 " ,
    "schemaLocation" : " https://json-schema.org/schemas/example#/properties/foo/allOf/0 " ,
    "instanceLocation" : " /foo " ,
    "errors" : {
      "required" : " required property 'unspecified-prop' not found "
    }
  }, {
    "valid" : false ,
    "evaluationPath" : " /properties/foo/allOf/1 " ,
    "schemaLocation" : " https://json-schema.org/schemas/example#/properties/foo/allOf/1 " ,
    "instanceLocation" : " /foo " ,
    "droppedAnnotations" : {
      "properties" : [ " foo-prop " ],
      "title" : " foo-title " ,
      "additionalProperties" : [ " foo-prop " , " other-prop " ]
    },
    "details" : [ {
      "valid" : false ,
      "evaluationPath" : " /properties/foo/allOf/1/properties/foo-prop " ,
      "schemaLocation" : " https://json-schema.org/schemas/example#/properties/foo/allOf/1/properties/foo-prop " ,
      "instanceLocation" : " /foo/foo-prop " ,
      "errors" : {
        "const" : " must be a constant value 1 "
      },
      "droppedAnnotations" : {
        "title" : " foo-prop-title "
      }
    } ]
  }, {
    "valid" : false ,
    "evaluationPath" : " /properties/bar/$ref " ,
    "schemaLocation" : " https://json-schema.org/schemas/example#/$defs/bar " ,
    "instanceLocation" : " /bar " ,
    "droppedAnnotations" : {
      "properties" : [ " bar-prop " ],
      "title" : " bar-title "
    },
    "details" : [ {
      "valid" : false ,
      "evaluationPath" : " /properties/bar/$ref/properties/bar-prop " ,
      "schemaLocation" : " https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop " ,
      "instanceLocation" : " /bar/bar-prop " ,
      "errors" : {
        "minimum" : " must have a minimum value of 10 "
      },
      "droppedAnnotations" : {
        "title" : " bar-prop-title "
      }
    } ]
  } ]
}

إعدادات

تكوين التنفيذ

اسم	وصف	القيمة الافتراضية
`annotationCollectionEnabled`	الضوابط ما إذا كان يتم جمع التعليقات التوضيحية أثناء المعالجة. لاحظ أن جمع التعليقات التوضيحية سيؤثر سلبًا على الأداء.	`false`
`annotationCollectionFilter`	المسند المستخدم للتحكم في الكلمات الرئيسية التي يجب جمعها والإبلاغ عن التعليقات التوضيحية ل. هذا يتطلب أن يكون `true` `annotationCollectionEnabled` .	`keyword -> false`
`locale`	اللغة التي يجب استخدامها لإنشاء الرسائل في `ValidationMessage` . لاحظ أن هذه القيمة يتم نسخها من `SchemaValidatorsConfig` لكل تنفيذ.	`Locale.getDefault()`
`failFast`	ما إذا كان لإرجاع الفشل على الفور عند إنشاء تأكيد. لاحظ أن هذه القيمة يتم نسخها من `SchemaValidatorsConfig` لكل تنفيذ ولكن يتم ضبطها تلقائيًا على `true` لتنسيقات الإخراج المنطقية والعلم.	`false`
`formatAssertionsEnabled`	الافتراضي هو إنشاء تأكيدات تنسيق من المسودة 4 إلى المسودة 7 ولتوليد تعليقات من المسودة 2019-09 فقط. سيؤدي الإعداد إلى `true` أو `false` إلى تجاوز السلوك الافتراضي.	`null`
`debugEnabled`	يتحكم في ما إذا كان يتم تمكين تسجيل الأخطاء لتسجيل معلومات العقدة عند المعالجة. لاحظ أن هذا سيولد الكثير من السجلات التي ستؤثر على الأداء.	`false`

مصادقي المخطط تكوين

اسم	وصف	القيمة الافتراضية
`applyDefaultsStrategy`	استراتيجية تطبيق الإعدادات الافتراضية عند المشي عند مواجهة العقد المفقودة أو الفارغة.	`ApplyDefaultsStrategy.EMPTY_APPLY_DEFAULTS_STRATEGY`
`cacheRefs`	ما إذا كان سيتم تخزين المخططات المحملة من Refs وإعادة استخدامها للتشغيل اللاحق. سيؤثر تعيين هذا على `false` على الأداء ولكن قد يكون ضروريًا لمنع استخدام ذاكرة ذاكرة التخزين المؤقت العالية إذا تم استخدام تطبيقات متعددة متداخلة مثل `anyOf` و `oneOf` و `allOf` .	`true`
`discriminatorKeywordEnabled`	ما إذا كانت الكلمة الرئيسية `discriminator` تتم معالجتها وفقًا لـ Openapi 3.	`false`
`errorMessageKeyword`	الكلمة الرئيسية التي يجب استخدامها لرسائل الخطأ المخصصة في المخطط. إذا لم يتم تعيين هذه الميزات. يتم تعيين هذا عادة على `errorMessage` أو `message` .	`null`
`executionContextCustomizer`	يمكن استخدام هذا لتخصيص `ExecutionContext` الذي تم إنشاؤه بواسطة `JsonSchema` لكل تشغيل التحقق من الصحة.	`null`
`failFast`	ما إذا كان لإرجاع الفشل على الفور عند إنشاء تأكيد.	`false`
`formatAssertionsEnabled`	الافتراضي هو إنشاء تأكيدات تنسيق من المسودة 4 إلى المسودة 7 ولتوليد تعليقات من المسودة 2019-09 فقط. سيؤدي الإعداد إلى `true` أو `false` إلى تجاوز السلوك الافتراضي.	`null`
`javaSemantics`	ما إذا كانت جافا دلالات تستخدم للكلمة الرئيسية `type` .	`false`
`locale`	اللغة التي يجب استخدامها لإنشاء الرسائل في `ValidationMessage` .	`Locale.getDefault()`
`losslessNarrowing`	ما إذا كان تضييق الخسارة يستخدم للكلمة الرئيسية `type` .	`false`
`messageSource`	يستخدم هذا لاسترداد الرسائل المحددة المحددة.	`DefaultMessageSource.getInstance()`
`nullableKeywordEnabled`	ما إذا كان يتم التعامل مع الكلمة الرئيسية `nullable` وفقًا لـ OpenAPI 3.0. هذا يؤثر على `enum` `type` الكلمات الرئيسية.	`false`
`pathType`	نوع المسار الذي يجب استخدامه للإبلاغ عن موقع المثيل ومسار التقييم. ضبط على `PathType.JSON_PATH` لاستخدام مسار JSON.	`PathType.JSON_POINTER`
`preloadJsonSchema`	ما إذا كان سيتم تحميل المخطط قبل معالجة أي مدخلات. سيستخدم هذا الذاكرة ولكن تنفيذ التحقق من الصحة سيكون أسرع.	`true`
`preloadJsonSchemaRefMaxNestingDepth`	أقصى عمق مسار التقييم للتحميل المسبق عند التحميل المسبق للمرور.	`40`
`readOnly`	ما إذا كانت المخطط يقرأ فقط. هذا يؤثر على الكلمة الرئيسية `readOnly` .	`null`
`regularExpressionFactory`	المصنع لاستخدامه لإنشاء تعبيرات منتظمة على سبيل المثال `JoniRegularExpressionFactory` أو `GraalJSRegularExpressionFactory` . يتطلب ذلك إضافة التبعية يدويًا إلى المشروع أو سيتم طرح `ClassNotFoundException` .	`JDKRegularExpressionFactory.getInstance()`
`schemaIdValidator`	يستخدم هذا لتخصيص كيفية التحقق من قيم `$id` . لاحظ أن التنفيذ الافتراضي يتيح أجزاء غير فارغة حيث لا يتم تحديد IRI الأساسي ويسمح أيضًا بقيم `$id` غير المتسابقين في مخطط الجذر.	`JsonSchemaIdValidator.DEFAULT`
`strict`	يتم تعيين هذا ما إذا كانت الكلمات الرئيسية صارمة في التحقق من صحتها. ما يفعله هذا يعتمد على المدققين الفرديين.
`typeLoose`	ما إذا كانت الأنواع يتم تفسيرها بطريقة فضفاضة. إذا تم ضبطها على TRUE ، يمكن تفسير قيمة واحدة على أنها مجموعة الحجم 1. يمكن أيضًا تفسير السلاسل على أنها عدد أو عدد صحيح أو منطقي.	`false`
`writeOnly`	ما إذا كان المخطط يكتب فقط. هذا يؤثر على الكلمة الرئيسية `writeOnly` .	`null`

اعتبارات الأداء

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

عند إنشاء المخطط ، ستقوم المكتبة بشكل افتراضي بتحميل جميع المدققين اللازمين وحل المراجع. يمكن تعطيل ذلك مع خيار preloadJsonSchema في SchemaValidatorsConfig . في هذه المرحلة ، لن يتم طرح أي استثناءات إذا تعذر حل المرجع. إذا كانت هناك مراجع دورية ، فسيتم تحميل الدورة الأولى فقط. إذا كنت ترغب في التأكد من أنه يمكن حل جميع المراجع عن بُعد ، فيجب استدعاء طريقة initializeValidators على JsonSchema التي ستلقي استثناءً إذا كانت هناك مراجع لا يمكن حلها.

تم تصميم حالات JsonSchemaFactory و JsonSchema التي تم إنشاؤها منها لتكون آمنة مؤلمة بشرط عدم تعديل تكوينها ويجب تخزينه مؤقتًا وإعادة استخدامه. عدم إعادة استخدام JsonSchema يعني أن بيانات المخطط يجب أن تتكرر مع مثيلات المدقق التي تم إنشاؤها وحل المراجع. عند حل المراجع ، سيتم تخزين المؤكدين. بالنسبة للمخططات التي لها مراجع متداخلة بعمق ، قد تكون الذاكرة اللازمة للمقدين عالية جدًا ، وفي هذه الحالة قد تحتاج التخزين المؤقت إلى تعطيله باستخدام خيار cacheRefs في SchemaValidatorsConfig . إن تعطيل هذا يعني أنه يجب إعادة إنشاء المصدين من المراجع لكل عملية التحقق من الصحة والتي ستؤثر على الأداء.

سيؤثر جمع التعليقات التوضيحية سلبًا على أداء التحقق من الصحة.

تحتوي المواصفات السابقة على كلمات رئيسية أقل يمكن أن تؤثر على الأداء. على سبيل المثال ، سيؤدي استخدام الكلمة الرئيسية unevaluatedProperties أو الكلمة الرئيسية unevaluatedItems إلى جمع التعليقات التوضيحية في المدققين ذوي الصلة ، مثل properties أو صحة items .

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

اعتبارات الأمن

تفترض المكتبة أن المخططات التي يتم تحميلها موثوق بها. يفترض هذا النموذج الأمني حالة الاستخدام حيث يتم تجميع المخططات مع التطبيق على ClassPath.

مشكلة	وصف	التخفيف
تحميل المخطط	ستعمل المكتبة افتراضيًا على تحميل المخططات من ClassPath وعبر الإنترنت إذا لزم الأمر.	يمكن تكوين `DisallowSchemaLoader` لعدم السماح باسترجاع المخطط. بدلاً من ذلك ، يمكن تكوين `AllowSchemaLoader` لتقييد قزحية الاسترجاع المسموح بها.
التخزين المؤقت مخطط	المكتبة بشكل افتراضي التحميل المسبق وذاكرة التخزين المؤقت عند تحميل المخططات. في حين أن هناك عمقًا أقصى تعشيشًا عندما لا يزال من الممكن إنشاء مخططات تحتوي على مخطط يحتوي على مروحة يستهلك الكثير من الذاكرة من الخادم.	اضبط خيار `cacheRefs` في `SchemaValidatorsConfig` على خطأ.
تعبيرات منتظمة	لا تتحقق المكتبة إذا كان التعبير العادي المعطى عرضة لرفض الخدمة (Redos).	يمكن تكوين `AllowRegularExpressionFactory` لإجراء التحقق من الصحة على التعبيرات العادية المسموح بها.
أخطاء التحقق من الصحة	تحاول المكتبة افتراضيًا لإعادة جميع أخطاء التحقق من الصحة. قد يؤدي استخدام التطبيقات مثل `allOf` مع عدد كبير من المخططات إلى عدد كبير من أخطاء التحقق من الصحة التي تتناول الذاكرة.	قم بتعيين خيار `failFast` في `SchemaValidatorsConfig` للعودة على الفور عند مواجهة الخطأ الأول. يمكن أيضًا استخدام `OutputFormat.BOOLEAN` أو `OutputFormat.FLAG` .

بداية سريعة

تخصيص استرجاع المخطط

تخصيص meta schemas والمفردات والكلمات الرئيسية والتنسيقات

مواصفات Openapi

المدققون

إعدادات

إصدار المواصفات

التحقق من صحة YAML

السياق جامع

مشاة مخطط JSON و Walklisteners

تعبيرات منتظمة

رسائل خطأ مخصصة

لغة متعددة

التحقق من صحة Metaschema

التحقق من صحة RFC 3339 فترات

المشاريع

استخدم هذا المكتبة REST-4J و Light-GraphQL-4J و Light-Hybrid-4J هذه المكتبة للتحقق من صحة الطلب والاستجابة بناءً على المواصفات. إذا كنت تستخدم أطر عمل أخرى مثل Spring Boot ، فيمكنك استخدام OpenApivivalator ، وهو مدقق OpenAPI 3.0 عام استنادًا إلى مواصفات OpenAPI 3.0.

إذا كان لديك مشروع يستخدم هذه المكتبة ، فيرجى إرسال العلاقات العامة لإضافة مشروعك أدناه.