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

# 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.
use `examples()`
`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 Details

### 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.
use `examples()`
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:
  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