org.apache.juneau.jsonschema.annotation

Annotation Type Schema

@Documented
 @Retention(value=RUNTIME)
public @interface Schema

Swagger schema annotation.

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 based on the JSON Schema Specification Draft 4 and uses a predefined subset of it. On top of this subset, there are extensions provided by this specification to allow for more complete documentation.

Used to populate the auto-generated Swagger documentation and UI for server-side @RestResource-annotated classes.
Also used to define OpenAPI schema information for POJOs serialized through OpenApiSerializer and parsed through OpenApiParser.

Examples:

// A response object thats a hex-encoded string @Response( schema=@Schema( type="string", format="binary" ) )

// Free-form @Response( schema=@Schema({ "type:'string',", "format:'binary'" }) )

// A request body consisting of an array of arrays, the internal array being of type integer, numbers must be between 0 and 63 (inclusive) @Body( schema=@Schema( items=@Items( type="array", items=@SubItems( type="integer", minimum="0", maximum="63" ) ) ) )

See Also:

• Overview > juneau-rest-server > Swagger
• Swagger Schema Object

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
String[]	_default default field of the Swagger Schema Object.
String[]	_enum enum field of the Swagger Schema Object.
String	$ref $ref field of the Swagger Schema Object.
String[]	additionalProperties additionalProperties field of the Swagger Schema Object.
String[]	allOf allOf field of the Swagger Schema Object.
String	collectionFormat collectionFormat field.
String[]	description description field of the Swagger Schema Object.
String	discriminator discriminator field of the Swagger Schema Object.
String[]	example example field of the Swagger Schema Object.
String[]	examples x-examples field of the Swagger Schema Object.
boolean	exclusiveMaximum exclusiveMaximum field of the Swagger Schema Object.
boolean	exclusiveMinimum exclusiveMinimum field of the Swagger Schema Object.
ExternalDocs	externalDocs externalDocs field of the Swagger Schema Object.
String	format format field of the Swagger Schema Object.
boolean	ignore Specifies that schema information for this part should not be shown in the generated Swagger documentation.
Items	items items field of the Swagger Schema Object.
String	maximum maximum field of the Swagger Schema Object.
long	maxItems maxItems field of the Swagger Schema Object.
long	maxLength maxLength field of the Swagger Schema Object.
long	maxProperties maxProperties field of the Swagger Schema Object.
String	minimum minimum field of the Swagger Schema Object.
long	minItems minItems field of the Swagger Schema Object.
long	minLength minLength field of the Swagger Schema Object.
long	minProperties minProperties field of the Swagger Schema Object.
String	multipleOf multipleOf field of the Swagger Schema Object.
String	pattern pattern field of the Swagger Schema Object.
String[]	properties properties field of the Swagger Schema Object.
boolean	readOnly readOnly field of the Swagger Schema Object.
boolean	required required field of the Swagger Schema Object.
String	title title field of the Swagger Schema Object.
String	type type field of the Swagger Schema Object.
boolean	uniqueItems uniqueItems field of the Swagger Schema Object.
String[]	value Free-form value for the Swagger Schema Object.
String[]	xml xml field of the Swagger Schema Object.

Element Detail

$ref

public abstract String $ref

$ref field of the Swagger Schema Object.

A JSON reference to the schema definition.

Notes:

• The format is a JSON Reference.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

""

format

public abstract String format

format field of the Swagger Schema Object.

Examples:

// Used on parameter @RestMethod(name=PUT) public void setAge( @Body(type="integer", format="int32") String input ) {...}

Notes:

• The format is plain text.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

See Also:

• Swagger Data Type Formats

Default:

""

title

public abstract String title

title field of the Swagger Schema Object.

Notes:

• The format is plain text.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

""

description

public abstract String[] description

description field of the Swagger Schema Object.

A brief description of the body. This could contain examples of use.

Examples:

// Used on parameter @RestMethod(name=POST) public void addPet( @Body(description="Pet object to add to the store") Pet input ) {...}

// Used on class @RestMethod(name=POST) public void addPet(Pet input) {...} @Body(description="Pet object to add to the store") public class Pet {...}

Notes:

• The format is plain text.
  Multiple lines are concatenated with newlines.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

{}

_default

public abstract String[] _default

