Descarga json schema validator - Descargar código fuente json schema validator

Esta es una implementación de Java de la especificación JSON Schema Core Draft V4, V6, V7, V2019-09 y V2020-12 para la validación del esquema JSON. Esta implementación admite la personalización de meta-esquemas, vocabularios, palabras clave y formatos.

Además, la validación de solicitud/respuesta de OpenAPI 3 es compatible con el uso del meta-schema apropiado. Para los usuarios que desean recopilar información de un nodo JSON basado en el esquema, los Walkers pueden ayudar. El analizador JSON utilizado es el analizador Jackson. Como es un componente clave en nuestro marco de microservicios de luz-4J para validar la solicitud/respuesta contra la especificación de OpenAPI para el esquema Light-Rest-4J y RPC para Light-Hybrid-4J en tiempo de ejecución, el rendimiento es el aspecto más importante en el diseño.

Compatibilidad de la especificación del esquema JSON

La información sobre el soporte de compatibilidad para cada versión, incluidos los problemas conocidos, se puede encontrar en el documento de compatibilidad con las versiones de esquema JSON.

Desde el borrador 2019-09, la palabra clave format solo genera anotaciones por defecto y no genera afirmaciones.

Este comportamiento se puede anular para generar afirmaciones estableciendo el setFormatAssertionsEnabled en true en SchemaValidatorsConfig o ExecutionConfig .

Actualización a nuevas versiones

Esta biblioteca puede contener cambios de ruptura en las versiones de versión minor que pueden requerir cambios en el código.

La información sobre cambios notables o de ruptura al actualizar la biblioteca se puede encontrar en el documento de actualización al nuevo documento de versiones.

La página de versiones contendrá información sobre las últimas versiones.

Comparación con otras implementaciones

El proyecto de comparación de validación de esquema JSON de Creek tiene una comparación informativa de las implementaciones de validación de esquema basadas en JVM que compara las características funcionales y de rendimiento de varias implementaciones de Java diferentes.

Comparación funcional
Comparación de rendimiento

El proyecto Bowtie tiene un informe que compara las características funcionales de diferentes implementaciones, incluidas las implementaciones que no son Java, pero no realiza ninguna evaluación comparativa de rendimiento.

Por qué esta biblioteca

Actuación

Esta debería ser la implementación de validador de esquema Java JSON más rápida.

El siguiente es los resultados de referencia del proyecto de Validador de Validador JSON que utiliza el arnés Java Microbenchmark.

Tenga en cuenta que los resultados de referencia dependen en gran medida de las cargas y esquemas de trabajo de datos de entrada utilizados para la validación.

En este caso, esta carga de trabajo está utilizando la especificación de borrador 4 y prueba en gran medida el rendimiento de la palabra clave de evaluación properties . Puede consultar los resultados de la comparación de rendimiento de las implementaciones de validación de esquema JSON basadas en JVM para resultados de referencia para cargas de trabajo más típicas

Si el rendimiento es una consideración importante, las cargas de trabajo de muestra específicas deben compararse, ya que hay diferentes características de rendimiento cuando se utilizan ciertas palabras clave. Por ejemplo, el uso de las unevaluatedProperties o la palabra clave unevaluatedItems activará la recopilación de anotaciones en los validadores relacionados, como las properties o los validadores items , y la colección de anotaciones afectará negativamente el rendimiento.

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

Funcionalidad

Esta implementación se prueba contra la suite de prueba de esquema JSON. Como las pruebas se agregan continuamente a la suite, estos resultados de la prueba pueden no ser actuales.

Implementación	En general	Draft_03	Draft_04	Draft_06	Draft_07	Draft_2019_09	Draft_2020_12
Networknt	Pase: R: 4803 (100.0%) O: 2372 (100.0%) Fall: R: 0 (0.0%) O: 0 (0.0%)		Pase: R: 610 (100.0%) O: 251 (100.0%) Fall: R: 0 (0.0%) O: 0 (0.0%)	Pase: R: 822 (100.0%) O: 318 (100.0%) Fall: R: 0 (0.0%) O: 0 (0.0%)	Pase: R: 906 (100.0%) O: 541 (100.0%) Fall: R: 0 (0.0%) O: 0 (0.0%)	Pase: R: 1220 (100.0%) O: 625 (100.0%) Fall: R: 0 (0.0%) O: 0 (0.0%)	Pase: R: 1245 (100.0%) O: 637 (100.0%) Fall: R: 0 (0.0%) O: 0 (0.0%)

