json schema validator Download - json schema validator Sumber Code Unduh

Ini adalah implementasi Java dari JSON Schema Core Draft V4, V6, V7, V2019-09 dan V2020-12 Spesifikasi untuk validasi skema JSON. Implementasi ini mendukung penyesuaian meta-skema, kosa kata, kata kunci dan format.

Selain itu, validasi permintaan/respons OpenAPI 3 didukung dengan penggunaan meta-skema yang sesuai. Untuk pengguna yang ingin mengumpulkan informasi dari node JSON berdasarkan skema, pejalan kaki dapat membantu. Parser JSON yang digunakan adalah Jackson Parser. Karena ini adalah komponen kunci dalam kerangka kerja Microservices cahaya-4J kami untuk memvalidasi permintaan/respons terhadap spesifikasi OpenAPI untuk skema REST-4J dan RPC untuk Light-Hybrid-4J saat runtime, kinerja adalah aspek terpenting dalam desain.

Kompatibilitas Spesifikasi Skema JSON

Informasi tentang dukungan kompatibilitas untuk setiap versi, termasuk masalah yang diketahui, dapat ditemukan dalam kompatibilitas dengan dokumen versi skema JSON.

Sejak draf 2019-09 kata kunci format hanya menghasilkan anotasi secara default dan tidak menghasilkan pernyataan.

Perilaku ini dapat diganti untuk menghasilkan pernyataan dengan mengatur setFormatAssertionsEnabled menjadi true di SchemaValidatorsConfig atau ExecutionConfig .

Meningkatkan ke versi baru

Perpustakaan ini dapat berisi perubahan besar dalam rilis versi minor yang mungkin memerlukan perubahan kode.

Informasi tentang perubahan yang terkenal atau melanggar saat meningkatkan perpustakaan dapat ditemukan dalam peningkatan ke dokumen versi baru.

Halaman rilis akan berisi informasi tentang versi terbaru.

Membandingkan dengan implementasi lain

Proyek Perbandingan Validasi Skema JSON dari Creek memiliki perbandingan informatif dari implementasi validasi skema berbasis JVM yang membandingkan karakteristik fungsional dan kinerja dari sejumlah implementasi JAVA yang berbeda.

Perbandingan fungsional
Perbandingan Kinerja

Proyek Bowtie memiliki laporan yang membandingkan karakteristik fungsional dari berbagai implementasi, termasuk implementasi non-java, tetapi tidak melakukan pembandingan kinerja.

Mengapa perpustakaan ini

Pertunjukan

Ini harus menjadi implementasi validator skema Java JSON tercepat.

Berikut ini adalah hasil benchmark dari proyek perftest validator skema JSON yang menggunakan java microbenchmark harness.

Perhatikan bahwa hasil benchmark sangat tergantung pada beban kerja data input dan skema yang digunakan untuk validasi.

Dalam hal ini beban kerja ini menggunakan spesifikasi draft 4 dan sebagian besar menguji kinerja evaluasi kata kunci properties . Anda dapat merujuk pada hasil perbandingan kinerja implementasi validasi skema JVM berbasis untuk hasil benchmark untuk beban kerja yang lebih khas

Jika kinerja merupakan pertimbangan penting, beban kerja sampel spesifik harus dibandingkan, karena ada karakteristik kinerja yang berbeda ketika kata kunci tertentu digunakan. Misalnya penggunaan kata kunci unevaluatedProperties atau kata kunci unevaluatedItems akan memicu koleksi anotasi dalam validator terkait, seperti validator properties atau items , dan pengumpulan anotasi akan mempengaruhi kinerja.

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

Everit 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

Fungsionalitas

Implementasi ini diuji terhadap rangkaian uji skema JSON. Karena tes terus ditambahkan ke suite, hasil tes ini mungkin tidak terkini.

