json schema validator Download - json schema validator Quellcode Download

Dies ist eine Java-Implementierung des JSON-Schema-Kernentwurfs V4, V6, V7, V2019-09 und V2020-12 für die JSON-Schema-Validierung. Diese Implementierung unterstützt das Anpassen von Meta-Schemas, Vokabularien, Schlüsselwörtern und Formaten.

Darüber hinaus wird die OpenAPI 3-Anforderung/Antwortvalidierung durch die Verwendung des entsprechenden Meta-Schemas unterstützt. Für Benutzer, die Informationen von einem JSON -Knoten basierend auf dem Schema sammeln möchten, können die Wanderer helfen. Der JSON -Parser ist der Jackson Parser. Da es sich um eine Schlüsselkomponente in unserem Light-4J-MicroServices-Framework handelt, um die Anforderung/Reaktion gegen OpenAPI-Spezifikation für Light-REST-4J- und RPC-Schema für Light-Hybrid-4J zur Laufzeit zu validieren, ist die Leistung der wichtigste Aspekt des Designs.

JSON -Schema -Spezifikationskompatibilität

Informationen zur Kompatibilitätsunterstützung für jede Version, einschließlich bekannter Probleme, finden Sie in der Kompatibilität mit dem Dokument für JSON -Schema -Versionen.

Seit dem Entwurf 2019-09 generiert das format nur standardmäßig Annotationen und generiert keine Behauptungen.

Dieses Verhalten kann überschrieben werden, um Behauptungen zu generieren, indem das setFormatAssertionsEnabled in SchemaValidatorsConfig oder ExecutionConfig auf true festgelegt wird.

Upgrade auf neue Versionen

Diese Bibliothek kann Bruchänderungen in minor Versionsveröffentlichungen enthalten, für die möglicherweise Codeänderungen erforderlich sind.

Informationen zu bemerkenswerten oder brechen Änderungen beim Upgrade der Bibliothek finden Sie im Upgrade auf neue Versionen.

Auf der Seite "Releases" werden Informationen zu den neuesten Versionen enthalten.

Vergleich mit anderen Implementierungen

Das JSON -Schema -Validierungsvergleichsprojekt aus Creek hat einen informativen Vergleich von Implementierungen von JVM -basierten Schema -Validierung, die sowohl die funktionalen als auch die Leistungsmerkmale einer Reihe verschiedener JAVA -Implementierungen vergleicht.

Funktioneller Vergleich
Leistungsvergleich

Das Bowtie-Projekt enthält einen Bericht, in dem die funktionalen Merkmale verschiedener Implementierungen, einschließlich Nicht-Java-Implementierungen, vergleicht, jedoch kein Leistungsbenchmarking ausführt.

Warum diese Bibliothek

Leistung

Dies sollte die schnellste Implementierung von Java JSON Schema Validator sein.

Im Folgenden sind die Benchmark -Ergebnisse des JSON -Schemas -Validators Perftest Project, das den Java Microbenchmark -Kabelbaum verwendet.

Beachten Sie, dass die Benchmark -Ergebnisse in hohem Maße von den für die Validierung verwendeten Eingabedaten -Workloads und Schemas abhängen.

In diesem Fall verwendet diese Workload die Spezifikation Entwurf 4 und testet weitgehend die Leistung der Bewertung des Schlüsselworts properties . Sie können sich auf die Ergebnisse des Leistungsvergleichs von JVM -basierten JSON -Schema -Validierungsimplementierungen für Benchmark -Ergebnisse für typischere Workloads beziehen

Wenn die Leistung eine wichtige Überlegung ist, sollten die spezifischen Proben -Workloads bewertet werden, da bei Verwendung bestimmter Schlüsselwörter unterschiedliche Leistungsmerkmale vorliegen. Zum Beispiel wird die Verwendung des Schlüsselworts unevaluatedProperties oder unevaluatedItems in den zugehörigen Validatoren wie den properties oder items -Validatoren die Annotationssammlung auslösen, und die Annotationssammlung wirkt sich negativ auf die Leistung aus.