Tenga en cuenta que esto usa la JoniRegularExpressionFactory para las pruebas regex pattern y format .

Parser de Jackson

Esta biblioteca usa Jackson, que es un analizador Java JSON que se usa ampliamente en otros proyectos. Si ya está utilizando el analizador Jackson en su proyecto, es natural elegir esta biblioteca sobre otros para la validación de esquemas.

Soporte YAML

La biblioteca funciona con JSON y YAML tanto en definiciones de esquema como en datos de entrada.

Soporte de OpenAPI

La especificación OpenAPI 3.0 está utilizando el esquema JSON para validar la solicitud/respuesta, pero hay algunas diferencias. Con un archivo de configuración, puede habilitar que la biblioteca funcione con la validación de OpenAPI 3.0.

Dependencias mínimas

Siguiendo el principio de diseño de la plataforma de luz, esta biblioteca tiene dependencias mínimas para garantizar que no haya conflictos de dependencia al usarla.

Dependencias requeridas

Las siguientes son las dependencias que se incluirán automáticamente cuando se incluya esta biblioteca.

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

Dependencias opcionales

Las siguientes son las dependencias opcionales que pueden ser necesarias para ciertas opciones.

Estos no se incluyen automáticamente y la configuración de la opción relevante sin agregar la biblioteca dará como resultado una 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 >

Dependencias excluibles

Las siguientes son dependencias requeridas que se incluyen automáticamente, pero pueden excluirse explícitamente si no son necesarias.

La dependencia de YAML puede excluirse si esto no es necesario. Intentar procesar esquemas o entrada que sean YAML dará como resultado una 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 >

La dependencia del tiempo ETHLO puede excluirse si no se requiere una validación precisa del formato date-time . El formato date-time usará java.time.OffsetDateTime para determinar si la date-time es válida.

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

Comunidad

Esta biblioteca es muy activa con muchos contribuyentes. Los miembros del equipo manejan rápidamente las nuevas características y correcciones de errores. Debido a que es una dependencia esencial del marco Light-4J en la misma organización GitHub, se evolucionará y mantendrá junto con el marco.

Requisito previo

La biblioteca admite Java 8 y más. Si desea construir desde el código fuente, debe instalar JDK 8 localmente. Para admitir una versión múltiple de JDK, puede usar sdkman

Uso

Agregar la dependencia

Este paquete está disponible en 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' );
}

Validando entradas contra un esquema

El siguiente ejemplo demuestra cómo se validan las entradas contra un esquema. Comprende los siguientes pasos.

Crear una fábrica de esquema con el dialecto de esquema predeterminado y cómo se pueden recuperar los esquemas.
- Configuración de la asignación de $id a un URI de recuperación utilizando schemaMappers .
- Configuración de cómo se cargan los esquemas utilizando el URI de recuperación utilizando schemaLoaders . Por ejemplo, un Map<String, String> schemas que contienen una asignación de URI de recuperación a los datos del esquema como una String configurada utilizando builder.schemaLoaders(schemaLoaders -> schemaLoaders.schemas(schemas)) . Esto también acepta una Function<String, String> schemaRetrievalFunction .
Creación de una configuración para controlar el comportamiento del validador.
Carga de un esquema desde una ubicación de esquema junto con la configuración de validador.
Uso del esquema para validar los datos junto con la configuración de cualquier configuración específica de ejecución, como por ejemplo, la ubicación o si las afirmaciones de formato están habilitados.

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

Validando un esquema contra un meta-schema

El siguiente ejemplo demuestra cómo se valida un esquema contra un meta-esquema.

Esto es en realidad lo mismo que validar las entradas contra un esquema, excepto en este caso, la entrada es el esquema y el esquema utilizado es el meta-esquema.

Tenga en cuenta que los meta-esquemas para el draft 4, el draft 6, el draft 7, el draft 2019-09 y el draft 2020-12 se agrupan con la biblioteca y estos recursos de classpath se utilizarán de manera predeterminada.

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

Resultados y formatos de salida

Resultados

