001// ***************************************************************************************************************************
002// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements.  See the NOTICE file *
003// * distributed with this work for additional information regarding copyright ownership.  The ASF licenses this file        *
004// * to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance            *
005// * with the License.  You may obtain a copy of the License at                                                              *
006// *                                                                                                                         *
007// *  http://www.apache.org/licenses/LICENSE-2.0                                                                             *
008// *                                                                                                                         *
009// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an  *
010// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the License for the        *
011// * specific language governing permissions and limitations under the License.                                              *
012// ***************************************************************************************************************************
013package org.apache.juneau.annotation;
014
015import static java.lang.annotation.ElementType.*;
016import static java.lang.annotation.RetentionPolicy.*;
017
018import java.lang.annotation.*;
019import java.util.*;
020
021import org.apache.juneau.collections.*;
022import org.apache.juneau.http.annotation.*;
023import org.apache.juneau.httppart.*;
024import org.apache.juneau.oapi.*;
025
026/**
027 * Swagger schema annotation.
028 *
029 * <p>
030 * The Schema Object allows the definition of input and output data types.
031 * These types can be objects, but also primitives and arrays.
032 * This object is based on the JSON Schema Specification Draft 4 and uses a predefined subset of it.
033 * On top of this subset, there are extensions provided by this specification to allow for more complete documentation.
034 *
035 * <p>
036 * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@Rest</ja>-annotated classes.
037 * <br>Also used to define OpenAPI schema information for POJOs serialized through {@link OpenApiSerializer} and parsed through {@link OpenApiParser}.
038 *
039 * <h5 class='section'>Examples:</h5>
040 * <p class='bjava'>
041 *    <jc>// A response object thats a hex-encoded string</jc>
042 *    <ja>@Response</ja>(
043 *       schema=<ja>@Schema</ja>(
044 *          type=<js>"string"</js>,
045 *          format=<js>"binary"</js>
046 *       )
047 *    )
048 * </p>
049 * <p class='bjava'>
050 *    <jc>// A request body consisting of an array of arrays, the internal
051 *    // array being of type integer, numbers must be between 0 and 63 (inclusive)</jc>
052 *    <ja>@Content</ja>(
053 *       schema=<ja>@Schema</ja>(
054 *          items=<ja>@Items</ja>(
055 *             type=<js>"array"</js>,
056 *             items=<ja>@SubItems</ja>(
057 *                type=<js>"integer"</js>,
058 *                minimum=<js>"0"</js>,
059 *                maximum=<js>"63"</js>
060 *             )
061 *       )
062 *       )
063 *    )
064 * </p>
065 *
066 * <h5 class='section'>See Also:</h5><ul>
067 *    <li class='link'><a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a>
068 *    <li class='extlink'><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>
069
070 * </ul>
071 */
072@Documented
073@Target({PARAMETER,METHOD,TYPE,FIELD})
074@Retention(RUNTIME)
075@Repeatable(SchemaAnnotation.Array.class)
076@ContextApply(SchemaAnnotation.Apply.class)
077public @interface Schema {
078
079   /**
080    * <mk>default</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
081    *
082    * <p>
083    * Declares the value of the parameter that the server will use if none is provided, for example a "count" to control the number of results per page might default to 100 if not supplied by the client in the request.
084    * <br>(Note: "default" has no meaning for required parameters.)
085    *
086    * <p>
087    * Additionally, this value is used to create instances of POJOs that are then serialized as language-specific examples in the generated Swagger documentation
088    * if the examples are not defined in some other way.
089    *
090    * <p>
091    * The format of this value is a string.
092    * <br>Multiple lines are concatenated with newlines.
093    *
094    * <h5 class='section'>Examples:</h5>
095    * <p class='bjava'>
096    *    <jk>public</jk> Order placeOrder(
097    *       <ja>@Header</ja>(<js>"X-PetId"</js>)
098    *       <ja>@Schema</ja>(_default=<js>"100"</js>)
099    *       <jk>long</jk> <jv>petId</jv>,
100    *
101    *       <ja>@Header</ja>(<js>"X-AdditionalInfo"</js>)
102    *       <ja>@Schema</ja>(format=<js>"uon"</js>, _default=<js>"(rushOrder=false)"</js>)
103    *       AdditionalInfo <jv>additionalInfo</jv>,
104    *
105    *       <ja>@Header</ja>(<js>"X-Flags"</js>)
106    *       <ja>@Schema</ja>(collectionFormat=<js>"uon"</js>, _default=<js>"@(new-customer)"</js>)
107    *       String[] <jv>flags</jv>
108    *    ) {...}
109    * </p>
110    *
111    * <h5 class='section'>Used for:</h5>
112    * <ul class='spaced-list'>
113    *    <li>
114    *       Server-side schema-based parsing.
115    *    <li>
116    *       Server-side generated Swagger documentation.
117    *    <li>
118    *       Client-side schema-based serializing.
119    * </ul>
120    *
121    * @return The annotation value.
122    */
123   String[] _default() default {};
124
125   /**
126    * <mk>enum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
127    *
128    * <p>
129    * If specified, the input validates successfully if it is equal to one of the elements in this array.
130    *
131    * <p>
132    * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
133    * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made.
134    * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400).
135    *
136    * <p>
137    * The format is either individual values or a comma-delimited list.
138    * <br>Multiple lines are concatenated with newlines.
139    *
140    * <h5 class='section'>Examples:</h5>
141    * <p class='bjava'>
142    *    <jc>// Comma-delimited list</jc>
143    *    <jk>public</jk> Collection&lt;Pet&gt; findPetsByStatus(
144    *       <ja>@Header</ja>(<js>"X-Status"</js>)
145    *       <ja>@Schema</ja>(_enum=<js>"AVAILABLE,PENDING,SOLD"</js>)
146    *       PetStatus <jv>status</jv>
147    *    ) {...}
148    * </p>
149    *
150    * <h5 class='section'>Used for:</h5>
151    * <ul class='spaced-list'>
152    *    <li>
153    *       Server-side schema-based parsing validation.
154    *    <li>
155    *       Server-side generated Swagger documentation.
156    *    <li>
157    *       Client-side schema-based serializing validation.
158    * </ul>
159    *
160    * @return The annotation value.
161    */
162   String[] _enum() default {};
163
164   /**
165    * <mk>$ref</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
166    *
167    * <p>
168    *    A JSON reference to the schema definition.
169    *
170    * <h5 class='section'>Notes:</h5><ul>
171    *    <li class='note'>
172    *       The format is a <a href='https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03'>JSON Reference</a>.
173    * </ul>
174    *
175    * @return The annotation value.
176    */
177   String $ref() default "";
178
179   /**
180    * <mk>additionalProperties</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
181    *
182    * <h5 class='section'>Notes:</h5><ul>
183    *    <li class='note'>
184    *       The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object.
185    *       <br>Multiple lines are concatenated with newlines.
186    * </ul>
187    *
188    * @return The annotation value.
189    */
190   String[] additionalProperties() default {};
191
192   /**
193    * <mk>allOf</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
194    *
195    * <h5 class='section'>Notes:</h5><ul>
196    *    <li class='note'>
197    *       The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object.
198    *       <br>Multiple lines are concatenated with newlines.
199    * </ul>
200    *
201    * @return The annotation value.
202    */
203   String[] allOf() default {};
204
205   /**
206    * Synonym for {@link #allowEmptyValue()}.
207    *
208    * @return The annotation value.
209    */
210   boolean aev() default false;
211
212   /**
213    * <mk>allowEmptyValue</mk> field of the <a class='doclink' href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter Object</a>.
214    *
215    * <p>
216    * Sets the ability to pass empty-valued heaver values.
217    *
218    * <h5 class='section'>Used for:</h5>
219    * <ul class='spaced-list'>
220    *    <li>
221    *       Server-side schema-based parsing validation.
222    *    <li>
223    *       Server-side generated Swagger documentation.
224    *    <li>
225    *       Client-side schema-based serializing validation.
226    * </ul>
227    *
228    * <p>
229    * <b>Note:</b>  This is technically only valid for either query or formData parameters, but support is provided anyway for backwards compatability.
230    *
231    * @return The annotation value.
232    */
233   boolean allowEmptyValue() default false;
234
235   /**
236    * Synonym for {@link #collectionFormat()}.
237    *
238    * @return The annotation value.
239    */
240   String cf() default "";
241
242   /**
243    * <mk>collectionFormat</mk> field.
244    *
245    * <p>
246    * Note that this field isn't part of the Swagger 2.0 specification, but the specification does not specify how
247    * items are supposed to be represented.
248    *
249    * <p>
250    * Determines the format of the array if <c>type</c> <js>"array"</js> is used.
251    * <br>Can only be used if <c>type</c> is <js>"array"</js>.
252    *
253    * <p>
254    * Static strings are defined in {@link CollectionFormatType}.
255    *
256    * <p>
257    * Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements.
258    *
259    * <h5 class='section'>Used for:</h5>
260    * <ul class='spaced-list'>
261    *    <li>
262    *       Server-side schema-based parsing.
263    *    <li>
264    *       Server-side generated Swagger documentation.
265    *    <li>
266    *       Client-side schema-based serializing.
267    * </ul>
268    *
269    * <p>
270    * Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements.
271    *
272    * <ul class='values'>
273    *    <li><js>"csv"</js> (default) - Comma-separated values (e.g. <js>"foo,bar"</js>).
274    *    <li><js>"ssv"</js> - Space-separated values (e.g. <js>"foo bar"</js>).
275    *    <li><js>"tsv"</js> - Tab-separated values (e.g. <js>"foo\tbar"</js>).
276    *    <li><js>"pipes</js> - Pipe-separated values (e.g. <js>"foo|bar"</js>).
277    *    <li><js>"multi"</js> - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. <js>"foo=bar&amp;foo=baz"</js>).
278    *    <li><js>"uon"</js> - UON notation (e.g. <js>"@(foo,bar)"</js>).
279    * </ul>
280    *
281    * @return The annotation value.
282    */
283   String collectionFormat() default "";
284
285   /**
286    * Synonym for {@link #description()}.
287    *
288    * @return The annotation value.
289    */
290   String[] d() default {};
291
292   /**
293    * <mk>description</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
294    *
295    * <p>
296    * A brief description of the body. This could contain examples of use.
297    *
298    * <h5 class='section'>Examples:</h5>
299    * <p class='bjava'>
300    *    <jc>// Used on parameter</jc>
301    *    <ja>@RestPost</ja>
302    *    <jk>public void</jk> addPet(
303    *       <ja>@Content</ja> <ja>@Schema</ja>(description=<js>"Pet object to add to the store"</js>) Pet <jv>input</jv>
304    *    ) {...}
305    * </p>
306    * <p class='bjava'>
307    *    <jc>// Used on class</jc>
308    *    <ja>@RestPost</ja>
309    *    <jk>public void</jk> addPet(Pet <jv>input</jv>) {...}
310    *
311    *    <ja>@Content</ja> <ja>@Schema</ja>(description=<js>"Pet object to add to the store"</js>)
312    *    <jk>public class</jk> Pet {...}
313    * </p>
314    *
315    * <h5 class='section'>Notes:</h5><ul>
316    *    <li class='note'>
317    *       The format is plain text.
318    *       <br>Multiple lines are concatenated with newlines.
319    *    <li class='note'>
320    *       Supports <a class="doclink" href="../../../../index.html#jrs.SvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>) for the swagger generator.
321    * </ul>
322    *
323    * @return The annotation value.
324    */
325   String[] description() default {};
326
327   /**
328    * Synonym for {@link #_default()}.
329    *
330    * @return The annotation value.
331    */
332   String[] df() default {};
333
334   /**
335    * <mk>discriminator</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
336    *
337    * <h5 class='section'>Notes:</h5><ul>
338    *    <li class='note'>
339    *       The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object.
340    *       <br>Multiple lines are concatenated with newlines.
341    * </ul>
342    *
343    * @return The annotation value.
344    */
345   String discriminator() default "";
346
347   /**
348    * Synonym for {@link #_enum()}.
349    *
350    * @return The annotation value.
351    */
352   String[] e() default {};
353
354   /**
355    * Synonym for {@link #exclusiveMaximum()}.
356    *
357    * @return The annotation value.
358    */
359   boolean emax() default false;
360
361   /**
362    * Synonym for {@link #exclusiveMinimum()}.
363    *
364    * @return The annotation value.
365    */
366   boolean emin() default false;
367
368   /**
369    * <mk>exclusiveMaximum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
370    *
371    * <p>
372    * Defines whether the maximum is matched exclusively.
373    *
374    * <p>
375    * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
376    * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made.
377    * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400).
378    *
379    * <p>
380    * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>.
381    * <br>If <jk>true</jk>, must be accompanied with <c>maximum</c>.
382    *
383    * <h5 class='section'>Used for:</h5>
384    * <ul class='spaced-list'>
385    *    <li>
386    *       Server-side schema-based parsing validation.
387    *    <li>
388    *       Server-side generated Swagger documentation.
389    *    <li>
390    *       Client-side schema-based serializing validation.
391    * </ul>
392    *
393    * @return The annotation value.
394    */
395   boolean exclusiveMaximum() default false;
396
397   /**
398    * <mk>exclusiveMinimum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
399    *
400    * <p>
401    * Defines whether the minimum is matched exclusively.
402    *
403    * <p>
404    * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
405    * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made.
406    * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400).
407    *
408    * <p>
409    * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>.
410    * <br>If <jk>true</jk>, must be accompanied with <c>minimum</c>.
411    *
412    * <h5 class='section'>Used for:</h5>
413    * <ul class='spaced-list'>
414    *    <li>
415    *       Server-side schema-based parsing validation.
416    *    <li>
417    *       Server-side generated Swagger documentation.
418    *    <li>
419    *       Client-side schema-based serializing validation.
420    * </ul>
421    *
422    * @return The annotation value.
423    */
424   boolean exclusiveMinimum() default false;
425
426   /**
427    * <mk>externalDocs</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
428    *
429    * <h5 class='section'>Notes:</h5><ul>
430    *    <li class='note'>
431    *       The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object.
432    *       <br>Multiple lines are concatenated with newlines.
433    * </ul>
434    *
435    * @return The annotation value.
436    */
437   ExternalDocs externalDocs() default @ExternalDocs;
438
439   /**
440    * Synonym for {@link #format()}.
441    *
442    * @return The annotation value.
443    */
444   String f() default "";
445
446   /**
447    * <mk>format</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
448    *
449    * <p>
450    * The extending format for the previously mentioned <a class="doclink" href="https://swagger.io/specification/v2#parameterType">parameter type</a>.
451    *
452    * <p>
453    * Static strings are defined in {@link FormatType}.
454    *
455    * <h5 class='section'>Examples:</h5>
456    * <p class='bjava'>
457    *    <jc>// Used on parameter</jc>
458    *    <ja>@RestPut</ja>
459    *    <jk>public void</jk> setAge(
460    *       <ja>@Content</ja> <ja>@Schema</ja>(type=<js>"integer"</js>, format=<js>"int32"</js>) String <jv>input</jv>
461    *    ) {...}
462    * </p>
463    *
464    * <h5 class='section'>Used for:</h5>
465    * <ul class='spaced-list'>
466    *    <li>
467    *       Server-side schema-based parsing.
468    *    <li>
469    *       Server-side generated Swagger documentation.
470    *    <li>
471    *       Client-side schema-based serializing.
472    * </ul>
473    *
474    * <ul class='values'>
475    *    <li>
476    *       <js>"int32"</js> - Signed 32 bits.
477    *       <br>Only valid with type <js>"integer"</js>.
478    *    <li>
479    *       <js>"int64"</js> - Signed 64 bits.
480    *       <br>Only valid with type <js>"integer"</js>.
481    *    <li>
482    *       <js>"float"</js> - 32-bit floating point number.
483    *       <br>Only valid with type <js>"number"</js>.
484    *    <li>
485    *       <js>"double"</js> - 64-bit floating point number.
486    *       <br>Only valid with type <js>"number"</js>.
487    *    <li>
488    *       <js>"byte"</js> - BASE-64 encoded characters.
489    *       <br>Only valid with type <js>"string"</js>.
490    *       <br>Parameters of type POJO convertible from string are converted after the string has been decoded.
491    *    <li>
492    *       <js>"binary"</js> - Hexadecimal encoded octets (e.g. <js>"00FF"</js>).
493    *       <br>Only valid with type <js>"string"</js>.
494    *       <br>Parameters of type POJO convertible from string are converted after the string has been decoded.
495    *    <li>
496    *       <js>"date"</js> - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 full-date</a>.
497    *       <br>Only valid with type <js>"string"</js>.
498    *    <li>
499    *       <js>"date-time"</js> - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 date-time</a>.
500    *       <br>Only valid with type <js>"string"</js>.
501    *    <li>
502    *       <js>"password"</js> - Used to hint UIs the input needs to be obscured.
503    *       <br>This format does not affect the serialization or parsing of the parameter.
504    *    <li>
505    *       <js>"uon"</js> - UON notation (e.g. <js>"(foo=bar,baz=@(qux,123))"</js>).
506    *       <br>Only valid with type <js>"object"</js>.
507    *       <br>If not specified, then the input is interpreted as plain-text and is converted to a POJO directly.
508    * </ul>
509    *
510    * <h5 class='section'>Notes:</h5><ul>
511    *    <li class='note'>
512    *       The format is plain text.
513    * </ul>
514    *
515    * <h5 class='section'>See Also:</h5><ul>
516    *    <li class='extlink'><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>
517    * </ul>
518    *
519    * @return The annotation value.
520    */
521   String format() default "";
522
523   /**
524    * Specifies that schema information for this part should not be shown in the generated Swagger documentation.
525    *
526    * @return The annotation value.
527    */
528   boolean ignore() default false;
529
530   /**
531    * <mk>items</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
532    *
533    * <p>
534    * Describes the type of items in the array.
535    *
536    * <p>
537    * Required if <c>type</c> is <js>"array"</js>.
538    * <br>Can only be used if <c>type</c> is <js>"array"</js>.
539    *
540    * <h5 class='section'>Used for:</h5>
541    * <ul class='spaced-list'>
542    *    <li>
543    *       Server-side schema-based parsing and parsing validation.
544    *    <li>
545    *       Server-side generated Swagger documentation.
546    *    <li>
547    *       Client-side schema-based serializing and serializing validation.
548    * </ul>
549    *
550    * @return The annotation value.
551    */
552   Items items() default @Items;
553
554   /**
555    * Synonym for {@link #maximum()}.
556    *
557    * @return The annotation value.
558    */
559   String max() default "";
560
561   /**
562    * Synonym for {@link #maxItems()}.
563    *
564    * @return The annotation value.
565    */
566   long maxi() default -1;
567
568   /**
569    * <mk>maximum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
570    *
571    * <p>
572    * Defines the maximum value for a parameter of numeric types.
573    * <br>The value must be a valid JSON number.
574    *
575    * <p>
576    * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
577    * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made.
578    * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400).
579    *
580    * <p>
581    * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>.
582    *
583    * <h5 class='section'>Used for:</h5>
584    * <ul class='spaced-list'>
585    *    <li>
586    *       Server-side schema-based parsing validation.
587    *    <li>
588    *       Server-side generated Swagger documentation.
589    *    <li>
590    *       Client-side schema-based serializing validation.
591    * </ul>
592    *
593    * @return The annotation value.
594    */
595   String maximum() default "";
596
597   /**
598    * <mk>maxItems</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
599    *
600    * <p>
601    * An array or collection is valid if its size is less than, or equal to, the value of this keyword.
602    *
603    * <p>
604    * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
605    * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made.
606    * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400).
607    *
608    * <p>
609    * Only allowed for the following types: <js>"array"</js>.
610    *
611    * <h5 class='section'>Used for:</h5>
612    * <ul class='spaced-list'>
613    *    <li>
614    *       Server-side schema-based parsing validation.
615    *    <li>
616    *       Server-side generated Swagger documentation.
617    *    <li>
618    *       Client-side schema-based serializing validation.
619    * </ul>
620    *
621    * @return The annotation value.
622    */
623   long maxItems() default -1;
624
625   /**
626    * Synonym for {@link #maxLength()}.
627    *
628    * @return The annotation value.
629    */
630   long maxl() default -1;
631
632   /**
633    * <mk>maxLength</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
634    *
635    * <p>
636    * A string instance is valid against this keyword if its length is less than, or equal to, the value of this keyword.
637    * <br>The length of a string instance is defined as the number of its characters as defined by <a href='https://tools.ietf.org/html/rfc4627'>RFC 4627</a>.
638    * <br>The value <c>-1</c> is always ignored.
639    *
640    * <p>
641    * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
642    * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made.
643    * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400).
644    *
645    * <p>
646    * Only allowed for the following types: <js>"string"</js>.
647    *
648    * <h5 class='section'>Used for:</h5>
649    * <ul class='spaced-list'>
650    *    <li>
651    *       Server-side schema-based parsing validation.
652    *    <li>
653    *       Server-side generated Swagger documentation.
654    *    <li>
655    *       Client-side schema-based serializing validation.
656    * </ul>
657    *
658    * @return The annotation value.
659    */
660   long maxLength() default -1;
661
662   /**
663    * Synonym for {@link #maxProperties()}.
664    *
665    * @return The annotation value.
666    */
667   long maxp() default -1;
668
669   /**
670    * <mk>maxProperties</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
671    *
672    * <h5 class='section'>Notes:</h5><ul>
673    *    <li class='note'>
674    *       The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object.
675    *       <br>Multiple lines are concatenated with newlines.
676    * </ul>
677    *
678    * @return The annotation value.
679    */
680   long maxProperties() default -1;
681
682   /**
683    * Synonym for {@link #minimum()}.
684    *
685    * @return The annotation value.
686    */
687   String min() default "";
688
689   /**
690    * Synonym for {@link #minItems()}.
691    *
692    * @return The annotation value.
693    */
694   long mini() default -1;
695
696   /**
697    * <mk>minimum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
698    *
699    * <p>
700    * Defines the minimum value for a parameter of numeric types.
701    * <br>The value must be a valid JSON number.
702    *
703    * <p>
704    * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
705    * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made.
706    * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400).
707    *
708    * <p>
709    * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>.
710    *
711    * <h5 class='section'>Used for:</h5>
712    * <ul class='spaced-list'>
713    *    <li>
714    *       Server-side schema-based parsing validation.
715    *    <li>
716    *       Server-side generated Swagger documentation.
717    *    <li>
718    *       Client-side schema-based serializing validation.
719    * </ul>
720    *
721    * @return The annotation value.
722    */
723   String minimum() default "";
724
725   /**
726    * <mk>minItems</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
727    *
728    * <p>
729    * An array or collection is valid if its size is greater than, or equal to, the value of this keyword.
730    *
731    * <p>
732    * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
733    * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made.
734    * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400).
735    *
736    * <p>
737    * Only allowed for the following types: <js>"array"</js>.
738    *
739    * <h5 class='section'>Used for:</h5>
740    * <ul class='spaced-list'>
741    *    <li>
742    *       Server-side schema-based parsing validation.
743    *    <li>
744    *       Server-side generated Swagger documentation.
745    *    <li>
746    *       Client-side schema-based serializing validation.
747    * </ul>
748    *
749    * @return The annotation value.
750    */
751   long minItems() default -1;
752
753   /**
754    * Synonym for {@link #minLength()}.
755    *
756    * @return The annotation value.
757    */
758   long minl() default -1;
759
760   /**
761    * <mk>minLength</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
762    *
763    * <p>
764    * A string instance is valid against this keyword if its length is greater than, or equal to, the value of this keyword.
765    * <br>The length of a string instance is defined as the number of its characters as defined by <a href='https://tools.ietf.org/html/rfc4627'>RFC 4627</a>.
766    * <br>The value <c>-1</c> is always ignored.
767    *
768    * <p>
769    * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
770    * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made.
771    * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400).
772    *
773    * <p>
774    * Only allowed for the following types: <js>"string"</js>.
775    *
776    * <h5 class='section'>Used for:</h5>
777    * <ul class='spaced-list'>
778    *    <li>
779    *       Server-side schema-based parsing validation.
780    *    <li>
781    *       Server-side generated Swagger documentation.
782    *    <li>
783    *       Client-side schema-based serializing validation.
784    * </ul>
785    *
786    * @return The annotation value.
787    */
788   long minLength() default -1;
789
790   /**
791    * Synonym for {@link #minProperties()}.
792    *
793    * @return The annotation value.
794    */
795   long minp() default -1;
796
797   /**
798    * <mk>minProperties</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
799    *
800    * <h5 class='section'>Notes:</h5><ul>
801    *    <li class='note'>
802    *       The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object.
803    *       <br>Multiple lines are concatenated with newlines.
804    * </ul>
805    *
806    * @return The annotation value.
807    */
808   long minProperties() default -1;
809
810   /**
811    * Synonym for {@link #multipleOf()}.
812    *
813    * @return The annotation value.
814    */
815   String mo() default "";
816
817   /**
818    * <mk>multipleOf</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
819    *
820    * <p>
821    * A numeric instance is valid if the result of the division of the instance by this keyword's value is an integer.
822    * <br>The value must be a valid JSON number.
823    *
824    * <p>
825    * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
826    * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made.
827    * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400).
828    *
829    * <p>
830    * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>.
831    *
832    * <h5 class='section'>Used for:</h5>
833    * <ul class='spaced-list'>
834    *    <li>
835    *       Server-side schema-based parsing validation.
836    *    <li>
837    *       Server-side generated Swagger documentation.
838    *    <li>
839    *       Client-side schema-based serializing validation.
840    * </ul>
841    *
842    * @return The annotation value.
843    */
844   String multipleOf() default "";
845
846   /**
847    * Dynamically apply this annotation to the specified classes/methods/fields.
848    *
849    * <p>
850    * Used in conjunction with {@link org.apache.juneau.BeanContext.Builder#applyAnnotations(Class...)} to dynamically apply an annotation to an existing class/method/field.
851    * It is ignored when the annotation is applied directly to classes/methods/fields.
852    *
853    * <h5 class='section'>Valid patterns:</h5>
854    * <ul class='spaced-list'>
855    *  <li>Classes:
856    *       <ul>
857    *          <li>Fully qualified:
858    *             <ul>
859    *                <li><js>"com.foo.MyClass"</js>
860    *             </ul>
861    *          <li>Fully qualified inner class:
862    *             <ul>
863    *                <li><js>"com.foo.MyClass$Inner1$Inner2"</js>
864    *             </ul>
865    *          <li>Simple:
866    *             <ul>
867    *                <li><js>"MyClass"</js>
868    *             </ul>
869    *          <li>Simple inner:
870    *             <ul>
871    *                <li><js>"MyClass$Inner1$Inner2"</js>
872    *                <li><js>"Inner1$Inner2"</js>
873    *                <li><js>"Inner2"</js>
874    *             </ul>
875    *       </ul>
876    *    <li>Methods:
877    *       <ul>
878    *          <li>Fully qualified with args:
879    *             <ul>
880    *                <li><js>"com.foo.MyClass.myMethod(String,int)"</js>
881    *                <li><js>"com.foo.MyClass.myMethod(java.lang.String,int)"</js>
882    *                <li><js>"com.foo.MyClass.myMethod()"</js>
883    *             </ul>
884    *          <li>Fully qualified:
885    *             <ul>
886    *                <li><js>"com.foo.MyClass.myMethod"</js>
887    *             </ul>
888    *          <li>Simple with args:
889    *             <ul>
890    *                <li><js>"MyClass.myMethod(String,int)"</js>
891    *                <li><js>"MyClass.myMethod(java.lang.String,int)"</js>
892    *                <li><js>"MyClass.myMethod()"</js>
893    *             </ul>
894    *          <li>Simple:
895    *             <ul>
896    *                <li><js>"MyClass.myMethod"</js>
897    *             </ul>
898    *          <li>Simple inner class:
899    *             <ul>
900    *                <li><js>"MyClass$Inner1$Inner2.myMethod"</js>
901    *                <li><js>"Inner1$Inner2.myMethod"</js>
902    *                <li><js>"Inner2.myMethod"</js>
903    *             </ul>
904    *       </ul>
905    *    <li>Fields:
906    *       <ul>
907    *          <li>Fully qualified:
908    *             <ul>
909    *                <li><js>"com.foo.MyClass.myField"</js>
910    *             </ul>
911    *          <li>Simple:
912    *             <ul>
913    *                <li><js>"MyClass.myField"</js>
914    *             </ul>
915    *          <li>Simple inner class:
916    *             <ul>
917    *                <li><js>"MyClass$Inner1$Inner2.myField"</js>
918    *                <li><js>"Inner1$Inner2.myField"</js>
919    *                <li><js>"Inner2.myField"</js>
920    *             </ul>
921    *       </ul>
922    *    <li>A comma-delimited list of anything on this list.
923    * </ul>
924    *
925    * <h5 class='section'>See Also:</h5><ul>
926    *    <li class='link'><a class="doclink" href="../../../../index.html#jm.DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a>
927    * </ul>
928    *
929    * @return The annotation value.
930    */
931   String[] on() default {};
932
933   /**
934    * Dynamically apply this annotation to the specified classes.
935    *
936    * <p>
937    * Identical to {@link #on()} except allows you to specify class objects instead of a strings.
938    *
939    * <h5 class='section'>See Also:</h5><ul>
940    *    <li class='link'><a class="doclink" href="../../../../index.html#jm.DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a>
941    * </ul>
942    *
943    * @return The annotation value.
944    */
945   Class<?>[] onClass() default {};
946
947   /**
948    * Synonym for {@link #pattern()}.
949    *
950    * @return The annotation value.
951    */
952   String p() default "";
953
954   /**
955    * <mk>pattern</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
956    *
957    * <p>
958    * A string input is valid if it matches the specified regular expression pattern.
959    *
960    * <p>
961    * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
962    * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made.
963    * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400).
964    *
965    * <h5 class='section'>Example:</h5>
966    * <p class='bjava'>
967    *    <ja>@RestPut</ja>
968    *    <jk>public void</jk> doPut(<ja>@Content</ja> <ja>@Schema</ja>(pattern=<js>"/\\w+\\.\\d+/"</js>) String <jv>input</jv>) {...}
969    * </p>
970    *
971    * <p>
972    * Only allowed for the following types: <js>"string"</js>.
973    *
974    * <h5 class='section'>Used for:</h5>
975    * <ul class='spaced-list'>
976    *    <li>
977    *       Server-side schema-based parsing validation.
978    *    <li>
979    *       Server-side generated Swagger documentation.
980    *    <li>
981    *       Client-side schema-based serializing validation.
982    * </ul>
983    *
984    * @return The annotation value.
985    */
986   String pattern() default "";
987
988   /**
989    * <mk>properties</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
990    *
991    * <h5 class='section'>Notes:</h5><ul>
992    *    <li class='note'>
993    *       The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object.
994    *       <br>Multiple lines are concatenated with newlines.
995    * </ul>
996    *
997    * @return The annotation value.
998    */
999   String[] properties() default {};
1000
1001   /**
1002    * Synonym for {@link #required()}.
1003    *
1004    * @return The annotation value.
1005    */
1006   boolean r() default false;
1007
1008   /**
1009    * <mk>readOnly</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
1010    *
1011    * <h5 class='section'>Notes:</h5><ul>
1012    *    <li class='note'>
1013    *       The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object.
1014    *       <br>Multiple lines are concatenated with newlines.
1015    * </ul>
1016    *
1017    * @return The annotation value.
1018    */
1019   boolean readOnly() default false;
1020
1021   /**
1022    * <mk>required</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
1023    *
1024    * <p>
1025    * Determines whether the parameter is mandatory.
1026    *
1027    * <p>
1028    * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
1029    * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made.
1030    * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400).
1031    *
1032    * <h5 class='section'>Examples:</h5>
1033    * <p class='bjava'>
1034    *    <jc>// Used on parameter</jc>
1035    *    <ja>@RestPost</ja>
1036    *    <jk>public void</jk> addPet(
1037    *       <ja>@Content</ja> <ja>@Schema</ja>(required=<jk>true</jk>) Pet <jv>input</jv>
1038    *    ) {...}
1039    * </p>
1040    * <p class='bjava'>
1041    *    <jc>// Used on class</jc>
1042    *    <ja>@RestPost</ja>
1043    *    <jk>public void</jk> addPet(Pet <jv>input</jv>) {...}
1044    *
1045    *    <ja>@Content</ja>(required=<jk>true</jk>)
1046    *    <jk>public class</jk> Pet {...}
1047    * </p>
1048    *
1049    * <h5 class='section'>Used for:</h5>
1050    * <ul class='spaced-list'>
1051    *    <li>
1052    *       Server-side schema-based parsing validation.
1053    *    <li>
1054    *       Server-side generated Swagger documentation.
1055    *    <li>
1056    *       Client-side schema-based serializing validation.
1057    * </ul>
1058    *
1059    * @return The annotation value.
1060    */
1061   boolean required() default false;
1062
1063   /**
1064    * Synonym for {@link #readOnly()}.
1065    *
1066    * @return The annotation value.
1067    */
1068   boolean ro() default false;
1069
1070   /**
1071    * Synonym for {@link #skipIfEmpty()}.
1072    *
1073    * @return The annotation value.
1074    */
1075   boolean sie() default false;
1076
1077   /**
1078    * Skips this value during serialization if it's an empty string or empty collection/array.
1079    *
1080    * <p>
1081    * Note that <jk>null</jk> values are already ignored.
1082    *
1083    * <h5 class='section'>Used for:</h5>
1084    * <ul class='spaced-list'>
1085    *    <li>
1086    *       Client-side schema-based serializing.
1087    * </ul>
1088    *
1089    * @return The annotation value.
1090    */
1091   boolean skipIfEmpty() default false;
1092
1093   /**
1094    * Synonym for {@link #type()}.
1095    *
1096    * @return The annotation value.
1097    */
1098   String t() default "";
1099
1100   /**
1101    * <mk>title</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
1102    *
1103    * <h5 class='section'>Notes:</h5><ul>
1104    *    <li class='note'>
1105    *       The format is plain text.
1106    * </ul>
1107    *
1108    * @return The annotation value.
1109    */
1110   String title() default "";
1111
1112   /**
1113    * <mk>type</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
1114    *
1115    * <p>
1116    * The type of the parameter.
1117    *
1118    * <h5 class='section'>Examples:</h5>
1119    * <p class='bjava'>
1120    *    <jc>// Used on parameter</jc>
1121    *    <ja>@RestPost</ja>
1122    *    <jk>public void</jk> addPet(
1123    *       <ja>@Content</ja> <ja>@Schema</ja>(type=<js>"object"</js>) Pet <jv>input</jv>
1124    *    ) {...}
1125    * </p>
1126    * <p class='bjava'>
1127    *    <jc>// Used on class</jc>
1128    *    <ja>@RestPost</ja>
1129    *    <jk>public void</jk> addPet(Pet <jv>input</jv>) {...}
1130    *
1131    *    <ja>@Content</ja> <ja>@Schema</ja>(type=<js>"object"</js>)
1132    *    <jk>public class</jk> Pet {...}
1133    * </p>
1134    *
1135    * <h5 class='section'>Used for:</h5>
1136    * <ul class='spaced-list'>
1137    *    <li>
1138    *       Server-side schema-based parsing.
1139    *    <li>
1140    *       Server-side generated Swagger documentation.
1141    *    <li>
1142    *       Client-side schema-based serializing.
1143    * </ul>
1144    *
1145    * <ul class='values spaced-list'>
1146    *    <li>
1147    *       <js>"string"</js>
1148    *       <br>Parameter must be a string or a POJO convertible from a string.
1149    *    <li>
1150    *       <js>"number"</js>
1151    *       <br>Parameter must be a number primitive or number object.
1152    *       <br>If parameter is <c>Object</c>, creates either a <c>Float</c> or <c>Double</c> depending on the size of the number.
1153    *    <li>
1154    *       <js>"integer"</js>
1155    *       <br>Parameter must be a integer/long primitive or integer/long object.
1156    *       <br>If parameter is <c>Object</c>, creates either a <c>Short</c>, <c>Integer</c>, or <c>Long</c> depending on the size of the number.
1157    *    <li>
1158    *       <js>"boolean"</js>
1159    *       <br>Parameter must be a boolean primitive or object.
1160    *    <li>
1161    *       <js>"array"</js>
1162    *       <br>Parameter must be an array or collection.
1163    *       <br>Elements must be strings or POJOs convertible from strings.
1164    *       <br>If parameter is <c>Object</c>, creates an {@link JsonList}.
1165    *    <li>
1166    *       <js>"object"</js>
1167    *       <br>Parameter must be a map or bean.
1168    *       <br>If parameter is <c>Object</c>, creates an {@link JsonMap}.
1169    *       <br>Note that this is an extension of the OpenAPI schema as Juneau allows for arbitrarily-complex POJOs to be serialized as HTTP parts.
1170    *    <li>
1171    *       <js>"file"</js>
1172    *       <br>This type is currently not supported.
1173    * </ul>
1174    *
1175    * <h5 class='section'>Notes:</h5><ul>
1176    *    <li class='note'>Static strings are defined in {@link ParameterType}.
1177    * </ul>
1178    *
1179    * <h5 class='section'>See Also:</h5><ul>
1180    *    <li class='extlink'><a class="doclink" href="https://swagger.io/specification#dataTypes">Swagger Data Types</a>
1181    * </ul>
1182    *
1183    * @return The annotation value.
1184    */
1185   String type() default "";
1186
1187   /**
1188    * Synonym for {@link #uniqueItems()}.
1189    *
1190    * @return The annotation value.
1191    */
1192   boolean ui() default false;
1193
1194   /**
1195    * <mk>uniqueItems</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
1196    *
1197    * <p>
1198    * If <jk>true</jk> the input validates successfully if all of its elements are unique.
1199    *
1200    * <p>
1201    * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}.
1202    * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made.
1203    * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400).
1204    *
1205    * <p>
1206    * If the parameter type is a subclass of {@link Set}, this validation is skipped (since a set can only contain unique items anyway).
1207    * <br>Otherwise, the collection or array is checked for duplicate items.
1208    *
1209    * <p>
1210    * Only allowed for the following types: <js>"array"</js>.
1211    *
1212    * <h5 class='section'>Used for:</h5>
1213    * <ul class='spaced-list'>
1214    *    <li>
1215    *       Server-side schema-based parsing validation.
1216    *    <li>
1217    *       Server-side generated Swagger documentation.
1218    *    <li>
1219    *       Client-side schema-based serializing validation.
1220    * </ul>
1221    *
1222    * @return The annotation value.
1223    */
1224   boolean uniqueItems() default false;
1225
1226   /**
1227    * <mk>xml</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>.
1228    *
1229    * <h5 class='section'>Notes:</h5><ul>
1230    *    <li class='note'>
1231    *       The format is a <a class="doclink" href="../../../../index.html#jd.Swagger">Swagger</a> object.
1232    *       <br>Multiple lines are concatenated with newlines.
1233    * </ul>
1234    *
1235    * @return The annotation value.
1236    */
1237   String[] xml() default {};
1238}