Netzwerknt 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

Funktionalität

Diese Implementierung wird gegen die JSON -Schema -Testsuite getestet. Da die Suite kontinuierlich zu Tests hinzugefügt werden, sind diese Testergebnisse möglicherweise nicht Strom.

Implementierungen	Gesamt	Draft_03	Draft_04	Draft_06	Draft_07	Draft_2019_09	WRECT_2020_12
Netzwerknt	Pass: R: 4803 (100,0%) O: 2372 (100,0%) Fehler: R: 0 (0,0%) O: 0 (0,0%)		Pass: R: 610 (100,0%) O: 251 (100,0%) Fehler: R: 0 (0,0%) O: 0 (0,0%)	Pass: R: 822 (100,0%) O: 318 (100,0%) Fehler: R: 0 (0,0%) O: 0 (0,0%)	Pass: R: 906 (100,0%) O: 541 (100,0%) Fehler: R: 0 (0,0%) O: 0 (0,0%)	Pass: R: 1220 (100,0%) O: 625 (100,0%) Fehler: R: 0 (0,0%) O: 0 (0,0%)	Pass: R: 1245 (100,0%) O: 637 (100,0%) Fehler: R: 0 (0,0%) O: 0 (0,0%)

Beachten Sie, dass dies die JoniRegularExpressionFactory für das pattern und format regex -Test verwendet.

Jackson Parser

Diese Bibliothek verwendet Jackson, ein Java JSON -Parser, der in anderen Projekten häufig verwendet wird. Wenn Sie den Jackson -Parser in Ihrem Projekt bereits verwenden, ist es natürlich, diese Bibliothek für andere für die Schema -Validierung zu wählen.

YAML -Unterstützung

Die Bibliothek arbeitet mit JSON und YAML sowohl für Schema -Definitionen als auch für Eingabedaten.

OpenAPI -Unterstützung

In der OpenAPI 3.0 -Spezifikation wird das JSON -Schema verwendet, um die Anfrage/Antwort zu validieren, es gibt jedoch einige Unterschiede. Mit einer Konfigurationsdatei können Sie der Bibliothek ermöglichen, mit OpenAPI 3.0 -Validierung zu arbeiten.

Minimale Abhängigkeiten

Nach dem Entwurfsprinzip der Lichtplattform verfügt diese Bibliothek über minimale Abhängigkeiten, um sicherzustellen, dass bei der Verwendung keine Abhängigkeitskonflikte vorhanden sind.

Erforderliche Abhängigkeiten

Im Folgenden sind die Abhängigkeiten aufgeführt, die automatisch enthalten sind, wenn diese Bibliothek enthalten ist.

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

Optionale Abhängigkeiten

Im Folgenden sind die optionalen Abhängigkeiten aufgeführt, die für bestimmte Optionen erforderlich sein können.

Diese werden nicht automatisch enthalten, und das Einstellen der relevanten Option ohne Hinzufügen der Bibliothek führt zu einer 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 >

Ausgeschlossene Abhängigkeiten

Die folgenden Abhängigkeiten sind erforderlich, die automatisch enthalten sind, aber ausdrücklich ausgeschlossen werden können, wenn sie nicht erforderlich sind.

Die YAML -Abhängigkeit kann ausgeschlossen werden, wenn dies nicht erforderlich ist. Der Versuch, Schemata oder Eingaben zu verarbeiten, die YAML sind, führt zu einer 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 >

Die zeitliche Abhängigkeit von Etlo kann ausgeschlossen werden, wenn keine genaue Validierung des date-time erforderlich ist. Das date-time -Format verwendet dann java.time.OffsetDateTime , um festzustellen, ob das date-time gültig ist.

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

Gemeinschaft

