Schema (swagger-annotations 2.2.8 API)

```
@Target(value={FIELD,METHOD,PARAMETER,TYPE,ANNOTATION_TYPE})
 @Retention(value=RUNTIME)
 @Inherited
public @interface Schema
```
The annotation may be used to define a Schema for a set of elements of the OpenAPI spec, and/or to define additional properties for the schema. It is applicable e.g. to parameters, schema classes (aka "models"), properties of such models, request and response content, header.
swagger-core resolver and swagger-jaxrs2 reader engine consider this annotation along with JAX-RS annotations, element type and context as input to resolve the annotated element into an OpenAPI schema definition for such element.

The annotation may be used also to override partly (e.g. the name) or fully (e.g providing a completely different representation) the schema of an element; for example if a specific class is provided as value of implementation(), it will override the element type

The annotation ArraySchema shall be used for array elements; ArraySchema and Schema cannot coexist

See Also:

Schema (OpenAPI specification), ArraySchema

Optional Element Summary

Optional Elements
Modifier and Type	Optional Element and Description
`Schema.AccessMode`	`accessMode` Allows to specify the access mode (AccessMode.READ_ONLY, READ_WRITE) AccessMode.READ_ONLY: value will not be written to during a request but may be returned during a response.
`Schema.AdditionalPropertiesValue`	`additionalProperties` Allows to specify the additionalProperties value AdditionalPropertiesValue.TRUE: set to TRUE AdditionalPropertiesValue.FALSE: set to FALSE AdditionalPropertiesValue.USE_ADDITIONAL_PROPERTIES_ANNOTATION: resolve from @Content.additionalPropertiesSchema
`Class<?>[]`	`allOf` Provides an array of java class implementations which can be used to describe multiple acceptable schemas.
`String[]`	`allowableValues` Provides a list of allowable values.
`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` Provides discriminator mapping values.
`String`	`discriminatorProperty` Provides a discriminator property value.
`boolean`	`enumAsRef` Allows enums to be resolved as a reference to a scheme added to components section.
`String`	`example` Provides an example of the 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` The list of optional extensions
`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`	`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`	`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` If true, designates a value as possibly null.
`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.
`boolean`	`readOnly` Deprecated. As of 2.0.0, replaced by `accessMode()`
`String`	`ref` References a schema definition in an external OpenAPI document.
`boolean`	`required` Deprecated. since 2.2.5, replaced by `requiredMode()`
`Schema.RequiredMode`	`requiredMode` Allows to specify the required mode (RequiredMode.AUTO, REQUIRED, NOT_REQUIRED) RequiredMode.AUTO: will let the library decide based on its heuristics.
`String[]`	`requiredProperties` Allows multiple properties in an object to be marked as required.
`Class<?>[]`	`subTypes` An array of the sub types inheriting from this model.
`String`	`title` A title to explain the purpose of the schema.
`String`	`type` Provides an override for the basic type of the schema.
`boolean`	`writeOnly` Deprecated. As of 2.0.0, replaced by `accessMode()`

- Element Detail
  - implementation
```
public abstract 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
```
public abstract Class<?> not
```
    Provides a java class to be used to disallow matching properties.
    
    Returns:
    
    a class with disallowed properties
    
    Default:
    
    java.lang.Void.class
- - oneOf
```
public abstract 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
```
public abstract 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
```
public abstract 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:
    
    {}
- - name
```
public abstract String name
```
    The name of the schema or property.
    
    Returns:
    
    the name of the schema
    
    Default:
    
    ""
- - title
```
public abstract String title
```
    A title to explain the purpose of the schema.
    
    Returns:
    
    the title of the schema
    
    Default:
    
    ""
- - multipleOf
```
public abstract 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
```
public abstract String maximum
```
    Sets the maximum numeric value for a property. Ignored if the value is an empty string.
    
    Returns:
    
    the maximum value for this schema
    
    Default:
    
    ""
- - exclusiveMaximum
```
public abstract 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
```
public abstract String minimum
```
    Sets the minimum numeric value for a property. Ignored if the value is an empty string or not a number.
    
    Returns:
    
    the minimum value for this schema
    
    Default:
    
    ""
- - exclusiveMinimum
```
public abstract 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
```
public abstract 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
```
public abstract 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
```
public abstract 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
```
public abstract 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
```
public abstract 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
```
public abstract String[] requiredProperties
```
    Allows multiple properties in an object to be marked as required.
    
    Returns:
    
    the list of required schema properties
    
    Default:
    
    {}
- - required
```
@Deprecated
public abstract boolean required
```
    Deprecated. since 2.2.5, replaced by requiredMode()
    
    Mandates that the annotated item is required or not.
    
    Returns:
    
    whether this schema is required
    
    Default:
    
    false
- - requiredMode
```
public abstract Schema.RequiredMode requiredMode
```
    Allows to specify the required mode (RequiredMode.AUTO, REQUIRED, NOT_REQUIRED) RequiredMode.AUTO: will let the library decide based on its heuristics. RequiredMode.REQUIRED: will force the item to be considered as required regardless of heuristics. RequiredMode.NOT_REQUIRED: will force the item to be considered as not required regardless of heuristics.
    
    Returns:
    
    the requiredMode for this schema (property)
    
    Since:
    
    2.2.5
    
    Default:
    
    io.swagger.v3.oas.annotations.media.Schema.RequiredMode.AUTO
