Package org.eclipse.microprofile.openapi.annotations.media

Annotation Interface Schema

@Target({FIELD,METHOD,PARAMETER,TYPE}) @Retention(RUNTIME) @Inherited public @interface Schema
The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00.
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    Schema.False
    Marker class for use in additionalProperties to indicate that the corresponding schema's additionalPropertiesBoolean value is to be set to boolean false.
    static final class 
    Schema.True
    Marker class for use in additionalProperties to indicate that the corresponding schema's additionalPropertiesBoolean value is to be set to boolean true.

  • 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
    defaultValue
    Provides a default value.
    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.
    String[]
    enumeration
    Provides a list of enum values.
    String
    example
    A free-form property to include an example 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<?>
    implementation
    Provides a java class as implementation for this 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.
    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 remainder must be an integer.
    String
    name
    The name of the schema or property.
    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 pattern that the value must satisfy.
    SchemaProperty[]
    properties
    Provides a list of properties present in this schema.
    boolean
    readOnly
    Relevant only for Schema "properties" definitions.
    String
    ref
    Reference value to a Schema definition.
    boolean
    required
    Mandates whether the annotated item is required or not.
    String[]
    requiredProperties
    Allows multiple properties in an object to be marked as required.
    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
    Relevant only for Schema "properties" definitions.

  • Element Details

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

      Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.

      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.

      Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.

      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.

      Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.

      Returns:
      the list of classes to match
      Default:
      {}

    • name

      String name
      The name of the schema or property.

      The name is REQUIRED when the schema is defined within Components. The name will be used as the key to add this schema to the 'schemas' map for reuse.

      Returns:
      the name of the schema
      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 remainder 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 pattern that the value must satisfy. Ignored if the value is an empty string.
      Returns:
      the pattern of this schema
      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:
      {}

    • required

      boolean required
      Mandates whether the annotated item is required or not.
      Returns:
      whether or not this schema is required
      Default:
      false

    • 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. This property and all other properties are mutually exclusive. If other properties are defined in addition to the ref property then the result is undefined.

      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
      Relevant only for Schema "properties" definitions. 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
      Relevant only for Schema "properties" definitions. 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

      String example
      A free-form property to include an example of an instance for this schema.

      To represent examples that cannot be naturally represented in JSON or YAML, a string value is used to contain the example with escaping where necessary.

      When associated with a specific media type, the example string shall be parsed by the consumer to be treated as an object or an array.
      Returns:
      an example of this schema
      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:
      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

    • properties

      SchemaProperty[] properties
      Provides a list of properties present in this schema. Use of the properties list does not preclude the annotation scanning runtime from also including other properties found in the scan process. For example, if an implementation is also specified, the final set of properties used by the annotation scanner will include properties from both this list and those found from introspection of the implementation class, if any.

      In the case where properties are specified here in addition to an implementation, the attributes given for a property using a SchemaProperty will override the same attributes scanned (or derived) from the implementation class.

      Example: 

       @Schema(properties = {
   @SchemaProperty(name = "creditCard", example = "4567100043210001"),
   @SchemaProperty(name = "departureFlight", description = "The departure flight information."),
   @SchemaProperty(name = "returningFlight")
})
      Returns:
      a list of defined properties
      Since:
      2.0
      Default:
      {}

    • 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:
      3.1
      See Also:
      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:
      {}