Module org.leadpony.justify
Package org.leadpony.justify.api

Interface JsonSchemaBuilder

  • public interface JsonSchemaBuilder
    A builder interface for building a JSON schema programmatically.

    Instances of this type can be created by the factory class JsonSchemaBuilderFactory.

    The following code sample shows how to build a JSON schema using this builder. 

     
 JsonValidationService service = JsonValidationService.newInstance();
 JsonSchemaBuilderFactory factory = service.createSchemaBuilderFactory();
 JsonSchemaBuilder builder = factory.createBuilder();
 JsonSchema schema = builder
         .withType(InstanceType.OBJECT)
         .withProperty("firstName",
             factory.createBuilder().withType(InstanceType.STRING).build())
         .withProperty("lastName",
             factory.createBuilder().withType(InstanceType.STRING).build())
         .withProperty("age",
             factory.createBuilder()
                 .withType(InstanceType.INTEGER)
                 .withMinimum(0)
                 .build())
         .withRequired("firstName", "lastName")
         .build();

    For more information about the keywords composing the JSON schema, please see JSON Schema Specification.

    Each instance of this type is NOT safe for use by multiple concurrent threads.

    Author:
    leadpony
    See Also:
    JSON Schema Specification

    • Method Detail

      • withId

        JsonSchemaBuilder withId​(URI id)
        Adds a "$id" keyword to the schema.
        Parameters:
        id - the identifier of the schema.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified id is null.

      • withSchema

        JsonSchemaBuilder withSchema​(URI schema)
        Adds a "$schema" keyword to the schema.

        The "$schema" keyword should be used in a root schema. It must not appear in subschemas.

        Parameters:
        schema - the version identifier of the schema.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified schema is null.

      • withComment

        JsonSchemaBuilder withComment​(String comment)
        Adds a "$comment" keyword to the schema.
        Parameters:
        comment - the comment for the schema.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified comment is null.

      • withType

        JsonSchemaBuilder withType​(InstanceType... types)
        Adds a "type" keyword to the schema. The type are specified as an array.
        Parameters:
        types - the array of types. At least one element is needed and elements must be unique.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified types is null.
        IllegalArgumentException - if the specified types is empty, or some types are not unique.

      • withEnum

        JsonSchemaBuilder withEnum​(JsonValue... values)
        Adds an "enum" keyword to the schema. The values are specified as an array.
        Parameters:
        values - the values in the enumeration. At least one element is needed and elements must be unique.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified values is null.
        IllegalArgumentException - if the specified values is empty. or some values are not unique.

      • withEnum

        JsonSchemaBuilder withEnum​(Set<JsonValue> values)
        Adds an "enum" keyword to the schema. The values are specified as a set.
        Parameters:
        values - the values in the enumeration. At least one element is needed.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified values is null.
        IllegalArgumentException - if the specified values is empty.

      • withConst

        JsonSchemaBuilder withConst​(JsonValue value)
        Adds a "const" keyword to the schema.
        Parameters:
        value - the value of the keyword.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified value is null.

      • withMultipleOf

        JsonSchemaBuilder withMultipleOf​(long value)
        Adds a "multipleOf" keyword to the schema. The value is specified as long type.
        Parameters:
        value - the value of the keyword. This must be greater than 0.
        Returns:
        this builder.
        Throws:
        IllegalArgumentException - if the specified value is not greater than 0.

      • withMultipleOf

        JsonSchemaBuilder withMultipleOf​(double value)
        Adds a "multipleOf" keyword to the schema. The value is specified as double type.
        Parameters:
        value - the value of the keyword. This must be greater than 0.
        Returns:
        this builder.
        Throws:
        IllegalArgumentException - if the specified value is not greater than 0.

      • withMaximum

        default JsonSchemaBuilder withMaximum​(long value)
        Adds a "maximum" keyword to the schema. The value is specified as long type.

        This keyword specifies an inclusive upper limit for a numeric instance.

        Parameters:
        value - the value of the keyword.
        Returns:
        this builder.

      • withMaximum

        default JsonSchemaBuilder withMaximum​(double value)
        Adds a "maximum" keyword to the schema. The value is specified as double type.

        This keyword specifies an inclusive upper limit for a numeric instance.

        Parameters:
        value - the value of the keyword.
        Returns:
        this builder.

      • withMaximum

        JsonSchemaBuilder withMaximum​(BigDecimal value)
        Adds a "maximum" keyword to the schema. The value is specified as BigDecimal type.

        This keyword specifies an inclusive upper limit for a numeric instance.

        Parameters:
        value - the value of the keyword.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified value is null.

      • withExclusiveMaximum

        default JsonSchemaBuilder withExclusiveMaximum​(long value)
        Adds an "exclusiveMaximum" keyword to the schema. The value is specified as long type.

        This keyword specifies an exclusive upper limit for a numeric instance.

        Parameters:
        value - the value of the keyword.
        Returns:
        this builder.

      • withExclusiveMaximum

        default JsonSchemaBuilder withExclusiveMaximum​(double value)
        Adds an "exclusiveMaximum" keyword to the schema. The value is specified as double type.

        This keyword specifies an exclusive upper limit for a numeric instance.

        Parameters:
        value - the value of the keyword.
        Returns:
        this builder.

      • withExclusiveMaximum

        JsonSchemaBuilder withExclusiveMaximum​(BigDecimal value)
        Adds an "exclusiveMaximum" keyword to the schema. The value is specified as BigDecimal type.

        This keyword specifies an exclusive upper limit for a numeric instance.

        Parameters:
        value - the value of the keyword.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified value is null.

      • withMinimum

        default JsonSchemaBuilder withMinimum​(long value)
        Adds a "minimum" keyword to the schema. The value is specified as long type.

        This keyword specifies an inclusive lower limit for a numeric instance.

        Parameters:
        value - the value of the keyword.
        Returns:
        this builder.

      • withMinimum

        default JsonSchemaBuilder withMinimum​(double value)
        Adds a "minimum" keyword to the schema. The value is specified as double type.

        This keyword specifies an inclusive lower limit for a numeric instance.

        Parameters:
        value - the value of the keyword.
        Returns:
        this builder.

      • withMinimum

        JsonSchemaBuilder withMinimum​(BigDecimal value)
        Adds a "minimum" keyword to the schema. The value is specified as BigDecimal type.

        This keyword specifies an inclusive lower limit for a numeric instance.

        Parameters:
        value - the value of the keyword.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified value is null.

      • withExclusiveMinimum

        default JsonSchemaBuilder withExclusiveMinimum​(long value)
        Adds an "exclusiveMinimum" keyword to the schema. The value is specified as long type.

        This keyword specifies an exclusive lower limit for a numeric instance.

        Parameters:
        value - the value of the keyword.
        Returns:
        this builder.

      • withExclusiveMinimum

        default JsonSchemaBuilder withExclusiveMinimum​(double value)
        Adds an "exclusiveMinimum" keyword to the schema. The value is specified as double type.

        This keyword specifies an exclusive lower limit for a numeric instance.

        Parameters:
        value - the value of the keyword.
        Returns:
        this builder.

      • withExclusiveMinimum

        JsonSchemaBuilder withExclusiveMinimum​(BigDecimal value)
        Adds an "exclusiveMinimum" keyword to the schema. The value is specified as BigDecimal type.

        This keyword specifies an exclusive lower limit for a numeric instance.

        Parameters:
        value - the value of the keyword.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified value is null.

      • withMaxLength

        JsonSchemaBuilder withMaxLength​(int value)
        Adds a "maxLength" keyword to the schema.

        This keyword specifies an upper limit of length for a string instance.

        Parameters:
        value - the value of the keyword. This must be a non-negative integer.
        Returns:
        this builder.
        Throws:
        IllegalArgumentException - if the specified value is negative.

      • withMinLength

        JsonSchemaBuilder withMinLength​(int value)
        Adds a "minLength" keyword to the schema.

        This keyword specifies a lower limit of length for a string instance.

        Parameters:
        value - the value of the keyword. This must be a non-negative integer.
        Returns:
        this builder.
        Throws:
        IllegalArgumentException - if the specified value is negative.

      • withPattern

        JsonSchemaBuilder withPattern​(String pattern)
        Adds a "pattern" keyword to the schema.

        This keyword specifies the pattern of string instance as a regular expression.

        Parameters:
        pattern - the regular expression which will be tested against a string instance.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified pattern is null.
        java.util.regex.PatternSyntaxException - if the specified pattern is not a valid regular expression.

      • withItems

        JsonSchemaBuilder withItems​(JsonSchema subschema)
        Adds an "items" keyword to the schema. The specified single subschema is used for all array items.
        Parameters:
        subschema - the subschema as the value of the keyword.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified subschema is null.

      • withItemsArray

        JsonSchemaBuilder withItemsArray​(JsonSchema... subschemas)
        Adds an "items" keyword to the schema. The value is specified as an array of subschemas.
        Parameters:
        subschemas - the array of subschemas as the value of the keyword. At least one element is needed.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified subschemas is null.
        IllegalArgumentException - if the specified subschemas is empty.

      • withItemsArray

        JsonSchemaBuilder withItemsArray​(List<JsonSchema> subschemas)
        Adds an "items" keyword to the schema. The value is specified as an ordered list of subschemas.
        Parameters:
        subschemas - the list of subschemas as the value of the keyword. At least one element is needed.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified subschemas is null.
        IllegalArgumentException - if the specified subschemas is empty.

      • withAdditionalItems

        JsonSchemaBuilder withAdditionalItems​(JsonSchema subschema)
        Adds an "additionalItems" keyword to the schema.
        Parameters:
        subschema - the value of the keyword.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified subschema is null.

      • withMaxItems

        JsonSchemaBuilder withMaxItems​(int value)
        Adds a "maxItems" keyword to the schema.
        Parameters:
        value - the value of the keyword. This must be a non-negative integer.
        Returns:
        this builder.
        Throws:
        IllegalArgumentException - if the specified value is negative.

      • withMinItems

        JsonSchemaBuilder withMinItems​(int value)
        Adds a "minItems" keyword to the schema.
        Parameters:
        value - the value of the keyword. This must be a non-negative integer.
        Returns:
        this builder.
        Throws:
        IllegalArgumentException - if the specified value is negative.

      • withUniqueItems

        JsonSchemaBuilder withUniqueItems​(boolean unique)
        Adds a "uniqueItems" keyword to the schema.

        This keyword specifies whether elements in the array should be unique or not.

        Parameters:
        unique - the value of the keyword.
        Returns:
        this builder.

      • withContains

        JsonSchemaBuilder withContains​(JsonSchema subschema)
        Adds a "contains" keyword to the schema.
        Parameters:
        subschema - the value of the keyword.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified subschema is null.

      • withMaxContains

        JsonSchemaBuilder withMaxContains​(int value)
        Adds a "maxContains" keyword to the schema.
        Parameters:
        value - the value of the keyword. This must be a non-negative integer.
        Returns:
        this builder.
        Throws:
        IllegalArgumentException - if the specified value is negative.
        Since:
        draft-08

      • withMinContains

        JsonSchemaBuilder withMinContains​(int value)
        Adds a "minContains" keyword to the schema.
        Parameters:
        value - the value of the keyword. This must be a non-negative integer.
        Returns:
        this builder.
        Throws:
        IllegalArgumentException - if the specified value is negative.
        Since:
        draft-08

      • withMaxProperties

        JsonSchemaBuilder withMaxProperties​(int value)
        Adds a "maxProperties" keyword to the schema.
        Parameters:
        value - the value of the keyword. This must be a non-negative integer.
        Returns:
        this builder.
        Throws:
        IllegalArgumentException - if the specified value is negative.

      • withMinProperties

        JsonSchemaBuilder withMinProperties​(int value)
        Adds a "minProperties" keyword to the schema.
        Parameters:
        value - the value of the keyword. This must be a non-negative integer.
        Returns:
        this builder.
        Throws:
        IllegalArgumentException - if the specified value is negative.

      • withRequired

        JsonSchemaBuilder withRequired​(String... names)
        Adds a "required" keyword to the schema.

        This keyword specifies the required properties in an object.

        Parameters:
        names - the value of the keyword. The names must be unique.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified names is null.
        IllegalArgumentException - if the specified values are not unique.

      • withRequired

        JsonSchemaBuilder withRequired​(Set<String> names)
        Adds a "required" keyword to the schema.

        This keyword specifies the required properties in an object.

        Parameters:
        names - the value of the keyword.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified names is null.

      • withProperty

        JsonSchemaBuilder withProperty​(String name,
                               JsonSchema subschema)
        Adds an entry of the "properties" keyword to the schema.
        Parameters:
        name - the name of the property.
        subschema - the subschema for the property.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified name or subschema is null.

      • withProperties

        JsonSchemaBuilder withProperties​(Map<String,​JsonSchema> subschemas)
        Adds a "properties" keyword to the schema.
        Parameters:
        subschemas - the object mapping a property name to a subschema.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified subschemas is null.

      • withPatternProperty

        JsonSchemaBuilder withPatternProperty​(String pattern,
                                      JsonSchema subschema)
        Adds an entry of the "patternProperties" keyword to the schema.
        Parameters:
        pattern - the name pattern the property.
        subschema - the subschema for the property.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified pattern or subschema is null.
        java.util.regex.PatternSyntaxException - if the specified pattern is not a valid regular expression.

      • withPatternProperties

        JsonSchemaBuilder withPatternProperties​(Map<String,​JsonSchema> subschemas)
        Adds a "patternProperties" keyword to the schema.
        Parameters:
        subschemas - the object mapping a name pattern to a subschema.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified subschemas is null.
        java.util.regex.PatternSyntaxException - if any pattern is not a valid regular expression.

      • withAdditionalProperties

        JsonSchemaBuilder withAdditionalProperties​(JsonSchema subschema)
        Adds an "additionalProperties" keyword to the schema.
        Parameters:
        subschema - the value of the keyword.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified subschema is null.

      • withDependency

        JsonSchemaBuilder withDependency​(String name,
                                 JsonSchema subschema)
        Adds an entry of the "dependencies" keyword to the schema.
        Parameters:
        name - the name of the dependency property.
        subschema - the schema to be evaluated against the entire object.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified name or subschema is null.

      • withDependency

        JsonSchemaBuilder withDependency​(String name,
                                 String... requiredProperties)
        Adds an entry of the "dependencies" keyword to the schema.
        Parameters:
        name - the name of the dependency property.
        requiredProperties - the required properties in the object.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified name or requiredProperties is null.
        IllegalArgumentException - if any element in requiredProperties is not unique.

      • withDependency

        JsonSchemaBuilder withDependency​(String name,
                                 Set<String> requiredProperties)
        Adds an entry of the "dependencies" keyword to the schema.
        Parameters:
        name - the name of the dependency property.
        requiredProperties - the required properties in the object.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified name or requiredProperties is null.

      • withDependencies

        JsonSchemaBuilder withDependencies​(Map<String,​?> values)
        Adds a "dependencies" keyword to the schema.
        Parameters:
        values - the object mapping a property name to a value. Each value of the map must be a JsonSchema or a Set<String>.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified values is null.
        ClassCastException - if any value of the map is of unexpected type.

      • withPropertyNames

        JsonSchemaBuilder withPropertyNames​(JsonSchema subschema)
        Adds a "propertyNames" keyword to the schema.
        Parameters:
        subschema - the subschema to be evaluated against all property names in an object.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified subschema is null.

      • withIf

        JsonSchemaBuilder withIf​(JsonSchema subschema)
        Adds an "if" keyword to the schema.
        Parameters:
        subschema - the value of the keyword.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified subschema is null.

      • withThen

        JsonSchemaBuilder withThen​(JsonSchema subschema)
        Adds a "then" keyword to the schema.

        This keyword has no effect when "if" is absent.

        Parameters:
        subschema - the value of the keyword.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified subschema is null.

      • withElse

        JsonSchemaBuilder withElse​(JsonSchema subschema)
        Adds an "else" keyword to the schema.

        This keyword has no effect when "if" is absent.

        Parameters:
        subschema - the value of the keyword.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified subschema is null.

      • withAllOf

        JsonSchemaBuilder withAllOf​(JsonSchema... subschemas)
        Adds an "allOf" keyword to the schema. The value is specifies as an array.
        Parameters:
        subschemas - the array of the subschemas.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified subschemas is null.
        IllegalArgumentException - if the specified subschemas is empty.

      • withAnyOf

        JsonSchemaBuilder withAnyOf​(JsonSchema... subschemas)
        Adds an "anyOf" keyword to the schema. The value is specifies as an array.
        Parameters:
        subschemas - the array of the subschemas.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified subschemas is null.
        IllegalArgumentException - if the specified subschemas is empty.

      • withNot

        JsonSchemaBuilder withNot​(JsonSchema subschema)
        Adds a "not" keyword to the schema.
        Parameters:
        subschema - the subschema to be negated.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified subschema is null.

      • withFormat

        JsonSchemaBuilder withFormat​(String attribute)
        Adds a "format" keyword to the schema. This method throws an exception if the specified attribute is not recognized as a formate attribute.
        Parameters:
        attribute - the format attribute such as "date-time".
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified attribute is null.
        IllegalArgumentException - if the specified attribute is not recogznied as a format attribute.
        See Also:
        withLaxFormat(java.lang.String)

      • withLaxFormat

        JsonSchemaBuilder withLaxFormat​(String attribute)
        Adds a "format" keyword to the schema. This method does not throw an exception even if the specified attribute is not recognized as a formate attribute.
        Parameters:
        attribute - the format attribute such as "date-time".
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified attribute is null.
        See Also:
        withFormat(java.lang.String)

      • withContentEncoding

        JsonSchemaBuilder withContentEncoding​(String value)
        Adds a "contentEncoding" keyword to the schema.
        Parameters:
        value - the value of the keyword.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified value is null.

      • withDefinition

        JsonSchemaBuilder withDefinition​(String name,
                                 JsonSchema schema)
        Adds an entry of "definitions" keyword to the schema.
        Parameters:
        name - the name of the definition to be added.
        schema - the schema to define.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified name or schema is null.

      • withDefinitions

        JsonSchemaBuilder withDefinitions​(Map<String,​JsonSchema> schemas)
        Adds a "definitions" keyword to the schema.
        Parameters:
        schemas - the object mapping a name to a schema.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified schemas is null.

      • withTitle

        JsonSchemaBuilder withTitle​(String title)
        Adds a "title" keyword to the schema.
        Parameters:
        title - the title of the schema.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified title is null.

      • withDescription

        JsonSchemaBuilder withDescription​(String description)
        Adds a "description" keyword to the schema.
        Parameters:
        description - the description of the schema.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified description is null.

      • withDefault

        JsonSchemaBuilder withDefault​(JsonValue value)
        Adds a "default" keyword to the schema.
        Parameters:
        value - the default value.
        Returns:
        this builder.
        Throws:
        NullPointerException - if the specified value is null.