Implementasi	Keseluruhan	Draft_03	Draft_04	Draft_06	Draft_07	Draft_2019_09	Draft_2020_12
Networknt	Pass: R: 4803 (100,0%) O: 2372 (100,0%) Gagal: R: 0 (0,0%) O: 0 (0,0%)		Pass: R: 610 (100.0%) O: 251 (100.0%) Gagal: R: 0 (0,0%) O: 0 (0,0%)	Pass: R: 822 (100,0%) O: 318 (100,0%) Gagal: R: 0 (0,0%) O: 0 (0,0%)	Pass: R: 906 (100,0%) O: 541 (100,0%) Gagal: R: 0 (0,0%) O: 0 (0,0%)	Pass: R: 1220 (100.0%) O: 625 (100.0%) Gagal: R: 0 (0,0%) O: 0 (0,0%)	Pass: R: 1245 (100,0%) O: 637 (100,0%) Gagal: R: 0 (0,0%) O: 0 (0,0%)

Perhatikan bahwa ini menggunakan JoniRegularExpressionFactory untuk uji pattern dan format regex .

Jackson Parser

Perpustakaan ini menggunakan Jackson yang merupakan parser Java Json yang banyak digunakan dalam proyek lain. Jika Anda sudah menggunakan parser Jackson di proyek Anda, wajar untuk memilih perpustakaan ini daripada orang lain untuk validasi skema.

Dukungan YAML

Perpustakaan bekerja dengan JSON dan YAML pada definisi skema dan data input.

Dukungan OpenAPI

Spesifikasi OpenAPI 3.0 menggunakan skema JSON untuk memvalidasi permintaan/respons, tetapi ada beberapa perbedaan. Dengan file konfigurasi, Anda dapat mengaktifkan pustaka untuk bekerja dengan validasi OpenAPI 3.0.

Dependensi minimal

Mengikuti prinsip desain platform cahaya, perpustakaan ini memiliki dependensi minim untuk memastikan tidak ada konflik ketergantungan saat menggunakannya.

Dependensi yang diperlukan

Berikut ini adalah dependensi yang secara otomatis akan dimasukkan ketika perpustakaan ini disertakan.

< 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 >

Dependensi opsional

Berikut ini adalah dependensi opsional yang mungkin diperlukan untuk opsi tertentu.

Ini tidak dimasukkan secara otomatis dan mengatur opsi yang relevan tanpa menambahkan perpustakaan akan menghasilkan 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 >

Ketergantungan yang dapat dikecualikan

Berikut ini adalah dependensi yang diperlukan yang secara otomatis disertakan, tetapi dapat secara eksplisit dikecualikan jika tidak diperlukan.

Ketergantungan YAML dapat dikecualikan jika ini tidak diperlukan. Mencoba memproses skema atau input yang merupakan YAML akan menghasilkan 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 >

Ketergantungan waktu ETHLO dapat dikecualikan jika validasi yang akurat dari format date-time tidak diperlukan. Format date-time kemudian akan menggunakan java.time.OffsetDateTime untuk menentukan apakah date-time valid.

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

Masyarakat

Perpustakaan ini sangat aktif dengan banyak kontributor. Fitur baru dan perbaikan bug ditangani dengan cepat oleh anggota tim. Karena ini merupakan ketergantungan penting dari kerangka cahaya-4J dalam organisasi GitHub yang sama, itu akan dikembangkan dan dipelihara bersama dengan kerangka kerja.

Prasyarat

Perpustakaan mendukung Java 8 dan lebih tinggi. Jika Anda ingin membangun dari kode sumber, Anda perlu menginstal JDK 8 secara lokal. Untuk mendukung beberapa versi JDK, Anda dapat menggunakan SDKMAN

Penggunaan

Menambahkan ketergantungan

Paket ini tersedia di Maven Central.

Maven:

< 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' );
}

Memvalidasi input terhadap skema

Contoh berikut menunjukkan bagaimana input divalidasi terhadap skema. Itu terdiri dari langkah -langkah berikut.

