Annotation Type SchemaProperty


  • @Retention(RUNTIME)
    @Inherited
    public @interface SchemaProperty
    The SchemaProperty Object allows the definition of input and output data types nested within the properties attribute of a Schema annotation. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema draft specification 2020-12.
    Since:
    2.0
    See Also:
    OpenAPI Specification Schema Object
    • Required Element Summary

      Required Elements 
      Modifier and Type Required Element Description
      String name
      The name of the property.
    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      Class<?> additionalProperties
      Provides a Java class as implementation for additional properties that may be present in instances of this schema.
      Class<?>[] allOf
      Provides an array of java class implementations which can be used to describe multiple acceptable schemas.
      Class<?>[] anyOf
      Provides an array of java class implementations which can be used to describe multiple acceptable schemas.
      String comment
      A comment to be included in the schema
      String constValue
      Requires that the instance must be a specific value.
      Class<?> contains
      A schema which at least one element of an array instance must validate against.
      String contentEncoding
      The encoding used to allow binary data to be stored in a string.
      String contentMediaType
      The media type of the data in a string.
      Class<?> contentSchema
      The schema that data in a string must validate against.
      String defaultValue
      Provides a default value.
      DependentRequired[] dependentRequired
      Specifies that certain properties must be present if other properties are present.
      DependentSchema[] dependentSchemas
      Schemas which an instance must validate against if the instance has certain properties.
      boolean deprecated
      Specifies that a schema is deprecated and SHOULD be transitioned out of usage.
      String description
      A description of the schema.
      DiscriminatorMapping[] discriminatorMapping
      An array of discriminator mappings.
      String discriminatorProperty
      Provides a discriminator property value.
      Class<?> elseSchema
      A class used to create a schema that an instance must validate against if it does not validate against the if schema.
      String[] enumeration
      Provides a list of enum values.
      String example
      Deprecated.
      String[] examples
      A free-form property to include examples of an instance for this schema.
      boolean exclusiveMaximum
      If true, makes the maximum value exclusive, or a less-than criteria.
      boolean exclusiveMinimum
      If true, makes the minimum value exclusive, or a greater-than criteria.
      Extension[] extensions
      List of extensions to be added to the Schema model corresponding to the containing annotation.
      ExternalDocumentation externalDocs
      Additional external documentation for this schema.
      String format
      Provides an optional override for the format.
      boolean hidden
      Allows schema to be marked as hidden.
      Class<?> ifSchema
      A class used to create a schema used to control conditional evaluation.
      Class<?> implementation
      Provides a java class as implementation for this schema.
      int maxContains
      Specifies the maximum number of elements which may validate against the contains() schema.
      String maximum
      Sets the maximum numeric value for a property.
      int maxItems
      Only applicable if type=array.
      int maxLength
      Sets the maximum length of a string value.
      int maxProperties
      Constrains the number of arbitrary properties when additionalProperties is defined.
      int minContains
      Specifies the minimum number of elements which must validate against the contains() schema.
      String minimum
      Sets the minimum numeric value for a property.
      int minItems
      Only applicable if type=array.
      int minLength
      Sets the minimum length of a string value.
      int minProperties
      Constrains the number of arbitrary properties when additionalProperties is defined.
      double multipleOf
      Constrains a value such that when divided by the multipleOf, the result must be an integer.
      Class<?> not
      Provides a java class to be used to disallow matching properties.
      boolean nullable
      Allows sending a null value for the defined schema.
      Class<?>[] oneOf
      Provides an array of java class implementations which can be used to describe multiple acceptable schemas.
      String pattern
      A regular expression that the value must satisfy.
      PatternProperty[] patternProperties
      Applies subschemas against properties matched by regular expressions.
      Class<?>[] prefixItems
      Schemas which the leading elements of an array instance must validate against.
      Class<?> propertyNames
      A schema which the names of properties of an object instance must validate against.
      boolean readOnly
      Declares the property as "read only".
      String ref
      Reference value to a Schema definition.
      String[] requiredProperties
      Allows multiple properties in an object to be marked as required.
      Class<?> thenSchema
      A class used to create a schema that an instance must validate against if it validates against the if schema.
      String title
      A title to explain the purpose of the schema.
      SchemaType type
      Provides an override for the basic type of the schema.
      boolean uniqueItems
      Only applicable if type=array.
      boolean writeOnly
      Declares the property as "write only".
    • Element Detail

      • name

        String name
        The name of the property.

        The name will be used as the key to add this schema to the parent schema's 'properties' map.

        Returns:
        the name of the schema
      • implementation

        Class<?> implementation
        Provides a java class as implementation for this schema. When provided, additional information in the Schema annotation (except for type information) will augment the java class after introspection.
        Returns:
        a class that implements this schema
        Default:
        java.lang.Void.class
      • not

        Class<?> not
        Provides a java class to be used to disallow matching properties. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
        Returns:
        a class with disallowed properties
        Default:
        java.lang.Void.class
      • oneOf

        Class<?>[] oneOf
        Provides an array of java class implementations which can be used to describe multiple acceptable schemas. If more than one match the derived schemas, a validation error will occur.
        Returns:
        the list of possible classes for a single match
        Default:
        {}
      • anyOf

        Class<?>[] anyOf
        Provides an array of java class implementations which can be used to describe multiple acceptable schemas. If any match, the schema will be considered valid.
        Returns:
        the list of possible class matches
        Default:
        {}
      • allOf

        Class<?>[] allOf
        Provides an array of java class implementations which can be used to describe multiple acceptable schemas. If all match, the schema will be considered valid.
        Returns:
        the list of classes to match
        Default:
        {}
      • title

        String title
        A title to explain the purpose of the schema.
        Returns:
        the title of the schema
        Default:
        ""
      • multipleOf

        double multipleOf
        Constrains a value such that when divided by the multipleOf, the result must be an integer. Ignored if the value is 0.
        Returns:
        the multiplier constraint of the schema
        Default:
        0.0
      • maximum

        String maximum
        Sets the maximum numeric value for a property. Value must be a valid number. Ignored if the value is an empty string or not a number.
        Returns:
        the maximum value for this schema
        Default:
        ""
      • exclusiveMaximum

        boolean exclusiveMaximum
        If true, makes the maximum value exclusive, or a less-than criteria.
        Returns:
        the exclusive maximum value for this schema
        Default:
        false
      • minimum

        String minimum
        Sets the minimum numeric value for a property. Value must be a valid number. Ignored if the value is an empty string or not a number.
        Returns:
        the minimum value for this schema
        Default:
        ""
      • exclusiveMinimum

        boolean exclusiveMinimum
        If true, makes the minimum value exclusive, or a greater-than criteria.
        Returns:
        the exclusive minimum value for this schema
        Default:
        false
      • maxLength

        int maxLength
        Sets the maximum length of a string value. Ignored if the value is negative.
        Returns:
        the maximum length of this schema
        Default:
        2147483647
      • minLength

        int minLength
        Sets the minimum length of a string value. Ignored if the value is negative.
        Returns:
        the minimum length of this schema
        Default:
        0
      • pattern

        String pattern
        A regular expression that the value must satisfy. Ignored if the value is an empty string.

        If the instance is a string, the regular expression must match the instance.

        Returns:
        the ECMA-262 regular expression to match against
        Default:
        ""
      • maxProperties

        int maxProperties
        Constrains the number of arbitrary properties when additionalProperties is defined. Ignored if value is 0.
        Returns:
        the maximum number of properties for this schema
        Default:
        0
      • minProperties

        int minProperties
        Constrains the number of arbitrary properties when additionalProperties is defined. Ignored if value is 0.
        Returns:
        the minimum number of properties for this schema
        Default:
        0
      • requiredProperties

        String[] requiredProperties
        Allows multiple properties in an object to be marked as required.
        Returns:
        the list of required schema properties
        Default:
        {}
      • description

        String description
        A description of the schema.
        Returns:
        this schema's description
        Default:
        ""
      • format

        String format
        Provides an optional override for the format.

        If a consumer is unaware of the meaning of the format, they shall fall back to using the basic type without format. For example, if \"type: integer, format: int128\" were used to designate a very large integer, most consumers will not understand how to handle it, and fall back to simply \"type: integer\"

        Returns:
        this schema's format
        Default:
        ""
      • ref

        String ref
        Reference value to a Schema definition.

        This property provides a reference to an object defined elsewhere.

        Unlike ref on most MP OpenAPI annotations, this property is not mutually exclusive with other properties.

        Returns:
        a reference to a schema definition
        Default:
        ""
      • nullable

        boolean nullable
        Allows sending a null value for the defined schema.
        Returns:
        whether or not this schema is nullable
        Default:
        false
      • readOnly

        boolean readOnly
        Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request.

        If the property is marked as readOnly being true and is in the required list, the required will take effect on the response only. A property MUST NOT be marked as both readOnly and writeOnly being true.

        Returns:
        whether or not this schema is read only
        Default:
        false
      • writeOnly

        boolean writeOnly
        Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response.

        If the property is marked as writeOnly being true and is in the required list, the required will take effect on the request only. A property MUST NOT be marked as both readOnly and writeOnly being true.

        Returns:
        whether or not this schema is write only
        Default:
        false
      • example

        @Deprecated(since="4.0")
        String example
        Deprecated.
        A free-form property to include an example of an instance for this schema.
        Returns:
        an example of this schema
        Default:
        ""
      • examples

        String[] examples
        A free-form property to include examples of an instance for this schema.

        Each example SHOULD validate against this schema.

        If the schema type() is STRING, the value will be interpreted as a literal string, otherwise it will be parsed as JSON.

        Returns:
        an array of examples of this schema
        Since:
        4.0
        Default:
        {}
      • externalDocs

        ExternalDocumentation externalDocs
        Additional external documentation for this schema.
        Returns:
        additional schema documentation
        Default:
        @org.eclipse.microprofile.openapi.annotations.ExternalDocumentation
      • deprecated

        boolean deprecated
        Specifies that a schema is deprecated and SHOULD be transitioned out of usage.
        Returns:
        whether or not this schema is deprecated
        Default:
        false
      • type

        SchemaType type
        Provides an override for the basic type of the schema.

        Value MUST be a string. Multiple types via an array are not supported.

        MUST be a valid type per the OpenAPI Specification.
        Returns:
        the type of this schema
        Default:
        org.eclipse.microprofile.openapi.annotations.enums.SchemaType.DEFAULT
      • enumeration

        String[] enumeration
        Provides a list of enum values. Corresponds to the enum property in the OAS schema and the enumeration property in the schema model.
        Returns:
        a list of allowed schema values
        Default:
        {}
      • defaultValue

        String defaultValue
        Provides a default value. The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided.

        Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level.

        For example, if type is string, then default can be "foo" but cannot be 1.
        Returns:
        the default value of this schema
        Default:
        ""
      • discriminatorProperty

        String discriminatorProperty
        Provides a discriminator property value. Adds support for polymorphism.

        The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description.

        Returns:
        the discriminator property
        Default:
        ""
      • discriminatorMapping

        DiscriminatorMapping[] discriminatorMapping
        An array of discriminator mappings.
        Returns:
        the discriminator mappings for this schema
        Default:
        {}
      • hidden

        boolean hidden
        Allows schema to be marked as hidden.
        Returns:
        whether or not this schema is hidden
        Default:
        false
      • maxItems

        int maxItems
        Only applicable if type=array. Sets the maximum number of items in an array. This integer MUST be greater than, or equal to, 0.

        An array instance is valid against "maxItems" if its size is less than, or equal to, the value of this keyword.

        Ignored if value is Integer.MIN_VALUE.
        Returns:
        the maximum number of items in this array
        Default:
        -2147483648
      • minItems

        int minItems
        Only applicable if type=array. Sets the minimum number of items in an array. This integer MUST be greater than, or equal to, 0.

        An array instance is valid against "minItems" if its size is greater than, or equal to, the value of this keyword.

        Ignored if value is Integer.MAX_VALUE.
        Returns:
        the minimum number of items in this array
        Default:
        2147483647
      • uniqueItems

        boolean uniqueItems
        Only applicable if type=array. Determines if the items in the array SHOULD be unique.

        If false, the instance validates successfully. If true, the instance validates successfully if all of its elements are unique.

        Returns:
        whether the items in this array are unique
        Default:
        false
      • additionalProperties

        Class<?> additionalProperties
        Provides a Java class as implementation for additional properties that may be present in instances of this schema.

        If no additional properties are allowed, the value of this property should be set to False.class which will be rendered as boolean false in the resulting OpenAPI document.

        The default value Void.class will result in no additionalProperties attribute being generated in the resulting OpenAPI document. The effective value in that case is true per the OpenAPI specification.

        Implementations MAY ignore this property if this schema's type is not OBJECT, either explicitly or as derived by the placement of the annotation.

        Returns:
        a class that describes the allowable schema for additional properties not explicitly defined
        Since:
        4.0
        See Also:
        Schema.True, Schema.False
        Default:
        java.lang.Void.class
      • extensions

        Extension[] extensions
        List of extensions to be added to the Schema model corresponding to the containing annotation.
        Returns:
        array of extensions
        Since:
        3.1
        Default:
        {}
      • comment

        String comment
        A comment to be included in the schema

        This value is set in the $comment property of the schema object

        Returns:
        the comment
        Since:
        4.0
        Default:
        ""
      • constValue

        String constValue
        Requires that the instance must be a specific value. No other values are permitted.

        The value is parsed as JSON if the schema type is anything other than STRING.

        Returns:
        the value which the instance must be equal to, expressed according to the type of the schema
        Since:
        4.0
        Default:
        ""
      • ifSchema

        Class<?> ifSchema
        A class used to create a schema used to control conditional evaluation. If an instance validates against the if schema then it must also validate against the then schema. Otherwise it must validate against the else schema.
        Returns:
        a class used to create the if schema
        Since:
        4.0
        See Also:
        thenSchema(), elseSchema()
        Default:
        java.lang.Void.class
      • thenSchema

        Class<?> thenSchema
        A class used to create a schema that an instance must validate against if it validates against the if schema.
        Returns:
        a class used to create the then schema
        Since:
        4.0
        See Also:
        ifSchema(), elseSchema()
        Default:
        java.lang.Void.class
      • elseSchema

        Class<?> elseSchema
        A class used to create a schema that an instance must validate against if it does not validate against the if schema.
        Returns:
        a class used to create the else schema
        Since:
        4.0
        See Also:
        ifSchema(), thenSchema()
        Default:
        java.lang.Void.class
      • dependentSchemas

        DependentSchema[] dependentSchemas
        Schemas which an instance must validate against if the instance has certain properties.

        For each DependentSchema listed, if the instance is an object which has a property named name() then the instance must validate against the schema created from schema().

        Returns:
        an array of DependentSchema entries
        Since:
        4.0
        Default:
        {}
      • contains

        Class<?> contains
        A schema which at least one element of an array instance must validate against.

        The class is used to create a schema. If the instance is an array, then at least one element of the array must validate against the schema.

        Returns:
        a class used to create a schema which at least one element of an array instance must validate against
        Since:
        4.0
        Default:
        java.lang.Void.class
      • maxContains

        int maxContains
        Specifies the maximum number of elements which may validate against the contains() schema.

        If more than this number of elements of an array instance match the contains schema, the instance does not validate against this schema.

        Returns:
        the maximum number of elements which may validate against the contains() schema
        Since:
        4.0
        Default:
        2147483647
      • minContains

        int minContains
        Specifies the minimum number of elements which must validate against the contains() schema.

        If fewer than this number of elements of an array instance match the contains schema, the instance does not validate against this schema.

        Returns:
        the minimum number of elements which must validate against the contains() schema
        Since:
        4.0
        Default:
        0
      • prefixItems

        Class<?>[] prefixItems
        Schemas which the leading elements of an array instance must validate against.

        The array of classes is used to create an array of schemas. If an instance is an array, the first element of the array must validate against the first schema, the second element must validate against the second schema and so on.

        Returns:
        an array of classes used to create an array of schemas used to validate the leading elements of an array instance
        Since:
        4.0
        Default:
        {}
      • patternProperties

        PatternProperty[] patternProperties
        Applies subschemas against properties matched by regular expressions.

        For each PatternProperty listed, for each property whose name matches | regex(), its value must validate against the schema created from schema().

        Returns:
        a mapping from regular expressions to schemas
        Since:
        4.0
        Default:
        {}
      • dependentRequired

        DependentRequired[] dependentRequired
        Specifies that certain properties must be present if other properties are present.

        For each DependentRequired entry in the list, if the instance is an object and has a property named DependentRequired.name() then it must also have property named for each entry of DependentRequired.requires() to validate against this schema.

        Returns:
        the properties required if certain other properties are present
        Since:
        4.0
        Default:
        {}
      • propertyNames

        Class<?> propertyNames
        A schema which the names of properties of an object instance must validate against.

        The class is used to create a schema. If the instance is an object, then the name of each property in the instance must validate against the schema.

        Returns:
        a schema that property names must validate against
        Since:
        4.0
        Default:
        java.lang.Void.class
      • contentEncoding

        String contentEncoding
        The encoding used to allow binary data to be stored in a string.

        If the instance is a string, this property specifies that it contains binary data encoded as text using the specified encoding (e.g. base64).

        Returns:
        the encoding
        Since:
        4.0
        Default:
        ""
      • contentMediaType

        String contentMediaType
        The media type of the data in a string.

        If the instance is a string, this property specifies the media type of the data it contains. If contentEncoding() is also set, it specifies the media type of the decoded string.

        Returns:
        the media type of the data in a string
        Since:
        4.0
        Default:
        ""
      • contentSchema

        Class<?> contentSchema
        The schema that data in a string must validate against.

        The class is used to create a schema. If the instance is a string and contentMediaType() is set, the data must validate against the schema when interpreted as the given media type.

        Returns:
        a class used to create a schema used to validate the data in a string
        Since:
        4.0
        Default:
        java.lang.Void.class