Los siguientes tipos de resultados son generados por la biblioteca.

Tipo Descripción

Afirmaciones Errores de validación generados por una palabra clave en una instancia de datos de entrada particular. Esto generalmente se describe en una ValidationMessage o en una OutputUnit . Tenga en cuenta que desde el borrador 2019-09, la palabra clave format ya no genera afirmaciones de forma predeterminada y, en su lugar, genera solo anotaciones a menos que se configuren de lo contrario usando una opción de configuración o utilizando un meta-schema que usa el vocabulario apropiado.

Anotaciones Información adicional generada por una palabra clave para una instancia de datos de entrada particular. Esto generalmente se describe en una OutputUnit . La recopilación y los informes de anotación se desactivan de forma predeterminada. Las anotaciones requeridas por palabras clave, como unevaluatedProperties o unevaluatedItems siempre se recopilan para fines de evaluación y no se pueden deshabilitar, pero no se informarán a menos que se configure para hacerlo.

Tipo	Descripción
Afirmaciones	Errores de validación generados por una palabra clave en una instancia de datos de entrada particular. Esto generalmente se describe en una `ValidationMessage` o en una `OutputUnit` . Tenga en cuenta que desde el borrador 2019-09, la palabra clave `format` ya no genera afirmaciones de forma predeterminada y, en su lugar, genera solo anotaciones a menos que se configuren de lo contrario usando una opción de configuración o utilizando un meta-schema que usa el vocabulario apropiado.
Anotaciones	Información adicional generada por una palabra clave para una instancia de datos de entrada particular. Esto generalmente se describe en una `OutputUnit` . La recopilación y los informes de anotación se desactivan de forma predeterminada. Las anotaciones requeridas por palabras clave, como `unevaluatedProperties` o `unevaluatedItems` siempre se recopilan para fines de evaluación y no se pueden deshabilitar, pero no se informarán a menos que se configure para hacerlo.

La siguiente información se utiliza para describir ambos tipos de resultados.

Tipo	Descripción
Ruta de evaluación	Este es el conjunto de claves desde la raíz a través del cual pasa la evaluación para llegar al esquema para evaluar la instancia. Esto incluye `$ref` y `$dynamicRef` . p.ej. `/properties/bar/$ref/properties/bar-prop`
Ubicación de esquema	Este es el IRI canónico del esquema más el fragmento JSON Pointer al esquema que se utilizó para evaluar la instancia. p.ej. `https://json-schema.org/schemas/example#/$defs/bar/properties/bar-prop`
Ubicación de instancia	Este es el fragmento JSON Pointer a los datos de la instancia que se estaban evaluando. p.ej. `/bar/bar-prop`

Las afirmaciones contienen la siguiente información adicional

Tipo	Descripción
Mensaje	El mensaje de error de validación.
Código	El código de error.
Clave de mensaje	La clave de mensaje utilizada para generar el mensaje para la localización.
Argumentos	Los argumentos utilizados para generar el mensaje.
Tipo	La palabra clave que generó el mensaje.
Propiedad	El nombre de la propiedad que causó el error de validación, por ejemplo, para la palabra clave `required` . Tenga en cuenta que esto no es parte de la ubicación de la instancia, ya que eso apunta al nodo de instancia.
Nodo de esquema	El `JsonNode` señaló por la ubicación del esquema. Estos son los datos de esquema que causaron que los datos de entrada fallaran. Es posible obtener la información de ubicación configurando la `JsonSchemaFactory` con un `JsonNodeReader` que usa la `LocationJsonNodeFactoryFactory` JSONNodeFactoryFactory y utilizando `JsonNodes.tokenLocationOf(schemaNode)` .
Nodo de instancia	El `JsonNode` señaló por la ubicación de la instancia. Estos son los datos de entrada que fallaron la validación. Es posible obtener la información de ubicación configurando la `JsonSchemaFactory` con un `JsonNodeReader` que usa la `LocationJsonNodeFactoryFactory` JSONNodeFactoryFactory y usando `JsonNodes.tokenLocationOf(instanceNode)` .
Error	El error.
Detalles	Detalles adicionales que se pueden establecer mediante implementaciones de validador de palabras clave personalizadas. Esto no es utilizado por la biblioteca.

Las anotaciones contienen la siguiente información adicional