Diese Bibliothek ist sehr aktiv mit vielen Mitwirkenden. Neue Funktionen und Fehlerbehebungen werden von den Teammitgliedern schnell behandelt. Da es sich um eine wesentliche Abhängigkeit des Light-4J-Frameworks in derselben Github-Organisation handelt, wird es zusammen mit dem Rahmen entwickelt und aufrechterhalten.

Voraussetzung

Die Bibliothek unterstützt Java 8 und Up. Wenn Sie aus dem Quellcode erstellen möchten, müssen Sie JDK 8 lokal installieren. Um mehrere Versionen von JDK zu unterstützen, können Sie SDKMAN verwenden

Verwendung

Hinzufügen der Abhängigkeit

Dieses Paket ist auf Maven Central erhältlich.

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

Validierung von Eingaben gegen ein Schema

Das folgende Beispiel zeigt, wie Eingaben gegen ein Schema validiert werden. Es umfasst die folgenden Schritte.

Erstellen einer Schema -Fabrik mit dem Standardschema -Dialekt und wie die Schemas abgerufen werden können.
- Konfigurieren der Zuordnung der $id zu einem Abruf -URI mithilfe von schemaMappers .
- Konfigurieren, wie die Schemata mithilfe der Abruf -URI unter Verwendung schemaLoaders geladen werden. Zum Beispiel eine Map<String, String> schemas die eine Zuordnung von Abruf -URI zu Schemadaten als String enthält, kann durch Konfigurieren von builder.schemaLoaders(schemaLoaders -> schemaLoaders.schemas(schemas)) . Dies akzeptiert auch eine Function<String, String> schemaRetrievalFunction .
Erstellen einer Konfiguration zur Steuerung des Validatorverhaltens.
Laden eines Schemas von einem Schema -Standort zusammen mit der Validator -Konfiguration.
Verwenden des Schemas zur Validierung der Daten sowie die Einstellung einer ausführungsspezifischen Konfiguration wie zum Beispiel das Gebietsschema oder der Frage, ob Formatbehauptungen aktiviert sind.

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

Validierung eines Schemas gegen ein Meta-Schema

Das folgende Beispiel zeigt, wie ein Schema gegen ein Meta-Schema validiert wird.

Dies ist tatsächlich das gleiche wie das Validieren von Eingaben gegen ein Schema, außer in diesem Fall ist das Eingang das Schema und das verwendete Schema das Meta-Schema.

Beachten Sie, dass die Meta-Schemas für den Entwurf 4, den Entwurf 6, den Entwurf 7, den Entwurf 2019-09 und den Entwurf 2020-12 mit der Bibliothek gebündelt sind und diese Klassenspath-Ressourcen standardmäßig verwendet werden.

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

Ergebnisse und Ausgangsformate

Ergebnisse

Die folgenden Arten von Ergebnissen werden von der Bibliothek generiert.

Typ Beschreibung

Behauptungen Validierungsfehler, die durch ein Schlüsselwort für eine bestimmte Eingabedateninstanz generiert werden. Dies wird im Allgemeinen in einer ValidationMessage oder in einem OutputUnit beschrieben. Beachten Sie, dass seit Entwurf 2019-09 das Schlüsselwort format nicht mehr standardmäßig Behauptungen mehr generiert und stattdessen nur Annotationen generiert, sofern sie nicht mithilfe einer Konfigurationsoption oder mithilfe eines Meta-Schemas, der das entsprechende Vokabular verwendet, anders konfiguriert ist.

Anmerkungen Zusätzliche Informationen, die durch ein Schlüsselwort für eine bestimmte Eingabedateninstanz generiert werden. Dies wird im Allgemeinen in einem OutputUnit beschrieben. Annotationssammlung und Berichterstattung wird standardmäßig ausgeschaltet. Annotationen, die von Schlüsselwörtern wie unevaluatedProperties oder unevaluatedItems erforderlich sind, werden immer zu Bewertungszwecken erfasst und können nicht deaktiviert werden, aber nicht gemeldet werden, wenn dies nicht so konfiguriert ist.