- - description
```
public abstract String description
```
    A description of the schema.
    
    Returns:
    
    the schema's description
    
    Default:
    
    ""
- - format
```
public abstract 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:
    
    the schema's format
    
    Default:
    
    ""
- - ref
```
public abstract String ref
```
    References a schema definition in an external OpenAPI document.
    
    Returns:
    
    a reference to this schema
    
    Default:
    
    ""
- - nullable
```
public abstract boolean nullable
```
    If true, designates a value as possibly null.
    
    Returns:
    
    whether or not this schema is nullable
    
    Default:
    
    false
- - readOnly
```
@Deprecated
public abstract boolean readOnly
```
    Deprecated. As of 2.0.0, replaced by accessMode()
    
    Sets whether the value should only be read during a response but not read to during a request.
    
    Returns:
    
    whether or not this schema is read only
    
    Default:
    
    false
- - writeOnly
```
@Deprecated
public abstract boolean writeOnly
```
    Deprecated. As of 2.0.0, replaced by accessMode()
    
    Sets whether a value should only be written to during a request but not returned during a response.
    
    Returns:
    
    whether or not this schema is write only
    
    Default:
    
    false
- - accessMode
```
public abstract Schema.AccessMode accessMode
```
    Allows to specify the access mode (AccessMode.READ_ONLY, READ_WRITE) AccessMode.READ_ONLY: value will not be written to during a request but may be returned during a response. AccessMode.WRITE_ONLY: value will only be written to during a request but not returned during a response. AccessMode.READ_WRITE: value will be written to during a request and returned during a response.
    
    Returns:
    
    the accessMode for this schema (property)
    
    Default:
    
    io.swagger.v3.oas.annotations.media.Schema.AccessMode.AUTO
- - example
```
public abstract String example
```
    Provides an example of the schema. 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
```
public abstract ExternalDocumentation externalDocs
```
    Additional external documentation for this schema.
    
    Returns:
    
    additional schema documentation
    
    Default:
    
    @io.swagger.v3.oas.annotations.ExternalDocumentation
- - deprecated
```
public abstract 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
```
public abstract String type
```
    Provides an override for the basic type of the schema. Must be a valid type per the OpenAPI Specification.
    
    Returns:
    
    the type of this schema
    
    Default:
    
    ""
- - allowableValues
```
public abstract String[] allowableValues
```
    Provides a list of allowable values. This field map to the enum property in the OAS schema.
    
    Returns:
    
    a list of allowed schema values
    
    Default:
    
    {}
- - defaultValue
```
public abstract String defaultValue
```
    Provides a default value.
    
    Returns:
    
    the default value of this schema
    
    Default:
    
    ""
- - discriminatorProperty
```
public abstract String discriminatorProperty
```
    Provides a discriminator property value.
    
    Returns:
    
    the discriminator property
    
    Default:
    
    ""
- - discriminatorMapping
```
public abstract DiscriminatorMapping[] discriminatorMapping
```
    Provides discriminator mapping values.
    
    Returns:
    
    the discriminator mappings
    
    Default:
    
    {}
- - hidden
```
public abstract boolean hidden
```
    Allows schema to be marked as hidden.
    
    Returns:
    
    whether or not this schema is hidden
    
    Default:
    
    false
- - enumAsRef
```
public abstract boolean enumAsRef
```
    Allows enums to be resolved as a reference to a scheme added to components section.
    
    Returns:
    
    whether or not this must be resolved as a reference
    
    Since:
    
    2.1.0
    
    Default:
    
    false
- - subTypes
```
public abstract Class<?>[] subTypes
```
    An array of the sub types inheriting from this model.
    
    Default:
    
    {}
- - extensions
```
public abstract Extension[] extensions
```
    The list of optional extensions
    
    Returns:
    
    an optional array of extensions
    
    Default:
    
    {}
- - additionalProperties
```
public abstract Schema.AdditionalPropertiesValue additionalProperties
```
    Allows to specify the additionalProperties value AdditionalPropertiesValue.TRUE: set to TRUE AdditionalPropertiesValue.FALSE: set to FALSE AdditionalPropertiesValue.USE_ADDITIONAL_PROPERTIES_ANNOTATION: resolve from @Content.additionalPropertiesSchema
    
    Returns:
    
    the accessMode for this schema (property)
    
    Since:
    
    2.2.0
    
    Default:
    
    io.swagger.v3.oas.annotations.media.Schema.AdditionalPropertiesValue.USE_ADDITIONAL_PROPERTIES_ANNOTATION

Annotation Type Schema

Optional Element Summary

Element Detail

implementation

not

oneOf

anyOf

allOf

name

title

multipleOf

maximum

exclusiveMaximum

minimum

exclusiveMinimum

maxLength

minLength

pattern

maxProperties

minProperties

requiredProperties

required

requiredMode

description

format

ref

nullable

readOnly

writeOnly

accessMode

example

externalDocs

deprecated

type

allowableValues

defaultValue

discriminatorProperty

discriminatorMapping

hidden

enumAsRef

subTypes

extensions

additionalProperties