Tipo	Descripción
Valor	El valor de anotación generado

Información de línea y columna

La biblioteca se puede configurar para almacenar información de línea y columna en las instancias JsonNode para los nodos de instancia y esquema. Esto afectará negativamente el rendimiento y no está configurado de forma predeterminada.

Esto se hace configurando un JsonNodeReader que usa la LocationJsonNodeFactoryFactory en JsonSchemaFactory . La información JsonLocation se puede recuperar utilizando 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 ());

Formatos de salida

Esta biblioteca implementa el indicador, la lista y los formatos de salida jerárquicos definidos en la especificación para la salida legible por máquina para la validación y anotación del esquema JSON.

La lista y los formatos de salida jerárquicos son particularmente útiles para comprender cómo llegó el sistema a un resultado particular.

Formato de salida	Descripción
Por defecto	Genera la lista de afirmaciones.
Booleano	Devuelve `true` si la validación es exitosa. Tenga en cuenta que la opción Fail Fast se enciende de forma predeterminada para este formato de salida.
Bandera	Devuelve un objeto `OutputFlag` con `valid` tener `true` si la validación es exitosa. Tenga en cuenta que la opción Fail Fast se enciende de forma predeterminada para este formato de salida.
Lista	Devuelve un objeto `OutputUnit` con `details` con una lista de objetos `OutputUnit` con las afirmaciones y anotaciones. Tenga en cuenta que las anotaciones no se recopilan de manera predeterminada y debe habilitarse, ya que afectará el rendimiento.
Jerárquico	Devuelve un objeto `OutputUnit` con una jerarquía de objetos `OutputUnit` para la ruta de evaluación con las afirmaciones y anotaciones. Tenga en cuenta que las anotaciones no se recopilan de manera predeterminada y debe habilitarse, ya que afectará el rendimiento.

El siguiente ejemplo muestra cómo generar el formato de salida jerárquico con la recopilación de anotaciones y los informes activados y las afirmaciones de formato activadas.

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

La siguiente es la salida de muestra del formato jerárquico.

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

Configuración

Configuración de ejecución

Nombre	Descripción	Valor predeterminado
`annotationCollectionEnabled`	Controla si las anotaciones se recopilan durante el procesamiento. Tenga en cuenta que la recopilación de anotaciones afectará negativamente el rendimiento.	`false`
`annotationCollectionFilter`	El predicado utilizado para controlar qué palabra clave recopilar e informar anotaciones. Esto requiere `annotationCollectionEnabled` para ser `true` .	`keyword -> false`
`locale`	La configuración regional para generar mensajes en el `ValidationMessage` . Tenga en cuenta que este valor se copia de `SchemaValidatorsConfig` para cada ejecución.	`Locale.getDefault()`
`failFast`	Si se debe devolver la falla inmediatamente cuando se genera una afirmación. Tenga en cuenta que este valor se copia de `SchemaValidatorsConfig` para cada ejecución, pero se establece automáticamente en `true` para los formatos de salida booleanos y de indicador.	`false`
`formatAssertionsEnabled`	El valor predeterminado es generar afirmaciones de formato del borrador 4 al borrador 7 y solo generar anotaciones del borrador 2019-09. La configuración en `true` o `false` anulará el comportamiento predeterminado.	`null`
`debugEnabled`	Controla si el registro de depuración está habilitado para registrar la información del nodo al procesar. Tenga en cuenta que esto generará muchos registros que afectarán el rendimiento.	`false`

Configuración de validadores de esquema