Typ	Beschreibung
Behauptungen	Validierungsfehler, die durch ein Schlüsselwort für eine bestimmte Eingabedateninstanz generiert werden. Dies wird im Allgemeinen in einer `ValidationMessage` oder in einem `OutputUnit` beschrieben. Beachten Sie, dass seit Entwurf 2019-09 das Schlüsselwort `format` nicht mehr standardmäßig Behauptungen mehr generiert und stattdessen nur Annotationen generiert, sofern sie nicht mithilfe einer Konfigurationsoption oder mithilfe eines Meta-Schemas, der das entsprechende Vokabular verwendet, anders konfiguriert ist.
Anmerkungen	Zusätzliche Informationen, die durch ein Schlüsselwort für eine bestimmte Eingabedateninstanz generiert werden. Dies wird im Allgemeinen in einem `OutputUnit` beschrieben. Annotationssammlung und Berichterstattung wird standardmäßig ausgeschaltet. Annotationen, die von Schlüsselwörtern wie `unevaluatedProperties` oder `unevaluatedItems` erforderlich sind, werden immer zu Bewertungszwecken erfasst und können nicht deaktiviert werden, aber nicht gemeldet werden, wenn dies nicht so konfiguriert ist.

Die folgenden Informationen werden verwendet, um beide Ergebnistypen zu beschreiben.

Typ	Beschreibung
Bewertungsweg	Dies ist der Satz von Schlüssel aus der Wurzel, durch die die Bewertung zum Schema zur Bewertung der Instanz gelangt. Dies beinhaltet `$ref` und `$dynamicRef` . z.B. `/properties/bar/$ref/properties/bar-prop`
SCHEMA -Standort	Dies ist der kanonische IRI des Schemas sowie das JSON -Zeigerfragment zu dem Schema, das zur Bewertung der Instanz verwendet wurde. z.B. `https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop`
Instanzort	Dies ist das JSON -Zeigerfragment zu den Instanzdaten, die bewertet wurden. z.B. `/bar/bar-prop`

Behauptungen enthalten die folgenden zusätzlichen Informationen

Typ	Beschreibung
Nachricht	Die Validierungsfehlermeldung.
Code	Der Fehlercode.
Nachrichtenschlüssel	Der Nachrichtenschlüssel zum Generieren der Nachricht zur Lokalisierung.
Argumente	Die Argumente, die zum Generieren der Nachricht verwendet wurden.
Typ	Das Schlüsselwort, das die Nachricht generiert hat.
Eigentum	Der Eigenschaftsname, der den Validierungsfehler für das `required` Schlüsselwort verursacht hat. Beachten Sie, dass dies nicht Teil des Instanzstandorts ist, da dies auf den Instanzknoten zeigt.
Schemaknoten	Der `JsonNode` zeigte vom Schema -Standort. Dies sind die Schema -Daten, die dazu geführt haben, dass die Eingabedaten fehlschlagen. Es ist möglich, die Standortinformationen zu erhalten, indem der `JsonSchemaFactory` mit einem `JsonNodeReader` konfiguriert wird, der den `LocationJsonNodeFactoryFactory` und die Verwendung `JsonNodes.tokenLocationOf(schemaNode)` verwendet.
Instanzknoten	Der `JsonNode` wies durch den Instanzstandort auf. Dies sind die Eingabedaten, die die Validierung fehlgeschlagen haben. Es ist möglich, die Standortinformationen zu erhalten, indem der `JsonSchemaFactory` mit einem `JsonNodeReader` konfiguriert wird, der den `LocationJsonNodeFactoryFactory` und die Verwendung `JsonNodes.tokenLocationOf(instanceNode)` verwendet.
Fehler	Der Fehler.
Details	Zusätzliche Details, die durch benutzerdefinierte Keyword -Validator -Implementierungen festgelegt werden können. Dies wird nicht von der Bibliothek verwendet.

Anmerkungen enthalten die folgenden zusätzlichen Informationen