Membuat pabrik skema dengan dialek skema default dan bagaimana skema dapat diambil.
- Mengkonfigurasi Pemetaan $id ke URI Pengambilan Menggunakan schemaMappers .
- Mengkonfigurasi bagaimana skema dimuat menggunakan pengambilan URI menggunakan schemaLoaders . Misalnya Map<String, String> schemas yang berisi pemetaan pengambilan URI ke data skema sebagai String dapat dikonfigurasi menggunakan builder.schemaLoaders(schemaLoaders -> schemaLoaders.schemas(schemas)) . Ini juga menerima Function<String, String> schemaRetrievalFunction .
Membuat konfigurasi untuk mengendalikan perilaku validator.
Memuat skema dari lokasi skema bersama dengan konfigurasi validator.
Menggunakan skema untuk memvalidasi data bersama dengan pengaturan konfigurasi spesifik eksekusi seperti misalnya lokasi atau apakah pernyataan format diaktifkan.

 // 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 );
});

Memvalidasi skema terhadap meta-skema

Contoh berikut menunjukkan bagaimana skema divalidasi terhadap meta-skema.

Ini sebenarnya sama dengan memvalidasi input terhadap skema kecuali dalam hal ini inputnya adalah skema dan skema yang digunakan adalah meta-skema.

Perhatikan bahwa meta-schemas untuk Draft 4, Draft 6, Draft 7, Draft 2019-09 dan Draft 2020-12 dibundel dengan perpustakaan dan sumber daya ClassPath ini akan digunakan secara default.

 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 );
});

Hasil dan format output

Hasil

Jenis hasil berikut dihasilkan oleh perpustakaan.

Jenis Keterangan

Pernyataan Kesalahan validasi yang dihasilkan oleh kata kunci pada instance data input tertentu. Ini umumnya dijelaskan dalam ValidationMessage atau dalam OutputUnit . Perhatikan bahwa sejak draf 2019-09 kata kunci format tidak lagi menghasilkan pernyataan secara default dan sebaliknya hanya menghasilkan anotasi kecuali dikonfigurasi sebaliknya menggunakan opsi konfigurasi atau dengan menggunakan meta-skema yang menggunakan kosa kata yang sesuai.

Anotasi Informasi tambahan yang dihasilkan oleh kata kunci untuk instance data input tertentu. Ini umumnya dijelaskan dalam OutputUnit . Koleksi dan pelaporan anotasi dimatikan secara default. Anotasi yang diperlukan oleh kata kunci seperti unevaluatedProperties atau unevaluatedItems selalu dikumpulkan untuk tujuan evaluasi dan tidak dapat dinonaktifkan tetapi tidak akan dilaporkan kecuali dikonfigurasi untuk melakukannya.

Jenis	Keterangan
Pernyataan	Kesalahan validasi yang dihasilkan oleh kata kunci pada instance data input tertentu. Ini umumnya dijelaskan dalam `ValidationMessage` atau dalam `OutputUnit` . Perhatikan bahwa sejak draf 2019-09 kata kunci `format` tidak lagi menghasilkan pernyataan secara default dan sebaliknya hanya menghasilkan anotasi kecuali dikonfigurasi sebaliknya menggunakan opsi konfigurasi atau dengan menggunakan meta-skema yang menggunakan kosa kata yang sesuai.
Anotasi	Informasi tambahan yang dihasilkan oleh kata kunci untuk instance data input tertentu. Ini umumnya dijelaskan dalam `OutputUnit` . Koleksi dan pelaporan anotasi dimatikan secara default. Anotasi yang diperlukan oleh kata kunci seperti `unevaluatedProperties` atau `unevaluatedItems` selalu dikumpulkan untuk tujuan evaluasi dan tidak dapat dinonaktifkan tetapi tidak akan dilaporkan kecuali dikonfigurasi untuk melakukannya.

Informasi berikut digunakan untuk menggambarkan kedua jenis hasil.

Jenis	Keterangan
Jalur evaluasi	Ini adalah himpunan kunci dari root yang melaluinya evaluasi berlalu untuk mencapai skema untuk mengevaluasi instance. Ini termasuk `$ref` dan `$dynamicRef` . misalnya. `/properties/bar/$ref/properties/bar-prop`
Lokasi Skema	Ini adalah IRI kanonik dari skema ditambah fragmen pointer JSON ke skema yang digunakan untuk mengevaluasi instance. misalnya. `https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop`
Lokasi instan	Ini adalah fragmen pointer JSON ke data instance yang sedang dievaluasi. misalnya. `/bar/bar-prop`