Nombre	Descripción	Valor predeterminado
`applyDefaultsStrategy`	La estrategia para aplicar los valores predeterminados al caminar cuando faltan o nodos nulos se encuentran.	`ApplyDefaultsStrategy.EMPTY_APPLY_DEFAULTS_STRATEGY`
`cacheRefs`	Si los esquemas cargados de las referencias se almacenarán en caché y se reutilizarán para las ejecuciones posteriores. Establecer esto en `false` afectará el rendimiento, pero puede ser necesario para evitar un alto uso de la memoria para el caché si se utilizan múltiples aplicadores anidados como `anyOf` , `oneOf` y `allOf` .	`true`
`discriminatorKeywordEnabled`	Si la palabra clave `discriminator` se maneja de acuerdo con OpenAPI 3.	`false`
`errorMessageKeyword`	La palabra clave para usar para mensajes de error personalizados en el esquema. Si no establece, estas características están deshabilitadas. Esto generalmente se establece en `errorMessage` o `message` .	`null`
`executionContextCustomizer`	Esto se puede utilizar para personalizar el `ExecutionContext` generado por `JsonSchema` para cada ejecución de validación.	`null`
`failFast`	Si se debe devolver la falla inmediatamente cuando se genera una afirmación.	`false`
`formatAssertionsEnabled`	El valor predeterminado es generar afirmaciones de formato del borrador 4 al borrador 7 y solo generar anotaciones del borrador 2019-09. La configuración en `true` o `false` anulará el comportamiento predeterminado.	`null`
`javaSemantics`	Si Java Semantics se usa para la palabra clave `type` .	`false`
`locale`	La configuración regional para generar mensajes en el `ValidationMessage` .	`Locale.getDefault()`
`losslessNarrowing`	Si el estrechamiento sin pérdidas se usa para la palabra clave `type` .	`false`
`messageSource`	Esto se utiliza para recuperar los mensajes específicos de la configuración regional.	`DefaultMessageSource.getInstance()`
`nullableKeywordEnabled`	Si la palabra clave `nullable` se maneja de acuerdo con OpenAPI 3.0. Esto afecta las palabras clave `enum` y `type` .	`false`
`pathType`	El tipo de ruta a usar para informar la ubicación de la instancia y la ruta de evaluación. Establecer en `PathType.JSON_PATH` para usar la ruta JSON.	`PathType.JSON_POINTER`
`preloadJsonSchema`	Si el esquema se precarga antes de procesar cualquier entrada. Esto usará la memoria, pero la ejecución de la validación será más rápida.	`true`
`preloadJsonSchemaRefMaxNestingDepth`	La profundidad máxima de la ruta de evaluación para precargar al precargar las referencias.	`40`
`readOnly`	Si el esquema se lee solo. Esto afecta la palabra clave `readOnly` .	`null`
`regularExpressionFactory`	La fábrica para usar para crear expresiones regulares, por ejemplo, `JoniRegularExpressionFactory` o `GraalJSRegularExpressionFactory` . Esto requiere que la dependencia se agregue manualmente al proyecto o se lanzará una `ClassNotFoundException` .	`JDKRegularExpressionFactory.getInstance()`
`schemaIdValidator`	Esto se usa para personalizar cómo se validan los valores `$id` . Tenga en cuenta que la implementación predeterminada permite fragmentos no vacíos en los que no se especifica IRI base y también permite valores de ID IRI `$id` no absoltos en el esquema raíz.	`JsonSchemaIdValidator.DEFAULT`
`strict`	Esto se establece si las palabras clave son estrictas en su validación. Lo que esto hace depende de los validadores individuales.
`typeLoose`	Si los tipos se interpretan de manera floja. Si se establece en True, un solo valor puede interpretarse como una matriz de tamaño 1. Las cadenas también pueden interpretarse como número, entero o booleano.	`false`
`writeOnly`	Si el esquema es solo escribir. Esto afecta la palabra clave `writeOnly` .	`null`

Consideraciones de rendimiento

Cuando la biblioteca crea un esquema de la fábrica de esquemas, crea una instancia de validador distinta para cada ubicación en la ruta de evaluación. Esto significa que si hay diferentes $ref que hacen referencia a la misma ubicación del esquema, se crean diferentes instancias de validador para cada ruta de evaluación.

Cuando se crea el esquema, la biblioteca, por defecto, precarga automáticamente todos los validadores necesarios y resolverá referencias. Esto se puede deshabilitar con la opción preloadJsonSchema en el SchemaValidatorsConfig . En este punto, no se lanzarán excepciones si no se puede resolver una referencia. Si hay referencias que son cíclicas, solo el primer ciclo será precargado. Si desea asegurarse de que todas las referencias remotas se puedan resolver, el método initializeValidators debe llamarse en JsonSchema que lanzará una excepción si hay referencias que no se pueden resolver.