Typ	Beschreibung
Wert	Der Annotationswert erzeugt

Zeilen- und Spalteninformationen

Die Bibliothek kann so konfiguriert werden, dass sie Zeilen- und Spalteninformationen in den JsonNode -Instanzen für die Instanz- und Schemaknoten speichern. Dies wirkt sich nachteilig auf die Leistung aus und ist standardmäßig nicht konfiguriert.

Dies geschieht durch Konfiguration eines JsonNodeReader , der den LocationJsonNodeFactoryFactory auf dem JsonSchemaFactory verwendet. Die JsonLocation -Informationen können dann mit JsonNodes.tokenLocationOf(jsonNode) abgerufen werden.

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

Ausgangsformate

Diese Bibliothek implementiert die in der Spezifikation für die maschinenlesbaren Ausgabe für die Validierung und Annotation von maschinellen Lesbare ausführbaren Ausgabe und die in der Spezifikation definierte hierarchische Ausgangsformate.

Die Liste und hierarchische Ausgangsformate sind besonders hilfreich, um zu verstehen, wie das System zu einem bestimmten Ergebnis gekommen ist.

Ausgangsformat	Beschreibung
Standard	Generiert die Liste der Behauptungen.
Boolean	Gibt `true` zurück, wenn die Validierung erfolgreich ist. Beachten Sie, dass die Option FAIL FAST standardmäßig für dieses Ausgabeformat eingeschaltet wird.
Flagge	Gibt ein `OutputFlag` -Objekt mit `valid` `true` zurück, wenn die Validierung erfolgreich ist. Beachten Sie, dass die Option FAIL FAST standardmäßig für dieses Ausgabeformat eingeschaltet wird.
Liste	Gibt ein `OutputUnit` -Objekt mit `details` mit einer Liste von `OutputUnit` -Objekten mit den Behauptungen und Anmerkungen zurück. Beachten Sie, dass Anmerkungen standardmäßig nicht erfasst werden und dies aktiviert werden muss, da dies die Leistung beeinträchtigt wird.
Hierarchisch	Gibt ein `OutputUnit` -Objekt mit einer Hierarchie von `OutputUnit` -Objekten für den Bewertungspfad mit den Behauptungen und Anmerkungen zurück. Beachten Sie, dass Anmerkungen standardmäßig nicht erfasst werden und dies aktiviert werden muss, da dies die Leistung beeinträchtigt wird.

Das folgende Beispiel zeigt, wie das hierarchische Ausgangsformat mit Annotationssammlung und Berichterstattung eingeschaltet und ausgeschaltet wird.

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

Das Folgende ist die Stichprobenausgabe aus dem hierarchischen Format.

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

Konfiguration

Ausführungskonfiguration

Name	Beschreibung	Standardwert
`annotationCollectionEnabled`	Kontrolliert, ob Anmerkungen während der Verarbeitung gesammelt werden. Beachten Sie, dass das Sammeln von Anmerkungen beeinträchtigt wird.	`false`
`annotationCollectionFilter`	Das Prädikat, das verwendet wird, um für welches Schlüsselwort Anmerkungen sammeln und melden sollen. Dies erfordert, dass `annotationCollectionEnabled` für `true` ist.	`keyword -> false`
`locale`	Das Gebietsschema zum Generieren von Nachrichten im `ValidationMessage` . Beachten Sie, dass dieser Wert für jede Ausführung aus `SchemaValidatorsConfig` kopiert wird.	`Locale.getDefault()`
`failFast`	Ob ein Versagen sofort zurückgibt, wenn eine Behauptung erzeugt wird. Beachten Sie, dass dieser Wert für jede Ausführung aus `SchemaValidatorsConfig` kopiert wird, jedoch automatisch auf `true` für die Booleschen und Flag -Ausgabesformate eingestellt wird.	`false`
`formatAssertionsEnabled`	Der Standardwert besteht darin, Formataussagen von Entwurf 4 auf Entwurf 7 zu generieren und nur Annotationen aus dem Entwurf 2019-09 zu generieren. Die Einstellung auf `true` oder `false` wird das Standardverhalten überschreiben.	`null`
`debugEnabled`	Steuert, ob die Debug -Protokollierung für die Protokollierung der Knoteninformationen bei der Verarbeitung aktiviert ist. Beachten Sie, dass dies viele Protokolle generiert, die die Leistung beeinflussen.	`false`