Pernyataan berisi informasi tambahan berikut

Jenis	Keterangan
Pesan	Pesan kesalahan validasi.
Kode	Kode kesalahan.
Kunci Pesan	Kunci pesan yang digunakan untuk menghasilkan pesan untuk lokalisasi.
Argumen	Argumen yang digunakan untuk menghasilkan pesan.
Jenis	Kata kunci yang menghasilkan pesan.
Milik	Nama properti yang menyebabkan kesalahan validasi misalnya untuk kata kunci `required` . Perhatikan bahwa ini bukan bagian dari lokasi instan seperti yang menunjuk ke node instan.
Node skema	`JsonNode` ditunjuk oleh lokasi skema. Ini adalah data skema yang menyebabkan data input gagal. Dimungkinkan untuk mendapatkan informasi lokasi dengan mengkonfigurasi `JsonSchemaFactory` dengan `JsonNodeReader` yang menggunakan `LocationJsonNodeFactoryFactory` dan menggunakan `JsonNodes.tokenLocationOf(schemaNode)` .
Node instan	`JsonNode` ditunjuk oleh lokasi instan. Ini adalah data input yang gagal validasi. Dimungkinkan untuk mendapatkan informasi lokasi dengan mengkonfigurasi `JsonSchemaFactory` dengan `JsonNodeReader` yang menggunakan `LocationJsonNodeFactoryFactory` dan menggunakan `JsonNodes.tokenLocationOf(instanceNode)` .
Kesalahan	Kesalahannya.
Detail	Detail tambahan yang dapat ditetapkan oleh implementasi validator kata kunci khusus. Ini tidak digunakan oleh perpustakaan.

Anotasi berisi informasi tambahan berikut

Jenis	Keterangan
Nilai	Nilai anotasi dihasilkan

Informasi baris dan kolom

Perpustakaan dapat dikonfigurasi untuk menyimpan informasi jalur dan kolom dalam instance JsonNode untuk node instance dan skema. Ini akan mempengaruhi kinerja dan tidak dikonfigurasi secara default.

Ini dilakukan dengan mengonfigurasi JsonNodeReader yang menggunakan LocationJsonNodeFactoryFactory di JsonSchemaFactory . Informasi JsonLocation kemudian dapat diambil menggunakan 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 ());

Format output

Perpustakaan ini mengimplementasikan format output bendera, daftar dan hierarkis yang ditentukan dalam spesifikasi untuk output yang dapat dibaca mesin untuk validasi dan anotasi skema JSON.

Daftar dan format output hierarkis sangat membantu untuk memahami bagaimana sistem sampai pada hasil tertentu.

Format output	Keterangan
Bawaan	Menghasilkan daftar pernyataan.
Boolean	Mengembalikan `true` jika validasi berhasil. Perhatikan bahwa opsi Fail Fast dihidupkan secara default untuk format output ini.
Bendera	Mengembalikan objek `OutputFlag` dengan `valid` yang `true` jika validasi berhasil. Perhatikan bahwa opsi Fail Fast dihidupkan secara default untuk format output ini.
Daftar	Mengembalikan objek `OutputUnit` dengan `details` dengan daftar objek `OutputUnit` dengan pernyataan dan anotasi. Perhatikan bahwa anotasi tidak dikumpulkan secara default dan harus diaktifkan karena akan memengaruhi kinerja.
Hierarkis	Mengembalikan objek `OutputUnit` dengan hierarki objek `OutputUnit` untuk jalur evaluasi dengan pernyataan dan anotasi. Perhatikan bahwa anotasi tidak dikumpulkan secara default dan harus diaktifkan karena akan memengaruhi kinerja.

Contoh berikut menunjukkan cara menghasilkan format output hierarkis dengan pengumpulan anotasi dan pelaporan dihidupkan dan format pernyataan dihidupkan.

 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 );
});

Berikut ini adalah output sampel dari format hierarkis.

