Package io.swagger.v3.oas.annotations.media

Annotation Type Schema

  • @Target({FIELD,METHOD,PARAMETER,TYPE,ANNOTATION_TYPE})
@Retention(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), Schema (OpenAPI specification), ArraySchema

    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      String _const
      Provides value restricted to this schema.
      Class<?> _else
      Provides the else sub schema related to this schema
      Class<?> _if
      Provides the if sub schema related to this schema
      String $anchor
      Provides the $anchor related to schema
      String $comment
      Provides $comment related to this schema
      String $dynamicAnchor
      Provides the $dynamicAnchor related to schema
      String $dynamicRef
      Provides the $dynamicRef related to schema
      String $id
      Provides the $id related to this schema.
      String $schema
      Provides Json Schema dialect where the schema is valid.
      String $vocabulary
      Provides the $vocabulary related to schema
      Schema.AccessMode accessMode
      Allows to specify the access mode (AccessMode.READ_ONLY, WRITE_ONLY, READ_WRITE) AccessMode.READ_ONLY: value will not be written to during a request but may be returned during a response.
      Class<?> additionalItems
      Provides a list of additional items
      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 or @Schema.additionalPropertiesSchema
      Class<?> 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.
      Class<?> contains
      Specifies contains constrictions expressions.
      String contentEncoding
      Provides the content encoding related to this schema
      String contentMediaType
      Provides the content media type related to this schema
      Class<?> contentSchema
      Provides the content schema related to this schema
      String defaultValue
      Provides a default value.
      DependentRequired[] dependentRequiredMap
      Allows to specify the dependentRequired value
      StringToClassMapItem[] dependentSchemas
      Allows to specify the dependentSchemas value providing a Class to be resolved into a Schema
      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.
      Class<?>[] exampleClasses
      Provides a list of examples related to this schema
      String[] examples
      Provides an array of examples of the schema.
      boolean exclusiveMaximum
      if true, makes the maximum value exclusive, or a less-than criteria.
      int exclusiveMaximumValue  
      boolean exclusiveMinimum
      If true, makes the minimum value exclusive, or a greater-than criteria.
      int exclusiveMinimumValue
      Provides an exclusive minimum for a expressing exclusive range.
      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.
      int maxContains
      Provides max contains related to 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.
      int minContains
      Provides min contains related to this schema
      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.
      StringToClassMapItem[] patternProperties
      Provides pattern properties to this schema
      Class<?>[] prefixItems
      List of optional items positionally defines before normal items.
      StringToClassMapItem[] properties
      Provides properties related to this schema
      Class<?> propertyNames
      Provides property names related to this schema
      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: the library decides using heuristics: - Bean Validation / nullability annotations (@NotNull, @NonNull, @NotBlank, @NotEmpty) - required - Optional - not required - Primitive types (int, boolean, etc.) - not required unless annotated - Other object fields without any constraints - not required RequiredMode.REQUIRED: will force the item to be considered as required regardless of heuristics.
      String[] requiredProperties
      Allows multiple properties in an object to be marked as required.
      Schema.SchemaResolution schemaResolution
      Allows to specify the schema resolution mode for object schemas SchemaResolution.DEFAULT: bundled into components/schemas, $ref with no siblings SchemaResolution.INLINE: inline schema, no $ref SchemaResolution.ALL_OF: bundled into components/schemas, $ref and any context annotation resolution into allOf SchemaResolution.ALL_OF_REF: bundled into components/schemas, $ref into allOf, context annotation resolution into root
      Class<?>[] subTypes
      An array of the sub types inheriting from this model.
      Class<?> then
      Provides the then sub schema related to this schema
      String title
      A title to explain the purpose of the schema.
      String type
      Provides an override for the basic type of the schema.
      String[] types
      List of schema types
      Class<?> unevaluatedItems
      Provides a list of unevaluated items
      Class<?> unevaluatedProperties
      Provides unevaluated properties to this schema
      boolean writeOnly
      Deprecated.
      As of 2.0.0, replaced by accessMode()

    • Element Detail

      • 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.
        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:
        {}

      • name

        String name
        The name of the schema or property.
        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. Ignored if the value is an empty string.
        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. 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

        @Deprecated
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

        Schema.RequiredMode requiredMode
        Allows to specify the required mode (RequiredMode.AUTO, REQUIRED, NOT_REQUIRED) RequiredMode.AUTO: the library decides using heuristics: - Bean Validation / nullability annotations (@NotNull, @NonNull, @NotBlank, @NotEmpty) - required - Optional - not required - Primitive types (int, boolean, etc.) - not required unless annotated - Other object fields without any constraints - not required 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

        String description
        A description of the schema.
        Returns:
        the 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:
        the schema's format
        Default:
        ""

      • ref

        String ref
        References a schema definition in an external OpenAPI document.
        Returns:
        a reference to this schema
        Default:
        ""

      • nullable

        boolean nullable
        If true, designates a value as possibly null.
        Returns:
        whether or not this schema is nullable
        Default:
        false

      • readOnly

        @Deprecated
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
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

        Schema.AccessMode accessMode
        Allows to specify the access mode (AccessMode.READ_ONLY, WRITE_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

        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

        ExternalDocumentation externalDocs
        Additional external documentation for this schema.
        Returns:
        additional schema documentation
        Default:
        @io.swagger.v3.oas.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

        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

        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

        String defaultValue
        Provides a default value.
        Returns:
        the default value of this schema
        Default:
        ""

      • discriminatorProperty

        String discriminatorProperty
        Provides a discriminator property value.
        Returns:
        the discriminator property
        Default:
        ""

      • discriminatorMapping

        DiscriminatorMapping[] discriminatorMapping
        Provides discriminator mapping values.
        Returns:
        the discriminator mappings
        Default:
        {}

      • hidden

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

      • enumAsRef

        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

        Class<?>[] subTypes
        An array of the sub types inheriting from this model.
        Default:
        {}

      • extensions

        Extension[] extensions
        The list of optional extensions
        Returns:
        an optional array of extensions
        Default:
        {}

      • prefixItems

        Class<?>[] prefixItems
        List of optional items positionally defines before normal items.
        Returns:
        optional array of items
        Default:
        {}

      • types

        String[] types
        List of schema types
        Returns:
        array of types
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        {}

      • exclusiveMaximumValue

        int exclusiveMaximumValue
        Returns:
        the exclusive maximum value for this schema
        Since:
        2.2.12 / OpenAPI 3.1 OAS 3.1 version of `exclusiveMaximum`, accepting a numeric value
        Default:
        0

      • exclusiveMinimumValue

        int exclusiveMinimumValue
        Provides an exclusive minimum for a expressing exclusive range.
        Returns:
        an exclusive minimum.
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        0

      • contains

        Class<?> contains
        Specifies contains constrictions expressions.
        Returns:
        contains expression.
        Default:
        java.lang.Void.class

      • $id

        String $id
        Provides the $id related to this schema.
        Returns:
        the $id of schema
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        ""

      • $schema

        String $schema
        Provides Json Schema dialect where the schema is valid.
        Returns:
        json schema dialect
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        ""

      • $anchor

        String $anchor
        Provides the $anchor related to schema
        Returns:
        $anchor schema
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        ""

      • $vocabulary

        String $vocabulary
        Provides the $vocabulary related to schema
        Returns:
        $vocabulary schema
        Since:
        2.2.14 / OpenAPI 3.1
        Default:
        ""

      • $dynamicAnchor

        String $dynamicAnchor
        Provides the $dynamicAnchor related to schema
        Returns:
        $dynamicAnchor schema
        Since:
        2.2.14 / OpenAPI 3.1
        Default:
        ""

      • $dynamicRef

        String $dynamicRef
        Provides the $dynamicRef related to schema
        Returns:
        $dynamicRef schema
        Since:
        2.2.32 / OpenAPI 3.1
        Default:
        ""

      • contentEncoding

        String contentEncoding
        Provides the content encoding related to this schema
        Returns:
        content encoding
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        ""

      • contentMediaType

        String contentMediaType
        Provides the content media type related to this schema
        Returns:
        content media type
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        ""

      • contentSchema

        Class<?> contentSchema
        Provides the content schema related to this schema
        Returns:
        content schema
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        java.lang.Void.class

      • propertyNames

        Class<?> propertyNames
        Provides property names related to this schema
        Returns:
        property names
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        java.lang.Void.class

      • maxContains

        int maxContains
        Provides max contains related to this schema
        Returns:
        max contains
        Default:
        2147483647

      • minContains

        int minContains
        Provides min contains related to this schema
        Returns:
        min contains
        Default:
        0

      • additionalItems

        Class<?> additionalItems
        Provides a list of additional items
        Returns:
        additional items
        Default:
        java.lang.Void.class

      • unevaluatedItems

        Class<?> unevaluatedItems
        Provides a list of unevaluated items
        Returns:
        unevaluated items
        Default:
        java.lang.Void.class

      • _if

        Class<?> _if
        Provides the if sub schema related to this schema
        Returns:
        if sub schema
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        java.lang.Void.class

      • _else

        Class<?> _else
        Provides the else sub schema related to this schema
        Returns:
        else sub schema
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        java.lang.Void.class

      • then

        Class<?> then
        Provides the then sub schema related to this schema
        Returns:
        then sub schema
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        java.lang.Void.class

      • $comment

        String $comment
        Provides $comment related to this schema
        Returns:
        $comment related to schema
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        ""

      • exampleClasses

        Class<?>[] exampleClasses
        Provides a list of examples related to this schema
        Returns:
        list of examples
        Default:
        {}

      • additionalProperties

        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 or @Schema.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

      • dependentRequiredMap

        DependentRequired[] dependentRequiredMap
        Allows to specify the dependentRequired value
        Returns:
        the list of DependentRequire annotations
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        {}

      • dependentSchemas

        StringToClassMapItem[] dependentSchemas
        Allows to specify the dependentSchemas value providing a Class to be resolved into a Schema
        Returns:
        the list of dependentSchemas annotations
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        {}

      • patternProperties

        StringToClassMapItem[] patternProperties
        Provides pattern properties to this schema
        Returns:
        pattern properties
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        {}

      • properties

        StringToClassMapItem[] properties
        Provides properties related to this schema
        Returns:
        schema properties
        Default:
        {}

      • unevaluatedProperties

        Class<?> unevaluatedProperties
        Provides unevaluated properties to this schema
        Returns:
        unevaluated properties
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        java.lang.Void.class

      • additionalPropertiesSchema

        Class<?> additionalPropertiesSchema
        Default:
        java.lang.Void.class

      • examples

        String[] examples
        Provides an array of examples 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 array of examples of this schema
        Default:
        {}

      • _const

        String _const
        Provides value restricted to this schema.
        Returns:
        const value
        Since:
        2.2.12 / OpenAPI 3.1
        Default:
        ""

      • schemaResolution

        Schema.SchemaResolution schemaResolution
        Allows to specify the schema resolution mode for object schemas SchemaResolution.DEFAULT: bundled into components/schemas, $ref with no siblings SchemaResolution.INLINE: inline schema, no $ref SchemaResolution.ALL_OF: bundled into components/schemas, $ref and any context annotation resolution into allOf SchemaResolution.ALL_OF_REF: bundled into components/schemas, $ref into allOf, context annotation resolution into root
        Returns:
        the schema resolution mode for this schema
        Default:
        io.swagger.v3.oas.annotations.media.Schema.SchemaResolution.AUTO