Schema -Validatoren -Konfiguration

Name	Beschreibung	Standardwert
`applyDefaultsStrategy`	Die Strategie zur Anwendung von Standardeinstellungen beim Gehen beim Fehlen oder beim Nullknoten wird angetroffen.	`ApplyDefaultsStrategy.EMPTY_APPLY_DEFAULTS_STRATEGY`
`cacheRefs`	Ob die aus den Schiedsrichtern geladenen Schemata für nachfolgende Läufe zwischengespeichert und wiederverwendet werden. Wenn Sie dies auf `false` setzen, wird die Leistung beeinflusst, kann jedoch merkwürdig sein, um einen hohen Speicherverbrauch für den Cache zu verhindern, wenn mehrere verschachtelte Applikatoren wie `anyOf` `oneOf` und `allOf` verwendet werden.	`true`
`discriminatorKeywordEnabled`	Ob das Schlüsselwort `discriminator` gemäß OpenAPI 3 behandelt wird.	`false`
`errorMessageKeyword`	Das Schlüsselwort für benutzerdefinierte Fehlermeldungen im Schema. Wenn nicht festgelegt wird, ist diese Funktionen deaktiviert. Dies wird normalerweise auf `errorMessage` oder `message` eingestellt.	`null`
`executionContextCustomizer`	Dies kann verwendet werden, um den vom `JsonSchema` generierten `ExecutionContext` für jeden Validierungslauf anzupassen.	`null`
`failFast`	Ob ein Versagen sofort zurückgibt, wenn eine Behauptung erzeugt wird.	`false`
`formatAssertionsEnabled`	Der Standardwert besteht darin, Formataussagen von Entwurf 4 auf Entwurf 7 zu generieren und nur Annotationen aus dem Entwurf 2019-09 zu generieren. Die Einstellung auf `true` oder `false` wird das Standardverhalten überschreiben.	`null`
`javaSemantics`	Ob Java -Semantik für das Schlüsselwort `type` verwendet wird.	`false`
`locale`	Das Gebietsschema zum Generieren von Nachrichten im `ValidationMessage` .	`Locale.getDefault()`
`losslessNarrowing`	Ob eine verlustfreie Verengung für das Schlüsselwort `type` verwendet wird.	`false`
`messageSource`	Dies wird verwendet, um die spezifischen Gebietsschema -Nachrichten abzurufen.	`DefaultMessageSource.getInstance()`
`nullableKeywordEnabled`	Ob das `nullable` Schlüsselwort gemäß OpenAPI 3.0 behandelt wird. Dies wirkt sich auf die `enum` und `type` -Schlüsselwörter aus.	`false`
`pathType`	Der Pfadtyp für die Berichterstattung über den Instanzstandort und den Bewertungspfad. Setzen Sie auf `PathType.JSON_PATH` , um JSON Path zu verwenden.	`PathType.JSON_POINTER`
`preloadJsonSchema`	Ob das Schema vor der Verarbeitung von Eingaben vorinstalliert wird. Dies wird Speicher verwendet, aber die Ausführung der Validierung wird schneller sein.	`true`
`preloadJsonSchemaRefMaxNestingDepth`	Die maximale Tiefe des Bewertungsweges zum Vorladen beim Vorladen von Refs.	`40`
`readOnly`	Ob Schema nur gelesen wird. Dies wirkt sich auf das Keyword `readOnly` aus.	`null`
`regularExpressionFactory`	Die Fabrik, um regelmäßige Ausdrücke zu erstellen, beispielsweise `JoniRegularExpressionFactory` oder `GraalJSRegularExpressionFactory` . Dies erfordert, dass die Abhängigkeit manuell zum Projekt hinzugefügt wird, oder eine `ClassNotFoundException` wird geworfen.	`JDKRegularExpressionFactory.getInstance()`
`schemaIdValidator`	Dies wird verwendet, um anzupassen, wie die `$id` -Werte validiert werden. Beachten Sie, dass die Standardimplementierung nicht leere Fragmente ermöglicht, bei denen kein Basis-IRI angegeben ist und auch nicht absolute IRI `$id` -Werte im Stammschema ermöglicht.	`JsonSchemaIdValidator.DEFAULT`
`strict`	Dies ist festgelegt, ob Schlüsselwörter in ihrer Validierung streng sind. Was dies tut, hängt von den einzelnen Validatoren ab.
`typeLoose`	Ob Typen locker interpretiert werden. Wenn sie auf True gesetzt sind, kann ein einzelner Wert als Array der Größe 1 interpretiert werden. Saiten können auch als Zahl, Ganzzahl oder Boolesche interpretiert werden.	`false`
`writeOnly`	Ob Schema nur geschrieben wird. Dies wirkt sich auf das `writeOnly` aus.	`null`