{
  "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 "
      }
    } ]
  } ]
}

Konfigurasi

Konfigurasi Eksekusi

Nama	Keterangan	Nilai default
`annotationCollectionEnabled`	Mengontrol apakah anotasi dikumpulkan selama pemrosesan. Perhatikan bahwa mengumpulkan anotasi akan mempengaruhi kinerja.	`false`
`annotationCollectionFilter`	Predikat yang digunakan untuk mengontrol kata kunci mana yang akan dikumpulkan dan melaporkan anotasi. Ini membutuhkan `annotationCollectionEnabled` menjadi `true` .	`keyword -> false`
`locale`	Lokal yang akan digunakan untuk menghasilkan pesan di `ValidationMessage` . Perhatikan bahwa nilai ini disalin dari `SchemaValidatorsConfig` untuk setiap eksekusi.	`Locale.getDefault()`
`failFast`	Apakah akan mengembalikan kegagalan segera ketika pernyataan dihasilkan. Perhatikan bahwa nilai ini disalin dari `SchemaValidatorsConfig` untuk setiap eksekusi tetapi secara otomatis diatur ke `true` untuk format output boolean dan bendera.	`false`
`formatAssertionsEnabled`	Standarnya adalah untuk menghasilkan pernyataan format dari draft 4 ke draft 7 dan hanya menghasilkan anotasi dari draft 2019-09. Pengaturan ke `true` atau `false` akan mengesampingkan perilaku default.	`null`
`debugEnabled`	Mengontrol apakah pencatatan debug diaktifkan untuk mencatat informasi simpul saat diproses. Perhatikan bahwa ini akan menghasilkan banyak log yang akan memengaruhi kinerja.	`false`

Konfigurasi Validator Skema

Nama	Keterangan	Nilai default
`applyDefaultsStrategy`	Strategi untuk menerapkan default saat berjalan saat node hilang atau nol ditemui.	`ApplyDefaultsStrategy.EMPTY_APPLY_DEFAULTS_STRATEGY`
`cacheRefs`	Apakah skema yang dimuat dari referensi akan di -cache dan digunakan kembali untuk menjalankan berikutnya. Menetapkan ini ke `false` akan mempengaruhi kinerja tetapi mungkin perlu untuk mencegah penggunaan memori yang tinggi untuk cache jika beberapa aplikator bersarang seperti `anyOf` , `oneOf` dan `allOf` digunakan.	`true`
`discriminatorKeywordEnabled`	Apakah kata kunci `discriminator` ditangani sesuai dengan OpenAPI 3.	`false`
`errorMessageKeyword`	Kata kunci yang digunakan untuk pesan kesalahan khusus dalam skema. Jika tidak mengatur fitur ini dinonaktifkan. Ini biasanya disetel ke `errorMessage` atau `message` .	`null`
`executionContextCustomizer`	Ini dapat digunakan untuk menyesuaikan `ExecutionContext` yang dihasilkan oleh `JsonSchema` untuk setiap menjalankan validasi.	`null`
`failFast`	Apakah akan mengembalikan kegagalan segera ketika pernyataan dihasilkan.	`false`
`formatAssertionsEnabled`	Standarnya adalah untuk menghasilkan pernyataan format dari draft 4 ke draft 7 dan hanya menghasilkan anotasi dari draft 2019-09. Pengaturan ke `true` atau `false` akan mengesampingkan perilaku default.	`null`
`javaSemantics`	Apakah Semantik Java digunakan untuk kata kunci `type` .	`false`
`locale`	Lokal yang akan digunakan untuk menghasilkan pesan di `ValidationMessage` .	`Locale.getDefault()`
`losslessNarrowing`	Apakah penyempitan lossless digunakan untuk kata kunci `type` .	`false`
`messageSource`	Ini digunakan untuk mengambil pesan spesifik lokal.	`DefaultMessageSource.getInstance()`
`nullableKeywordEnabled`	Apakah kata kunci `nullable` ditangani sesuai dengan OpenAPI 3.0. Ini mempengaruhi kata kunci `enum` dan `type` .	`false`
`pathType`	Jenis jalur yang akan digunakan untuk melaporkan lokasi instan dan jalur evaluasi. Atur ke `PathType.JSON_PATH` untuk menggunakan JSON Path.	`PathType.JSON_POINTER`
`preloadJsonSchema`	Apakah skema akan dimuat sebelum memproses input apa pun. Ini akan menggunakan memori tetapi pelaksanaan validasi akan lebih cepat.	`true`
`preloadJsonSchemaRefMaxNestingDepth`	Kedalaman maksimum dari jalur evaluasi ke preload saat preloading referensi.	`40`
`readOnly`	Apakah skema hanya dibaca. Ini mempengaruhi kata kunci `readOnly` .	`null`
`regularExpressionFactory`	Pabrik yang akan digunakan untuk membuat ekspresi reguler misalnya `JoniRegularExpressionFactory` atau `GraalJSRegularExpressionFactory` . Ini membutuhkan ketergantungan untuk ditambahkan secara manual ke proyek atau `ClassNotFoundException` akan dilemparkan.	`JDKRegularExpressionFactory.getInstance()`
`schemaIdValidator`	Ini digunakan untuk menyesuaikan bagaimana nilai `$id` divalidasi. Perhatikan bahwa implementasi default memungkinkan fragmen yang tidak kosong di mana tidak ada IRI basis yang ditentukan dan juga memungkinkan nilai `$id` IRI non-absolute dalam skema root.	`JsonSchemaIdValidator.DEFAULT`
`strict`	Ini ditetapkan apakah kata kunci ketat dalam validasinya. Apa yang dilakukannya tergantung pada validator individu.
`typeLoose`	Apakah jenis ditafsirkan secara longgar. Jika diatur ke True, nilai tunggal dapat diartikan sebagai array ukuran 1. String juga dapat ditafsirkan sebagai bilangan, bilangan bulat atau boolean.	`false`
`writeOnly`	Apakah skema hanya menulis. Ini mempengaruhi kata kunci `writeOnly` .	`null`