default field of the Swagger Schema Object.

Notes:

• The format is any Overview > juneau-marshall > JSON Details > Simplified JSON.
  Multiple lines are concatenated with newlines.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

{}

multipleOf

public abstract String multipleOf

multipleOf field of the Swagger Schema Object.

Notes:

• The format is numeric.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

""

maximum

public abstract String maximum

maximum field of the Swagger Schema Object.

Notes:

• The format is numeric.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

""

exclusiveMaximum

public abstract boolean exclusiveMaximum

exclusiveMaximum field of the Swagger Schema Object.

Notes:

• The format is numeric.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

false

minimum

public abstract String minimum

minimum field of the Swagger Schema Object.

Notes:

• The format is numeric.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

""

exclusiveMinimum

public abstract boolean exclusiveMinimum

exclusiveMinimum field of the Swagger Schema Object.

Notes:

• The format is numeric.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

false

maxLength

public abstract long maxLength

maxLength field of the Swagger Schema Object.

Notes:

• The format is numeric.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

-1L

minLength

public abstract long minLength

minLength field of the Swagger Schema Object.

Notes:

• The format is numeric.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

-1L

pattern

public abstract String pattern

pattern field of the Swagger Schema Object.

Example:

@RestMethod(name=PUT) public void doPut(@Body(format="/\\w+\\.\\d+/") String input) {...}

Notes:

• The format is plain text.
• This string SHOULD be a valid regular expression.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

""

maxItems

public abstract long maxItems

maxItems field of the Swagger Schema Object.

Notes:

• The format is numeric.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

-1L

minItems

public abstract long minItems

minItems field of the Swagger Schema Object.

Notes:

• The format is numeric.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

-1L

uniqueItems

public abstract boolean uniqueItems

uniqueItems field of the Swagger Schema Object.

Notes:

• The format is boolean.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

false

maxProperties

public abstract long maxProperties

maxProperties field of the Swagger Schema Object.

Notes:

• The format is a Overview > juneau-marshall > JSON Details > Simplified JSON object.
  Multiple lines are concatenated with newlines.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

-1L

minProperties

public abstract long minProperties

minProperties field of the Swagger Schema Object.

Notes:

• The format is a Overview > juneau-marshall > JSON Details > Simplified JSON object.
  Multiple lines are concatenated with newlines.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

-1L

required

public abstract boolean required

required field of the Swagger Schema Object.

Determines whether this parameter is mandatory.
The property MAY be included and its default value is false.

Examples:

// Used on parameter @RestMethod(name=POST) public void addPet( @Body(required=true) Pet input ) {...}

// Used on class @RestMethod(name=POST) public void addPet(Pet input) {...} @Body(required=true) public class Pet {...}

Notes:

• The format is boolean.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

false

_enum

public abstract String[] _enum

enum field of the Swagger Schema Object.

Notes:

• The format is a Overview > juneau-marshall > JSON Details > Simplified JSON array or comma-delimited list.
  Multiple lines are concatenated with newlines.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

{}

type

public abstract String type

type field of the Swagger Schema Object.

Examples:

// Used on parameter @RestMethod(name=POST) public void addPet( @Body(type="object") Pet input ) {...}

// Used on class @RestMethod(name=POST) public void addPet(Pet input) {...} @Body(type="object") public class Pet {...}

Notes:

• The format is plain text.
• The possible values are:
  • "object"
  • "string"
  • "number"
  • "integer"
  • "boolean"
  • "array"
  • "file"
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

See Also:

• Swagger Data Types

Default:

""

items

public abstract Items items

items field of the Swagger Schema Object.

Notes:

• The format is a Overview > juneau-marshall > JSON Details > Simplified JSON object.
  Multiple lines are concatenated with newlines.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

@org.apache.juneau.jsonschema.annotation.Items

collectionFormat

public abstract String collectionFormat

collectionFormat field.

Note that this field isn't part of the Swagger 2.0 specification, but the specification does not specify how items are supposed to be represented.

Determines the format of the array if type "array" is used.
Can only be used if type is "array".
Possible values are:

• "csv" (default) - Comma-separated values (e.g. "foo,bar").
• "ssv" - Space-separated values (e.g. "foo bar").
• "tsv" - Tab-separated values (e.g. "foo\tbar").
• "pipes - Pipe-separated values (e.g. "foo|bar").
• "multi" - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. "foo=bar&foo=baz").
• "uon" - UON notation (e.g. "@(foo,bar)").

Static strings are defined in CollectionFormatType.

Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements.

Used for:

• Server-side schema-based parsing.
• Server-side generated Swagger documentation.
• Client-side schema-based serializing.

Default:

""

allOf

public abstract String[] allOf

allOf field of the Swagger Schema Object.

Notes:

• The format is a Overview > juneau-marshall > JSON Details > Simplified JSON object.
  Multiple lines are concatenated with newlines.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

{}

properties

public abstract String[] properties

properties field of the Swagger Schema Object.

Notes:

• The format is a Overview > juneau-marshall > JSON Details > Simplified JSON object.
  Multiple lines are concatenated with newlines.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

{}

additionalProperties

public abstract String[] additionalProperties

additionalProperties field of the Swagger Schema Object.

Notes:

• The format is a Overview > juneau-marshall > JSON Details > Simplified JSON object.
  Multiple lines are concatenated with newlines.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

{}

discriminator

public abstract String discriminator

discriminator field of the Swagger Schema Object.

Notes:

• The format is a Overview > juneau-marshall > JSON Details > Simplified JSON object.
  Multiple lines are concatenated with newlines.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

""

readOnly

public abstract boolean readOnly

readOnly field of the Swagger Schema Object.

Notes:

• The format is a Overview > juneau-marshall > JSON Details > Simplified JSON object.
  Multiple lines are concatenated with newlines.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

false

xml

public abstract String[] xml

xml field of the Swagger Schema Object.

Notes:

• The format is a Overview > juneau-marshall > JSON Details > Simplified JSON object.
  Multiple lines are concatenated with newlines.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

{}

externalDocs

public abstract ExternalDocs externalDocs

externalDocs field of the Swagger Schema Object.

Notes:

• The format is a Overview > juneau-marshall > JSON Details > Simplified JSON object.
  Multiple lines are concatenated with newlines.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

@org.apache.juneau.jsonschema.annotation.ExternalDocs

example

public abstract String[] example

example field of the Swagger Schema Object.

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

This attribute defines a JSON representation of the body value that is used by BasicRestInfoProvider to construct media-type-based examples of the body of the request.

Notes:

• The format is a Overview > juneau-marshall > JSON Details > Simplified JSON object or plain text string.
  Multiple lines are concatenated with newlines.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

{}

examples

public abstract String[] examples

x-examples field of the Swagger Schema Object.

This is a JSON object whose keys are media types and values are string representations of that value.

Notes:

• The format is a Overview > juneau-marshall > JSON Details > Simplified JSON object.
  Multiple lines are concatenated with newlines.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").

Default:

{}

ignore

public abstract boolean ignore

Specifies that schema information for this part should not be shown in the generated Swagger documentation.

Default:

false

value

public abstract String[] value

Free-form value for the Swagger Schema Object.

This is a JSON object that makes up the swagger information for this field.

The following are completely equivalent ways of defining the swagger description of a Schema object:

// Normal @Schema( type="array", items=@Items( $ref="#/definitions/Pet" ) )

// Free-form @Schema( "type: 'array',", "items: {", "$ref: '#/definitions/Pet'", "}" )

// Free-form using variables @Schema("$L{petArraySwagger}")

// Contents of MyResource.properties petArraySwagger = { type: "array", items: { $ref: "#/definitions/Pet" } }

The reasons why you may want to use this field include:

• You want to pull in the entire Swagger JSON definition for this field from an external source such as a properties file.
• You want to add extra fields to the Swagger documentation that are not officially part of the Swagger specification.

Notes:

• The format is a Overview > juneau-marshall > JSON Details > Simplified JSON object.
• The leading/trailing { } characters are optional.
  The following two example are considered equivalent:

  @Schema("{type: 'array'}")

  @Schema("type: 'array'")

• Multiple lines are concatenated with newlines so that you can format the value to be readable.
• Supports Default REST SVL Variables (e.g. "$L{my.localized.variable}").
• Values defined in this field supersede values pulled from the Swagger JSON file and are superseded by individual values defined on this annotation.

Default:

{}