Leistungsüberlegungen

Wenn die Bibliothek ein Schema aus der Schema -Fabrik erstellt, schafft sie für jeden Ort auf dem Bewertungspfad eine eigene Validatorinstanz. Dies bedeutet, dass für jeden Evaluierungspfad unterschiedliche Validatorinstanzen erstellt werden, wenn es unterschiedliche $ref gibt, die auf denselben Schema -Ort verweisen.

Wenn das Schema erstellt wird, wird die Bibliothek standardmäßig automatisch alle erforderlichen Validatoren aufladen und Referenzen auflösen. Dies kann mit der preloadJsonSchema -Option in der SchemaValidatorsConfig deaktiviert werden. Zu diesem Zeitpunkt werden keine Ausnahmen geworfen, wenn eine Referenz nicht gelöst werden kann. Wenn es zyklische Referenzen gibt, wird nur der erste Zyklus vorinstalliert. Wenn Sie sicherstellen möchten, dass Remote -Referenzen alle gelöst werden können, muss die initializeValidators -Methode auf das JsonSchema aufgerufen werden, das eine Ausnahme ausgelegt wird, wenn Referenzen nicht gelöst werden können.

Instanzen für JsonSchemaFactory und das aus der IT erstellte JsonSchema sind so konzipiert, dass die Konfiguration nicht geändert wird und zwischengespeichert und wiederverwendet werden sollte. Die Wiederverwendung des JsonSchema bedeutet, dass die Schema -Daten mit den erstellten Validatorinstanzen analysiert werden müssen und die Referenzen behoben werden müssen. Wenn Referenzen gelöst werden, werden die erstellten Validatoren zwischengespeichert. Bei Schemata mit tief verschachtelten Referenzen kann das für die Validatoren benötigte Speicher sehr hoch sein. In diesem Fall muss das Caching möglicherweise unter Verwendung der cacheRefs -Option im SchemaValidatorsConfig deaktiviert werden. Wenn Sie dies deaktivieren, müssen die Validatoren aus den Referenzen für jeden Validierungslauf neu erstellt werden, was sich auf die Leistung auswirkt.

Das Sammeln von Anmerkungen wirkt sich nachteilig auf die Validierungsleistung aus.

Die früheren Entwurfsspezifikationen enthalten weniger Schlüsselwörter, die möglicherweise die Leistung beeinflussen können. Beispielsweise löst die Verwendung des Schlüsselworts unevaluatedProperties oder unevaluatedItems in den zugehörigen Validatoren wie den properties oder items -Validatoren die Annotationssammlung aus.