Pertimbangan kinerja

Ketika perpustakaan membuat skema dari pabrik skema, ia menciptakan instance validator yang berbeda untuk setiap lokasi di jalur evaluasi. Ini berarti jika ada berbeda $ref yang merujuk pada lokasi skema yang sama, instance validator yang berbeda dibuat untuk setiap jalur evaluasi.

Ketika skema dibuat, perpustakaan akan secara default secara otomatis memuat semua validator yang diperlukan dan menyelesaikan referensi. Ini dapat dinonaktifkan dengan opsi preloadJsonSchema di SchemaValidatorsConfig . Pada titik ini, tidak ada pengecualian yang akan dilemparkan jika referensi tidak dapat diselesaikan. Jika ada referensi yang bersifat siklik, hanya siklus pertama yang akan dimuat sebelumnya. Jika Anda ingin memastikan bahwa referensi jarak jauh semua dapat diselesaikan, metode initializeValidators perlu dipanggil pada JsonSchema yang akan melempar pengecualian jika ada referensi yang tidak dapat diselesaikan.

Contoh untuk JsonSchemaFactory dan JsonSchema yang dibuat darinya dirancang untuk menjadi aman agar konfigurasinya tidak dimodifikasi dan harus di-cache dan digunakan kembali. Tidak menggunakan kembali JsonSchema berarti bahwa data skema perlu diulangi diuraikan dengan instance validator yang dibuat dan referensi diselesaikan. Ketika referensi diselesaikan, validator yang dibuat akan di -cache. Untuk skema yang memiliki referensi bersarang, memori yang diperlukan untuk validator mungkin sangat tinggi, dalam hal ini caching mungkin perlu dinonaktifkan menggunakan opsi cacheRefs di SchemaValidatorsConfig . Menonaktifkan Ini berarti validator dari referensi perlu diciptakan kembali untuk setiap menjalankan validasi yang akan memengaruhi kinerja.

Mengumpulkan anotasi akan berdampak buruk pada kinerja validasi.