Las instancias para JsonSchemaFactory y el JsonSchema creado a partir de él están diseñados para ser seguros, siempre que su configuración no esté modificada y debe almacenarse en caché y reutilización. No reutilizar el JsonSchema significa que los datos del esquema deben repetirse con las instancias de validador creadas y las referencias resueltas. Cuando se resuelven referencias, los validadores creados serán almacenados en caché. Para los esquemas que tienen referencias profundamente anidadas, la memoria necesaria para los validadores puede ser muy alta, en cuyo caso el almacenamiento en caché puede necesitar deshabilitarse utilizando la opción cacheRefs en el SchemaValidatorsConfig . Deshabilitar esto significará que los validadores de las referencias deben recrearse para cada ejecución de validación que afectará el rendimiento.

La recolección de anotaciones afectará negativamente el rendimiento de la validación.

Las especificaciones del borrador anterior contienen menos palabras clave que pueden afectar el rendimiento. Por ejemplo, el uso de la palabra clave unevaluatedProperties o unevaluatedItems activará la recopilación de anotaciones en los validadores relacionados, como los validadores properties o items .

Esto no significa que el uso de un esquema con un borrador de especificación posterior causará automáticamente un impacto en el rendimiento. Por ejemplo, el validador properties realizará verificaciones para determinar si las anotaciones deben ser recolectadas, y verifica si el meta-schema contiene la palabra clave unevaluatedProperties y si la palabra clave unevaluatedProperties existe adyacente la ruta de evaluación.

Consideraciones de seguridad

La biblioteca asume que se confía en los esquemas que se están cargando. Este modelo de seguridad asume el caso de uso en el que los esquemas se agrupan con la aplicación en el ClassPath.

Asunto	Descripción	Mitigación
Carga de esquema	La biblioteca de forma predeterminada cargará esquemas de classpath y a través de Internet si es necesario.	Se puede configurar un `DisallowSchemaLoader` para no permitir la recuperación del esquema. Alternativamente, se puede configurar un `AllowSchemaLoader` para restringir el iris de recuperación que se permite.
Almacenamiento en caché del esquema	La biblioteca, por defecto, las referencias de precarga y caché al cargar esquemas. Si bien hay una profundidad de anidación máxima al precargar esquemas, todavía es posible construir un esquema que tenga un ventilador que consuma mucha memoria del servidor.	Establecer la opción `cacheRefs` en `SchemaValidatorsConfig` a False.
Expresiones regulares	La biblioteca no valida si una expresión regular dada es susceptible a la denegación de servicio (redos).	Se puede configurar un `AllowRegularExpressionFactory` para realizar la validación en las expresiones regulares que están permitidas.
Errores de validación	La biblioteca por defecto intenta devolver todos los errores de validación. El uso de aplicadores como `allOf` con una gran cantidad de esquemas puede dar lugar a una gran cantidad de errores de validación que toman memoria.	Establezca la opción `failFast` en `SchemaValidatorsConfig` para regresar inmediatamente cuando se encuentre el primer error. `OutputFormat.BOOLEAN` o `OutputFormat.FLAG` también se puede usar.

Comienzo rápido

Personalización de recuperación de esquema

Personalización de metaetemas, vocabularios, palabras clave y formatos

Especificación de OpenAPI

Validador

Configuración

Versión de especificación

Validación de Yaml

Contexto coleccionista

JSON Schema Walkers y Walkeners

Expresiones regulares

Mensajes de error personalizados

Lenguaje múltiple

Validación de Metaschema

Validación de duraciones RFC 3339

Proyectos

El Light-Rest-4J, Light-GraphQL-4J y Light-Hybrid-4J usan esta biblioteca para validar la solicitud y la respuesta en función de las especificaciones. Si está utilizando otros marcos como Spring Boot, puede usar OpenApivalidator, un validador genérico de OpenAPI 3.0 basado en la especificación OpenAPI 3.0.

Si tiene un proyecto que usa esta biblioteca, envíe un PR para agregar su proyecto a continuación.

Colaboradores

Gracias a las siguientes personas que han contribuido a este proyecto. Si está utilizando esta biblioteca, considere ser patrocinador de uno de los contribuyentes.

@stevehu

@Prashanth-Chaitanya

@fdutton

@valfirst

@Balloonwen

@jiachen1120

@Ddobrin

@eskabetxe

@ehrmann

@Prashanthjos

@Subhajitdas298

@Fwiesner