Dies bedeutet nicht, dass die Verwendung eines Schemas mit einer späteren Entwurfsspezifikation automatisch eine Leistungswirkung verursacht. Beispielsweise führt der properties Validator Schecks durch, um festzustellen, ob Anmerkungen gesammelt werden müssen, und prüft, ob das Meta-Schema das Schlüsselwort unevaluatedProperties enthält und ob das Schlüsselwort unevaluatedProperties neben dem Bewertungspfad existiert.

Sicherheitsüberlegungen

Die Bibliothek geht davon aus, dass die geladenen Schemas vertrauenswürdig sind. Dieses Sicherheitsmodell geht davon aus, dass die Schemas mit der Anwendung auf dem Klassenpfad gebündelt sind.

Ausgabe	Beschreibung	Minderung
Schemabelastung	Die Bibliothek lädt standardmäßig Schemas vom Klassenpfad und über das Internet bei Bedarf.	Ein `DisallowSchemaLoader` kann so konfiguriert werden, dass das Schema -Abruf nicht zulässt. Alternativ kann eine `AllowSchemaLoader` konfiguriert werden, um die zulässigen Abruf -Iris einzuschränken.
Schema Caching	Die Bibliothek standardmäßig vorlädt und kann beim Ladenschemata verweist. Während es eine maximale Nisttiefe gibt, wenn Vorspannungsschemata ein Schema erstellt, das einen Lüfter enthält, der viel Speicher vom Server verbraucht.	Setzen Sie die Option `cacheRefs` in `SchemaValidatorsConfig` auf false.
Reguläre Ausdrücke	Die Bibliothek bestätigt nicht, ob ein bestimmter regulärer Ausdruck für die Ablehnung des Dienstes (Redos) anfällig ist.	Eine `AllowRegularExpressionFactory` kann so konfiguriert werden, dass die zulässige reguläre Ausdrücke die Validierung durchführen.
Validierungsfehler	Die Bibliothek versucht standardmäßig, alle Validierungsfehler zurückzugeben. Die Verwendung von Applikatoren wie `allOf` mit einer großen Anzahl von Schemata kann zu einer großen Anzahl von Validierungsfehlern führen, die Speicher aufnehmen.	Setzen Sie `failFast` Option in `SchemaValidatorsConfig` , um sofort zurückzukehren, wenn der erste Fehler auftritt. Die `OutputFormat.BOOLEAN` oder `OutputFormat.FLAG` kann auch verwendet werden.

Schneller Start

Anpassungsschema -Abruf

Anpassung von Meta-Schemas, Vokabeln, Schlüsselwörtern und Formaten

OpenAPI -Spezifikation

Validatoren

Konfiguration

Spezifikationsversion

YAML -Validierung

Sammlerkontext

JSON Schema Walkers und Walkuristener

Reguläre Ausdrücke

Benutzerdefinierte Fehlermeldungen

Mehrfachsprache

Metaschema -Validierung

Validierung von RFC 3339 Dauer

Projekte

Die Light-Rest-4J, die Light-Graphql-4J und die Light-Hybrid-4J verwenden diese Bibliothek, um die Anforderung und Antwort basierend auf den Spezifikationen zu validieren. Wenn Sie andere Frameworks wie Spring Boot verwenden, können Sie den OpenAPivalidator verwenden, einen generischen OpenAPI 3.0 -Validator, der auf der OpenAPI 3.0 -Spezifikation basiert.

Wenn Sie ein Projekt mit dieser Bibliothek haben, senden Sie bitte eine PR, um Ihr Projekt unten hinzuzufügen.

Mitwirkende

Vielen Dank an die folgenden Personen, die zu diesem Projekt beigetragen haben. Wenn Sie diese Bibliothek verwenden, erwägen Sie bitte einen Sponsor für einen der Mitwirkenden.

@stevehu

@Prashanth-Chaitanya

@fdutton

@VALFIRST

@Ballonwen

@JiACHEN1120

@ddobrin

@eskabetxe

@ehrmann

@Prashanthjos

@Subhajitdas298

@Fwiesner