Spesifikasi draft sebelumnya mengandung lebih sedikit kata kunci yang berpotensi berdampak pada kinerja. Misalnya penggunaan kata kunci unevaluatedProperties atau kata kunci unevaluatedItems akan memicu pengumpulan anotasi di validator terkait, seperti validator properties atau items .

Ini tidak berarti bahwa menggunakan skema dengan spesifikasi draft selanjutnya akan secara otomatis menyebabkan dampak kinerja. Misalnya, validator properties akan melakukan pemeriksaan untuk menentukan apakah anotasi perlu dikumpulkan, dan memeriksa apakah meta-schema berisi kata kunci unevaluatedProperties dan apakah kata kunci unevaluatedProperties yang ada berdekatan dengan jalur evaluasi.

Pertimbangan keamanan

Perpustakaan mengasumsikan bahwa skema yang dimuat dipercaya. Model keamanan ini mengasumsikan kasus penggunaan di mana skema dibundel dengan aplikasi di classpath.

Masalah	Keterangan	Mitigasi
Pemuatan Skema	Perpustakaan secara default akan memuat skema dari Classpath dan melalui Internet jika diperlukan.	`DisallowSchemaLoader` dapat dikonfigurasi untuk tidak mengizinkan pengambilan skema. Sebagai alternatif, seorang `AllowSchemaLoader` dikonfigurasi dapat dikonfigurasi untuk membatasi iris pengambilan yang diizinkan.
Caching skema	Perpustakaan secara default Preloads dan cache referensi saat memuat skema. Meskipun ada kedalaman sarang maksimal ketika skema preloading masih dimungkinkan untuk membangun skema yang memiliki kipas yang menghabiskan banyak memori dari server.	Atur opsi `cacheRefs` di `SchemaValidatorsConfig` menjadi false.
Ekspresi reguler	Perpustakaan tidak memvalidasi jika ekspresi reguler yang diberikan rentan terhadap penolakan layanan (redos).	Sebuah `AllowRegularExpressionFactory` dapat dikonfigurasi untuk melakukan validasi pada ekspresi reguler yang diizinkan.
Kesalahan validasi	Perpustakaan secara default mencoba mengembalikan semua kesalahan validasi. Penggunaan aplikator seperti `allOf` dengan sejumlah besar skema dapat mengakibatkan sejumlah besar kesalahan validasi yang mengambil memori.	Setel opsi `failFast` di `SchemaValidatorsConfig` untuk segera kembali ketika kesalahan pertama ditemui. `OutputFormat.BOOLEAN` atau `OutputFormat.FLAG` juga dapat digunakan.

Awal yang cepat

Menyesuaikan pengambilan skema

Menyesuaikan meta-skema, kosa kata, kata kunci dan format

Spesifikasi OpenAPI

Validator

Konfigurasi

Versi spesifikasi

Validasi YAML

Konteks kolektor

JSON Schema Walkers dan Walklisteners

Ekspresi reguler

Pesan Kesalahan Kustom

Banyak bahasa

Validasi Metaschema

Memvalidasi durasi RFC 3339

Proyek

Light-Rest-4J, Light-Graphql-4J dan Light-Hybrid-4J menggunakan pustaka ini untuk memvalidasi permintaan dan respons berdasarkan spesifikasi. Jika Anda menggunakan kerangka kerja lain seperti Spring Boot, Anda dapat menggunakan OpenApivalidator, validator OpenApi 3.0 generik berdasarkan spesifikasi OpenAPI 3.0.

Jika Anda memiliki proyek menggunakan perpustakaan ini, silakan kirim PR untuk menambahkan proyek Anda di bawah ini.

Kontributor

Terima kasih kepada orang -orang berikut yang telah berkontribusi pada proyek ini. Jika Anda menggunakan perpustakaan ini, harap pertimbangkan untuk menjadi sponsor untuk salah satu kontributor.

@Stevehu

@Prashanth-Chaitanya

@fdutton

@valfirst

@Balloonwen

@jiachen1120

@ddobrin

@eskabetxe

@ehrmann

@prashanthjos

@Subhajitdas298

@Fwiesner