001/* 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.juneau.annotation; 018 019import static java.lang.annotation.ElementType.*; 020import static java.lang.annotation.RetentionPolicy.*; 021 022import java.lang.annotation.*; 023import java.util.*; 024 025import org.apache.juneau.collections.*; 026import org.apache.juneau.http.annotation.*; 027import org.apache.juneau.httppart.*; 028import org.apache.juneau.oapi.*; 029 030/** 031 * Swagger/OpenAPI/JSON Schema annotation. 032 * 033 * <p> 034 * The Schema Object allows the definition of input and output data types. 035 * These types can be objects, but also primitives and arrays. 036 * This annotation is based on the JSON Schema Specification and supports multiple versions: 037 * <ul> 038 * <li><b>JSON Schema Draft 04</b> - Core properties (via Swagger 2.0/OpenAPI 3.0) 039 * <li><b>JSON Schema Draft 2020-12</b> - Extended properties and updated semantics 040 * </ul> 041 * 042 * <p> 043 * For backward compatibility, all Swagger 2.0 and OpenAPI 3.0 properties are supported. 044 * New Draft 2020-12 properties are opt-in and can be used alongside existing properties. 045 * 046 * <p> 047 * Used to populate the auto-generated Swagger documentation and UI for server-side <ja>@Rest</ja>-annotated classes. 048 * <br>Also used to define OpenAPI schema information for POJOs serialized through {@link OpenApiSerializer} and parsed through {@link OpenApiParser}. 049 * 050 * <h5 class='section'>Examples:</h5> 051 * <p class='bjava'> 052 * <jc>// A response object thats a hex-encoded string</jc> 053 * <ja>@Response</ja>( 054 * schema=<ja>@Schema</ja>( 055 * type=<js>"string"</js>, 056 * format=<js>"binary"</js> 057 * ) 058 * ) 059 * </p> 060 * <p class='bjava'> 061 * <jc>// A request body consisting of an array of arrays, the internal 062 * // array being of type integer, numbers must be between 0 and 63 (inclusive)</jc> 063 * <ja>@Content</ja>( 064 * schema=<ja>@Schema</ja>( 065 * items=<ja>@Items</ja>( 066 * type=<js>"array"</js>, 067 * items=<ja>@SubItems</ja>( 068 * type=<js>"integer"</js>, 069 * minimum=<js>"0"</js>, 070 * maximum=<js>"63"</js> 071 * ) 072 * ) 073 * ) 074 * ) 075 * </p> 076 * <p class='bjava'> 077 * <jc>// Using Draft 2020-12 properties</jc> 078 * <ja>@Schema</ja>( 079 * type=<js>"number"</js>, 080 * exclusiveMaximumValue=<js>"100"</js>, <jc>// Draft 2020-12 numeric format</jc> 081 * examples={<js>"50"</js>, <js>"75"</js>, <js>"99"</js>}, <jc>// Draft 2020-12 property</jc> 082 * deprecatedProperty=<jk>true</jk> <jc>// Draft 2020-12 property</jc> 083 * ) 084 * </p> 085 * 086 * <h5 class='section'>See Also:</h5><ul> 087 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> 088 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanJsonSchema">juneau-bean-jsonschema</a> 089 * <li class='extlink'><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger 2.0 Schema Object</a> 090 * <li class='extlink'><a class="doclink" href="https://spec.openapis.org/oas/v3.0.3#schema-object">OpenAPI 3.0 Schema Object</a> 091 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-core.html">JSON Schema Draft 2020-12 Core</a> 092 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-validation.html">JSON Schema Draft 2020-12 Validation</a> 093 094 * </ul> 095 */ 096@Documented 097@Target({ PARAMETER, METHOD, TYPE, FIELD }) 098@Retention(RUNTIME) 099@Repeatable(SchemaAnnotation.Array.class) 100@ContextApply(SchemaAnnotation.Apply.class) 101public @interface Schema { 102 103 /** 104 * <mk>const</mk> field of the JSON Schema. 105 * 106 * <p> 107 * The value of this keyword MAY be of any type, including null. 108 * An instance validates successfully against this keyword if its value is equal to the value of this keyword. 109 * 110 * <p> 111 * This is a JSON Schema Draft 2020-12 property. 112 * 113 * <h5 class='section'>Examples:</h5> 114 * <p class='bjava'> 115 * <jc>// A constant string value</jc> 116 * <ja>@Schema</ja>(const_=<js>"fixed-value"</js>) 117 * <jk>public</jk> String getStatus() {...} 118 * </p> 119 * <p class='bjava'> 120 * <jc>// A constant numeric value</jc> 121 * <ja>@Schema</ja>(const_=<js>"42"</js>) 122 * <jk>public int</jk> getMagicNumber() {...} 123 * </p> 124 * 125 * <h5 class='section'>Used for:</h5> 126 * <ul class='spaced-list'> 127 * <li> 128 * Server-side schema-based parsing validation. 129 * <li> 130 * Server-side generated Swagger documentation. 131 * <li> 132 * Client-side schema-based serializing validation. 133 * </ul> 134 * 135 * <h5 class='section'>See Also:</h5><ul> 136 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.1.3">JSON Schema Validation § 6.1.3</a> 137 * </ul> 138 * 139 * @return The annotation value. 140 */ 141 String[] const_() default {}; 142 143 /** 144 * <mk>default</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 145 * 146 * <p> 147 * 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. 148 * <br>(Note: "default" has no meaning for required parameters.) 149 * 150 * <p> 151 * Additionally, this value is used to create instances of POJOs that are then serialized as language-specific examples in the generated Swagger documentation 152 * if the examples are not defined in some other way. 153 * 154 * <p> 155 * The format of this value is a string. 156 * <br>Multiple lines are concatenated with newlines. 157 * 158 * <h5 class='section'>Examples:</h5> 159 * <p class='bjava'> 160 * <jk>public</jk> Order placeOrder( 161 * <ja>@Header</ja>(<js>"X-PetId"</js>) 162 * <ja>@Schema</ja>(default_=<js>"100"</js>) 163 * <jk>long</jk> <jv>petId</jv>, 164 * 165 * <ja>@Header</ja>(<js>"X-AdditionalInfo"</js>) 166 * <ja>@Schema</ja>(format=<js>"uon"</js>, default_=<js>"(rushOrder=false)"</js>) 167 * AdditionalInfo <jv>additionalInfo</jv>, 168 * 169 * <ja>@Header</ja>(<js>"X-Flags"</js>) 170 * <ja>@Schema</ja>(collectionFormat=<js>"uon"</js>, default_=<js>"@(new-customer)"</js>) 171 * String[] <jv>flags</jv> 172 * ) {...} 173 * </p> 174 * 175 * <h5 class='section'>Used for:</h5> 176 * <ul class='spaced-list'> 177 * <li> 178 * Server-side schema-based parsing. 179 * <li> 180 * Server-side generated Swagger documentation. 181 * <li> 182 * Client-side schema-based serializing. 183 * </ul> 184 * 185 * @return The annotation value. 186 */ 187 String[] default_() default {}; 188 189 /** 190 * <mk>else</mk> field of the JSON Schema. 191 * 192 * <p> 193 * This keyword's value MUST be a valid JSON Schema. 194 * When "if" is present, and the instance fails to validate against its subschema, 195 * then validation succeeds against this keyword if the instance successfully validates against this keyword's subschema. 196 * 197 * <p> 198 * This is a JSON Schema Draft 2020-12 property that provides conditional schema validation. 199 * 200 * <h5 class='section'>Notes:</h5><ul> 201 * <li class='note'> 202 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanJsonSchema">juneau-bean-jsonschema</a> object. 203 * <br>Multiple lines are concatenated with newlines. 204 * </ul> 205 * 206 * <h5 class='section'>See Also:</h5><ul> 207 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.10.2.2.3">JSON Schema Core § 10.2.2.3</a> 208 * </ul> 209 * 210 * @return The annotation value. 211 */ 212 String[] else_() default {}; 213 214 /** 215 * <mk>enum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 216 * 217 * <p> 218 * If specified, the input validates successfully if it is equal to one of the elements in this array. 219 * 220 * <p> 221 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 222 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 223 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 224 * 225 * <p> 226 * The format is either individual values or a comma-delimited list. 227 * <br>Multiple lines are concatenated with newlines. 228 * 229 * <h5 class='section'>Examples:</h5> 230 * <p class='bjava'> 231 * <jc>// Comma-delimited list</jc> 232 * <jk>public</jk> Collection<Pet> findPetsByStatus( 233 * <ja>@Header</ja>(<js>"X-Status"</js>) 234 * <ja>@Schema</ja>(enum_=<js>"AVAILABLE,PENDING,SOLD"</js>) 235 * PetStatus <jv>status</jv> 236 * ) {...} 237 * </p> 238 * 239 * <h5 class='section'>Used for:</h5> 240 * <ul class='spaced-list'> 241 * <li> 242 * Server-side schema-based parsing validation. 243 * <li> 244 * Server-side generated Swagger documentation. 245 * <li> 246 * Client-side schema-based serializing validation. 247 * </ul> 248 * 249 * @return The annotation value. 250 */ 251 String[] enum_() default {}; 252 253 /** 254 * <mk>if</mk> field of the JSON Schema. 255 * 256 * <p> 257 * This keyword's value MUST be a valid JSON Schema. 258 * This validation outcome of this keyword's subschema has no direct effect on the overall validation result. 259 * Rather, it controls which of the "then" or "else" keywords are evaluated. 260 * 261 * <p> 262 * This is a JSON Schema Draft 2020-12 property that provides conditional schema validation. 263 * 264 * <h5 class='section'>Notes:</h5><ul> 265 * <li class='note'> 266 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanJsonSchema">juneau-bean-jsonschema</a> object. 267 * <br>Multiple lines are concatenated with newlines. 268 * </ul> 269 * 270 * <h5 class='section'>See Also:</h5><ul> 271 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.10.2.2.3">JSON Schema Core § 10.2.2.3</a> 272 * </ul> 273 * 274 * @return The annotation value. 275 */ 276 String[] if_() default {}; 277 278 /** 279 * <mk>then</mk> field of the JSON Schema. 280 * 281 * <p> 282 * This keyword's value MUST be a valid JSON Schema. 283 * When "if" is present, and the instance successfully validates against its subschema, 284 * then validation succeeds against this keyword if the instance also successfully validates against this keyword's subschema. 285 * 286 * <p> 287 * This is a JSON Schema Draft 2020-12 property that provides conditional schema validation. 288 * 289 * <h5 class='section'>Notes:</h5><ul> 290 * <li class='note'> 291 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanJsonSchema">juneau-bean-jsonschema</a> object. 292 * <br>Multiple lines are concatenated with newlines. 293 * </ul> 294 * 295 * <h5 class='section'>See Also:</h5><ul> 296 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.10.2.2.3">JSON Schema Core § 10.2.2.3</a> 297 * </ul> 298 * 299 * @return The annotation value. 300 */ 301 String[] then_() default {}; 302 303 /** 304 * <mk>$comment</mk> field of the JSON Schema. 305 * 306 * <p> 307 * This keyword reserves a location for comments from schema authors to readers or maintainers of the schema. 308 * The value of this keyword MUST be a string. 309 * Implementations MUST NOT present this string to end users. 310 * Tools for editing schemas SHOULD support displaying and editing this keyword. 311 * 312 * <p> 313 * This is a JSON Schema Draft 2020-12 property. 314 * 315 * <h5 class='section'>Examples:</h5> 316 * <p class='bjava'> 317 * <ja>@Schema</ja>( 318 * type=<js>"string"</js>, 319 * $comment=<js>"This field is deprecated but maintained for backward compatibility"</js> 320 * ) 321 * <jk>public</jk> String getLegacyField() {...} 322 * </p> 323 * 324 * <h5 class='section'>See Also:</h5><ul> 325 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.3">JSON Schema Core § 8.3</a> 326 * </ul> 327 * 328 * @return The annotation value. 329 */ 330 String[] $comment() default {}; 331 332 /** 333 * <mk>$defs</mk> field of the JSON Schema. 334 * 335 * <p> 336 * The "$defs" keyword reserves a location for schema authors to inline re-usable JSON Schemas into a more general schema. 337 * The value of this keyword MUST be an object. Each value of this object MUST be a valid JSON Schema. 338 * 339 * <p> 340 * This is a JSON Schema Draft 2020-12 property that replaces the older "definitions" keyword. 341 * 342 * <h5 class='section'>Notes:</h5><ul> 343 * <li class='note'> 344 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanJsonSchema">juneau-bean-jsonschema</a> object. 345 * <br>Multiple lines are concatenated with newlines. 346 * </ul> 347 * 348 * <h5 class='section'>See Also:</h5><ul> 349 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.2.4">JSON Schema Core § 8.2.4</a> 350 * </ul> 351 * 352 * @return The annotation value. 353 */ 354 String[] $defs() default {}; 355 356 /** 357 * <mk>$id</mk> field of the JSON Schema. 358 * 359 * <p> 360 * The "$id" keyword defines a URI for the schema, and the base URI that other URI references within the schema are resolved against. 361 * 362 * <p> 363 * This is a JSON Schema Draft 2020-12 property. 364 * 365 * <h5 class='section'>Examples:</h5> 366 * <p class='bjava'> 367 * <ja>@Schema</ja>( 368 * $id=<js>"https://example.com/schemas/person.json"</js>, 369 * type=<js>"object"</js> 370 * ) 371 * <jk>public class</jk> Person {...} 372 * </p> 373 * 374 * <h5 class='section'>See Also:</h5><ul> 375 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.2.1">JSON Schema Core § 8.2.1</a> 376 * </ul> 377 * 378 * @return The annotation value. 379 */ 380 String $id() default ""; 381 382 /** 383 * <mk>$ref</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 384 * 385 * <p> 386 * A JSON reference to the schema definition. 387 * 388 * <h5 class='section'>Notes:</h5><ul> 389 * <li class='note'> 390 * The format is a <a href='https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03'>JSON Reference</a>. 391 * </ul> 392 * 393 * @return The annotation value. 394 */ 395 String $ref() default ""; 396 397 /** 398 * <mk>additionalProperties</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 399 * 400 * <h5 class='section'>Notes:</h5><ul> 401 * <li class='note'> 402 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> object. 403 * <br>Multiple lines are concatenated with newlines. 404 * </ul> 405 * 406 * @return The annotation value. 407 */ 408 String[] additionalProperties() default {}; 409 410 /** 411 * Synonym for {@link #allowEmptyValue()}. 412 * 413 * @return The annotation value. 414 */ 415 boolean aev() default false; 416 417 /** 418 * <mk>allOf</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 419 * 420 * <h5 class='section'>Notes:</h5><ul> 421 * <li class='note'> 422 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> object. 423 * <br>Multiple lines are concatenated with newlines. 424 * </ul> 425 * 426 * @return The annotation value. 427 */ 428 String[] allOf() default {}; 429 430 /** 431 * <mk>allowEmptyValue</mk> field of the <a class='doclink' href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter Object</a>. 432 * 433 * <p> 434 * Sets the ability to pass empty-valued heaver values. 435 * 436 * <h5 class='section'>Used for:</h5> 437 * <ul class='spaced-list'> 438 * <li> 439 * Server-side schema-based parsing validation. 440 * <li> 441 * Server-side generated Swagger documentation. 442 * <li> 443 * Client-side schema-based serializing validation. 444 * </ul> 445 * 446 * <p> 447 * <b>Note:</b> This is technically only valid for either query or formData parameters, but support is provided anyway for backwards compatability. 448 * 449 * @return The annotation value. 450 */ 451 boolean allowEmptyValue() default false; 452 453 /** 454 * Synonym for {@link #collectionFormat()}. 455 * 456 * @return The annotation value. 457 */ 458 String cf() default ""; 459 460 /** 461 * <mk>collectionFormat</mk> field. 462 * 463 * <p> 464 * Note that this field isn't part of the Swagger 2.0 specification, but the specification does not specify how 465 * items are supposed to be represented. 466 * 467 * <p> 468 * Determines the format of the array if <c>type</c> <js>"array"</js> is used. 469 * <br>Can only be used if <c>type</c> is <js>"array"</js>. 470 * 471 * <p> 472 * Static strings are defined in {@link CollectionFormatType}. 473 * 474 * <p> 475 * Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements. 476 * 477 * <h5 class='section'>Used for:</h5> 478 * <ul class='spaced-list'> 479 * <li> 480 * Server-side schema-based parsing. 481 * <li> 482 * Server-side generated Swagger documentation. 483 * <li> 484 * Client-side schema-based serializing. 485 * </ul> 486 * 487 * <p> 488 * Note that for collections/arrays parameters with POJO element types, the input is broken into a string array before being converted into POJO elements. 489 * 490 * <ul class='values'> 491 * <li><js>"csv"</js> (default) - Comma-separated values (e.g. <js>"foo,bar"</js>). 492 * <li><js>"ssv"</js> - Space-separated values (e.g. <js>"foo bar"</js>). 493 * <li><js>"tsv"</js> - Tab-separated values (e.g. <js>"foo\tbar"</js>). 494 * <li><js>"pipes</js> - Pipe-separated values (e.g. <js>"foo|bar"</js>). 495 * <li><js>"multi"</js> - Corresponds to multiple parameter instances instead of multiple values for a single instance (e.g. <js>"foo=bar&foo=baz"</js>). 496 * <li><js>"uon"</js> - UON notation (e.g. <js>"@(foo,bar)"</js>). 497 * </ul> 498 * 499 * @return The annotation value. 500 */ 501 String collectionFormat() default ""; 502 503 /** 504 * <mk>contentEncoding</mk> field of the JSON Schema. 505 * 506 * <p> 507 * If the instance is a string, this property defines the encoding used to store the contents. 508 * Common values: "base64", "quoted-printable", "7bit", "8bit", "binary" 509 * 510 * <p> 511 * This is a JSON Schema Draft 2020-12 property. 512 * 513 * <h5 class='section'>Examples:</h5> 514 * <p class='bjava'> 515 * <jc>// A base64-encoded binary string</jc> 516 * <ja>@Schema</ja>( 517 * type=<js>"string"</js>, 518 * contentEncoding=<js>"base64"</js>, 519 * contentMediaType=<js>"image/png"</js> 520 * ) 521 * <jk>public</jk> String getImageData() {...} 522 * </p> 523 * 524 * <h5 class='section'>Used for:</h5> 525 * <ul class='spaced-list'> 526 * <li> 527 * Server-side generated Swagger documentation. 528 * </ul> 529 * 530 * <h5 class='section'>See Also:</h5><ul> 531 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.8.3">JSON Schema Validation § 8.3</a> 532 * </ul> 533 * 534 * @return The annotation value. 535 */ 536 String contentEncoding() default ""; 537 538 /** 539 * <mk>contentMediaType</mk> field of the JSON Schema. 540 * 541 * <p> 542 * If the instance is a string, this property defines the MIME type of the contents of the string. 543 * 544 * <p> 545 * This is a JSON Schema Draft 2020-12 property. 546 * 547 * <h5 class='section'>Examples:</h5> 548 * <p class='bjava'> 549 * <jc>// A string containing JSON data</jc> 550 * <ja>@Schema</ja>( 551 * type=<js>"string"</js>, 552 * contentMediaType=<js>"application/json"</js> 553 * ) 554 * <jk>public</jk> String getJsonData() {...} 555 * </p> 556 * 557 * <h5 class='section'>Used for:</h5> 558 * <ul class='spaced-list'> 559 * <li> 560 * Server-side generated Swagger documentation. 561 * </ul> 562 * 563 * <h5 class='section'>See Also:</h5><ul> 564 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.8.3">JSON Schema Validation § 8.3</a> 565 * </ul> 566 * 567 * @return The annotation value. 568 */ 569 String contentMediaType() default ""; 570 571 /** 572 * Synonym for {@link #description()}. 573 * 574 * @return The annotation value. 575 */ 576 String[] d() default {}; 577 578 /** 579 * <mk>dependentRequired</mk> field of the JSON Schema. 580 * 581 * <p> 582 * This keyword specifies properties that are required if a specific other property is present. 583 * The value of this keyword MUST be an object where each value is an array of strings. 584 * 585 * <p> 586 * This is a JSON Schema Draft 2020-12 property. 587 * 588 * <h5 class='section'>Notes:</h5><ul> 589 * <li class='note'> 590 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanJsonSchema">juneau-bean-jsonschema</a> object. 591 * <br>Multiple lines are concatenated with newlines. 592 * </ul> 593 * 594 * <h5 class='section'>See Also:</h5><ul> 595 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.5.4">JSON Schema Validation § 6.5.4</a> 596 * </ul> 597 * 598 * @return The annotation value. 599 */ 600 String[] dependentRequired() default {}; 601 602 /** 603 * <mk>dependentSchemas</mk> field of the JSON Schema. 604 * 605 * <p> 606 * This keyword specifies subschemas that are evaluated if the instance is an object and contains a certain property. 607 * The value of this keyword MUST be an object where each value is a valid JSON Schema. 608 * 609 * <p> 610 * This is a JSON Schema Draft 2020-12 property. 611 * 612 * <h5 class='section'>Notes:</h5><ul> 613 * <li class='note'> 614 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanJsonSchema">juneau-bean-jsonschema</a> object. 615 * <br>Multiple lines are concatenated with newlines. 616 * </ul> 617 * 618 * <h5 class='section'>See Also:</h5><ul> 619 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.10.2.2.4">JSON Schema Core § 10.2.2.4</a> 620 * </ul> 621 * 622 * @return The annotation value. 623 */ 624 String[] dependentSchemas() default {}; 625 626 /** 627 * <mk>deprecated</mk> field of the JSON Schema. 628 * 629 * <p> 630 * The value of this keyword MUST be a boolean. 631 * When true, applications SHOULD refrain from usage of the declared property. 632 * It may mean the property is going to be removed in the future. 633 * 634 * <p> 635 * This is a JSON Schema Draft 2020-12 property. 636 * 637 * <h5 class='section'>Examples:</h5> 638 * <p class='bjava'> 639 * <ja>@Schema</ja>(deprecated=<jk>true</jk>) 640 * <ja>@Deprecated</ja> 641 * <jk>public</jk> String getOldMethod() {...} 642 * </p> 643 * 644 * <h5 class='section'>Used for:</h5> 645 * <ul class='spaced-list'> 646 * <li> 647 * Server-side generated Swagger documentation. 648 * </ul> 649 * 650 * <h5 class='section'>See Also:</h5><ul> 651 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.9.3">JSON Schema Validation § 9.3</a> 652 * </ul> 653 * 654 * @return The annotation value. 655 */ 656 boolean deprecatedProperty() default false; 657 658 /** 659 * <mk>description</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 660 * 661 * <p> 662 * A brief description of the body. This could contain examples of use. 663 * 664 * <h5 class='section'>Examples:</h5> 665 * <p class='bjava'> 666 * <jc>// Used on parameter</jc> 667 * <ja>@RestPost</ja> 668 * <jk>public void</jk> addPet( 669 * <ja>@Content</ja> <ja>@Schema</ja>(description=<js>"Pet object to add to the store"</js>) Pet <jv>input</jv> 670 * ) {...} 671 * </p> 672 * <p class='bjava'> 673 * <jc>// Used on class</jc> 674 * <ja>@RestPost</ja> 675 * <jk>public void</jk> addPet(Pet <jv>input</jv>) {...} 676 * 677 * <ja>@Content</ja> <ja>@Schema</ja>(description=<js>"Pet object to add to the store"</js>) 678 * <jk>public class</jk> Pet {...} 679 * </p> 680 * 681 * <h5 class='section'>Notes:</h5><ul> 682 * <li class='note'> 683 * The format is plain text. 684 * <br>Multiple lines are concatenated with newlines. 685 * <li class='note'> 686 * Supports <a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">SVL Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>) for the swagger generator. 687 * </ul> 688 * 689 * @return The annotation value. 690 */ 691 String[] description() default {}; 692 693 /** 694 * Synonym for {@link #default_()}. 695 * 696 * @return The annotation value. 697 */ 698 String[] df() default {}; 699 700 /** 701 * <mk>discriminator</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 702 * 703 * <h5 class='section'>Notes:</h5><ul> 704 * <li class='note'> 705 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> object. 706 * <br>Multiple lines are concatenated with newlines. 707 * </ul> 708 * 709 * @return The annotation value. 710 */ 711 String discriminator() default ""; 712 713 /** 714 * Synonym for {@link #enum_()}. 715 * 716 * @return The annotation value. 717 */ 718 String[] e() default {}; 719 720 /** 721 * Synonym for {@link #exclusiveMaximum()}. 722 * 723 * @return The annotation value. 724 */ 725 boolean emax() default false; 726 727 /** 728 * Synonym for {@link #exclusiveMinimum()}. 729 * 730 * @return The annotation value. 731 */ 732 boolean emin() default false; 733 734 /** 735 * <mk>examples</mk> field of the JSON Schema. 736 * 737 * <p> 738 * The value of this keyword MUST be an array. 739 * There are no restrictions on the values within the array. 740 * When multiple examples are applicable, an array of examples can be used. 741 * 742 * <p> 743 * This is a JSON Schema Draft 2020-12 property. 744 * 745 * <h5 class='section'>Examples:</h5> 746 * <p class='bjava'> 747 * <jc>// Multiple examples of valid values</jc> 748 * <ja>@Schema</ja>( 749 * type=<js>"string"</js>, 750 * examples={<js>"red"</js>, <js>"green"</js>, <js>"blue"</js>} 751 * ) 752 * <jk>public</jk> String getColor() {...} 753 * </p> 754 * 755 * <h5 class='section'>Used for:</h5> 756 * <ul class='spaced-list'> 757 * <li> 758 * Server-side generated Swagger documentation. 759 * </ul> 760 * 761 * <h5 class='section'>See Also:</h5><ul> 762 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.9.5">JSON Schema Validation § 9.5</a> 763 * </ul> 764 * 765 * @return The annotation value. 766 */ 767 String[] examples() default {}; 768 769 /** 770 * <mk>exclusiveMaximum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 771 * 772 * <p> 773 * Defines whether the maximum is matched exclusively. 774 * 775 * <p> 776 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 777 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 778 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 779 * 780 * <p> 781 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 782 * <br>If <jk>true</jk>, must be accompanied with <c>maximum</c>. 783 * 784 * <h5 class='section'>Notes:</h5><ul> 785 * <li class='note'> 786 * <b>Deprecated in JSON Schema Draft 2020-12:</b> This boolean format is from Swagger 2.0/OpenAPI 3.0 and JSON Schema Draft 04. 787 * Consider using {@link #exclusiveMaximumValue()} for Draft 2020-12 compliance, which uses a numeric value instead. 788 * For backward compatibility, if {@link #exclusiveMaximumValue()} is set, it takes precedence over this property. 789 * </ul> 790 * 791 * <h5 class='section'>Used for:</h5> 792 * <ul class='spaced-list'> 793 * <li> 794 * Server-side schema-based parsing validation. 795 * <li> 796 * Server-side generated Swagger documentation. 797 * <li> 798 * Client-side schema-based serializing validation. 799 * </ul> 800 * 801 * @return The annotation value. 802 * @deprecated Use {@link #exclusiveMaximumValue()} for JSON Schema Draft 2020-12 compliance. 803 */ 804 @Deprecated 805 boolean exclusiveMaximum() default false; 806 807 /** 808 * <mk>exclusiveMaximum</mk> field of the JSON Schema (Draft 2020-12 numeric value). 809 * 810 * <p> 811 * The value of this keyword MUST be a number. 812 * The instance is valid if it is strictly less than (not equal to) the value specified by this keyword. 813 * 814 * <p> 815 * This is a JSON Schema Draft 2020-12 property that replaces the boolean {@link #exclusiveMaximum()}. 816 * For backward compatibility, both properties are supported. 817 * If this property is specified, it takes precedence over the boolean version. 818 * 819 * <h5 class='section'>Examples:</h5> 820 * <p class='bjava'> 821 * <jc>// A number that must be strictly less than 100</jc> 822 * <ja>@Schema</ja>( 823 * type=<js>"number"</js>, 824 * exclusiveMaximumValue=<js>"100"</js> 825 * ) 826 * <jk>public</jk> Double getPercentage() {...} 827 * </p> 828 * 829 * <h5 class='section'>Used for:</h5> 830 * <ul class='spaced-list'> 831 * <li> 832 * Server-side schema-based parsing validation. 833 * <li> 834 * Server-side generated Swagger documentation. 835 * <li> 836 * Client-side schema-based serializing validation. 837 * </ul> 838 * 839 * <h5 class='section'>See Also:</h5><ul> 840 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.2.3">JSON Schema Validation § 6.2.3</a> 841 * </ul> 842 * 843 * @return The annotation value. 844 */ 845 String exclusiveMaximumValue() default ""; 846 847 /** 848 * <mk>exclusiveMinimum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 849 * 850 * <p> 851 * Defines whether the minimum is matched exclusively. 852 * 853 * <p> 854 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 855 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 856 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 857 * 858 * <p> 859 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 860 * <br>If <jk>true</jk>, must be accompanied with <c>minimum</c>. 861 * 862 * <h5 class='section'>Notes:</h5><ul> 863 * <li class='note'> 864 * <b>Deprecated in JSON Schema Draft 2020-12:</b> This boolean format is from Swagger 2.0/OpenAPI 3.0 and JSON Schema Draft 04. 865 * Consider using {@link #exclusiveMinimumValue()} for Draft 2020-12 compliance, which uses a numeric value instead. 866 * For backward compatibility, if {@link #exclusiveMinimumValue()} is set, it takes precedence over this property. 867 * </ul> 868 * 869 * <h5 class='section'>Used for:</h5> 870 * <ul class='spaced-list'> 871 * <li> 872 * Server-side schema-based parsing validation. 873 * <li> 874 * Server-side generated Swagger documentation. 875 * <li> 876 * Client-side schema-based serializing validation. 877 * </ul> 878 * 879 * @return The annotation value. 880 * @deprecated Use {@link #exclusiveMinimumValue()} for JSON Schema Draft 2020-12 compliance. 881 */ 882 @Deprecated 883 boolean exclusiveMinimum() default false; 884 885 /** 886 * <mk>exclusiveMinimum</mk> field of the JSON Schema (Draft 2020-12 numeric value). 887 * 888 * <p> 889 * The value of this keyword MUST be a number. 890 * The instance is valid if it is strictly greater than (not equal to) the value specified by this keyword. 891 * 892 * <p> 893 * This is a JSON Schema Draft 2020-12 property that replaces the boolean {@link #exclusiveMinimum()}. 894 * For backward compatibility, both properties are supported. 895 * If this property is specified, it takes precedence over the boolean version. 896 * 897 * <h5 class='section'>Examples:</h5> 898 * <p class='bjava'> 899 * <jc>// A number that must be strictly greater than 0</jc> 900 * <ja>@Schema</ja>( 901 * type=<js>"number"</js>, 902 * exclusiveMinimumValue=<js>"0"</js> 903 * ) 904 * <jk>public</jk> Double getPositiveNumber() {...} 905 * </p> 906 * 907 * <h5 class='section'>Used for:</h5> 908 * <ul class='spaced-list'> 909 * <li> 910 * Server-side schema-based parsing validation. 911 * <li> 912 * Server-side generated Swagger documentation. 913 * <li> 914 * Client-side schema-based serializing validation. 915 * </ul> 916 * 917 * <h5 class='section'>See Also:</h5><ul> 918 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-validation.html#rfc.section.6.2.5">JSON Schema Validation § 6.2.5</a> 919 * </ul> 920 * 921 * @return The annotation value. 922 */ 923 String exclusiveMinimumValue() default ""; 924 925 /** 926 * <mk>externalDocs</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 927 * 928 * <h5 class='section'>Notes:</h5><ul> 929 * <li class='note'> 930 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> object. 931 * <br>Multiple lines are concatenated with newlines. 932 * </ul> 933 * 934 * @return The annotation value. 935 */ 936 ExternalDocs externalDocs() default @ExternalDocs; 937 938 /** 939 * Synonym for {@link #format()}. 940 * 941 * @return The annotation value. 942 */ 943 String f() default ""; 944 945 /** 946 * <mk>format</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 947 * 948 * <p> 949 * The extending format for the previously mentioned <a class="doclink" href="https://swagger.io/specification/v2#parameterType">parameter type</a>. 950 * 951 * <p> 952 * Static strings are defined in {@link FormatType}. 953 * 954 * <h5 class='section'>Examples:</h5> 955 * <p class='bjava'> 956 * <jc>// Used on parameter</jc> 957 * <ja>@RestPut</ja> 958 * <jk>public void</jk> setAge( 959 * <ja>@Content</ja> <ja>@Schema</ja>(type=<js>"integer"</js>, format=<js>"int32"</js>) String <jv>input</jv> 960 * ) {...} 961 * </p> 962 * 963 * <h5 class='section'>Used for:</h5> 964 * <ul class='spaced-list'> 965 * <li> 966 * Server-side schema-based parsing. 967 * <li> 968 * Server-side generated Swagger documentation. 969 * <li> 970 * Client-side schema-based serializing. 971 * </ul> 972 * 973 * <ul class='values'> 974 * <li> 975 * <js>"int32"</js> - Signed 32 bits. 976 * <br>Only valid with type <js>"integer"</js>. 977 * <li> 978 * <js>"int64"</js> - Signed 64 bits. 979 * <br>Only valid with type <js>"integer"</js>. 980 * <li> 981 * <js>"float"</js> - 32-bit floating point number. 982 * <br>Only valid with type <js>"number"</js>. 983 * <li> 984 * <js>"double"</js> - 64-bit floating point number. 985 * <br>Only valid with type <js>"number"</js>. 986 * <li> 987 * <js>"byte"</js> - BASE-64 encoded characters. 988 * <br>Only valid with type <js>"string"</js>. 989 * <br>Parameters of type POJO convertible from string are converted after the string has been decoded. 990 * <li> 991 * <js>"binary"</js> - Hexadecimal encoded octets (e.g. <js>"00FF"</js>). 992 * <br>Only valid with type <js>"string"</js>. 993 * <br>Parameters of type POJO convertible from string are converted after the string has been decoded. 994 * <li> 995 * <js>"date"</js> - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 full-date</a>. 996 * <br>Only valid with type <js>"string"</js>. 997 * <li> 998 * <js>"date-time"</js> - An <a href='http://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14'>RFC3339 date-time</a>. 999 * <br>Only valid with type <js>"string"</js>. 1000 * <li> 1001 * <js>"password"</js> - Used to hint UIs the input needs to be obscured. 1002 * <br>This format does not affect the serialization or parsing of the parameter. 1003 * <li> 1004 * <js>"uon"</js> - UON notation (e.g. <js>"(foo=bar,baz=@(qux,123))"</js>). 1005 * <br>Only valid with type <js>"object"</js>. 1006 * <br>If not specified, then the input is interpreted as plain-text and is converted to a POJO directly. 1007 * </ul> 1008 * 1009 * <h5 class='section'>Notes:</h5><ul> 1010 * <li class='note'> 1011 * The format is plain text. 1012 * </ul> 1013 * 1014 * <h5 class='section'>See Also:</h5><ul> 1015 * <li class='extlink'><a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a> 1016 * </ul> 1017 * 1018 * @return The annotation value. 1019 */ 1020 String format() default ""; 1021 1022 /** 1023 * Specifies that schema information for this part should not be shown in the generated Swagger documentation. 1024 * 1025 * @return The annotation value. 1026 */ 1027 boolean ignore() default false; 1028 1029 /** 1030 * <mk>items</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1031 * 1032 * <p> 1033 * Describes the type of items in the array. 1034 * 1035 * <p> 1036 * Required if <c>type</c> is <js>"array"</js>. 1037 * <br>Can only be used if <c>type</c> is <js>"array"</js>. 1038 * 1039 * <h5 class='section'>Used for:</h5> 1040 * <ul class='spaced-list'> 1041 * <li> 1042 * Server-side schema-based parsing and parsing validation. 1043 * <li> 1044 * Server-side generated Swagger documentation. 1045 * <li> 1046 * Client-side schema-based serializing and serializing validation. 1047 * </ul> 1048 * 1049 * @return The annotation value. 1050 */ 1051 Items items() default @Items; 1052 1053 /** 1054 * Synonym for {@link #maximum()}. 1055 * 1056 * @return The annotation value. 1057 */ 1058 String max() default ""; 1059 1060 /** 1061 * Synonym for {@link #maxItems()}. 1062 * 1063 * @return The annotation value. 1064 */ 1065 long maxi() default -1; 1066 1067 /** 1068 * <mk>maximum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1069 * 1070 * <p> 1071 * Defines the maximum value for a parameter of numeric types. 1072 * <br>The value must be a valid JSON number. 1073 * 1074 * <p> 1075 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 1076 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 1077 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 1078 * 1079 * <p> 1080 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 1081 * 1082 * <h5 class='section'>Used for:</h5> 1083 * <ul class='spaced-list'> 1084 * <li> 1085 * Server-side schema-based parsing validation. 1086 * <li> 1087 * Server-side generated Swagger documentation. 1088 * <li> 1089 * Client-side schema-based serializing validation. 1090 * </ul> 1091 * 1092 * @return The annotation value. 1093 */ 1094 String maximum() default ""; 1095 1096 /** 1097 * <mk>maxItems</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1098 * 1099 * <p> 1100 * An array or collection is valid if its size is less than, or equal to, the value of this keyword. 1101 * 1102 * <p> 1103 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 1104 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 1105 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 1106 * 1107 * <p> 1108 * Only allowed for the following types: <js>"array"</js>. 1109 * 1110 * <h5 class='section'>Used for:</h5> 1111 * <ul class='spaced-list'> 1112 * <li> 1113 * Server-side schema-based parsing validation. 1114 * <li> 1115 * Server-side generated Swagger documentation. 1116 * <li> 1117 * Client-side schema-based serializing validation. 1118 * </ul> 1119 * 1120 * @return The annotation value. 1121 */ 1122 long maxItems() default -1; 1123 1124 /** 1125 * Synonym for {@link #maxLength()}. 1126 * 1127 * @return The annotation value. 1128 */ 1129 long maxl() default -1; 1130 1131 /** 1132 * <mk>maxLength</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1133 * 1134 * <p> 1135 * A string instance is valid against this keyword if its length is less than, or equal to, the value of this keyword. 1136 * <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>. 1137 * <br>The value <c>-1</c> is always ignored. 1138 * 1139 * <p> 1140 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 1141 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 1142 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 1143 * 1144 * <p> 1145 * Only allowed for the following types: <js>"string"</js>. 1146 * 1147 * <h5 class='section'>Used for:</h5> 1148 * <ul class='spaced-list'> 1149 * <li> 1150 * Server-side schema-based parsing validation. 1151 * <li> 1152 * Server-side generated Swagger documentation. 1153 * <li> 1154 * Client-side schema-based serializing validation. 1155 * </ul> 1156 * 1157 * @return The annotation value. 1158 */ 1159 long maxLength() default -1; 1160 1161 /** 1162 * Synonym for {@link #maxProperties()}. 1163 * 1164 * @return The annotation value. 1165 */ 1166 long maxp() default -1; 1167 1168 /** 1169 * <mk>maxProperties</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1170 * 1171 * <h5 class='section'>Notes:</h5><ul> 1172 * <li class='note'> 1173 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> object. 1174 * <br>Multiple lines are concatenated with newlines. 1175 * </ul> 1176 * 1177 * @return The annotation value. 1178 */ 1179 long maxProperties() default -1; 1180 1181 /** 1182 * Synonym for {@link #minimum()}. 1183 * 1184 * @return The annotation value. 1185 */ 1186 String min() default ""; 1187 1188 /** 1189 * Synonym for {@link #minItems()}. 1190 * 1191 * @return The annotation value. 1192 */ 1193 long mini() default -1; 1194 1195 /** 1196 * <mk>minimum</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1197 * 1198 * <p> 1199 * Defines the minimum value for a parameter of numeric types. 1200 * <br>The value must be a valid JSON number. 1201 * 1202 * <p> 1203 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 1204 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 1205 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 1206 * 1207 * <p> 1208 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 1209 * 1210 * <h5 class='section'>Used for:</h5> 1211 * <ul class='spaced-list'> 1212 * <li> 1213 * Server-side schema-based parsing validation. 1214 * <li> 1215 * Server-side generated Swagger documentation. 1216 * <li> 1217 * Client-side schema-based serializing validation. 1218 * </ul> 1219 * 1220 * @return The annotation value. 1221 */ 1222 String minimum() default ""; 1223 1224 /** 1225 * <mk>minItems</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1226 * 1227 * <p> 1228 * An array or collection is valid if its size is greater than, or equal to, the value of this keyword. 1229 * 1230 * <p> 1231 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 1232 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 1233 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 1234 * 1235 * <p> 1236 * Only allowed for the following types: <js>"array"</js>. 1237 * 1238 * <h5 class='section'>Used for:</h5> 1239 * <ul class='spaced-list'> 1240 * <li> 1241 * Server-side schema-based parsing validation. 1242 * <li> 1243 * Server-side generated Swagger documentation. 1244 * <li> 1245 * Client-side schema-based serializing validation. 1246 * </ul> 1247 * 1248 * @return The annotation value. 1249 */ 1250 long minItems() default -1; 1251 1252 /** 1253 * Synonym for {@link #minLength()}. 1254 * 1255 * @return The annotation value. 1256 */ 1257 long minl() default -1; 1258 1259 /** 1260 * <mk>minLength</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1261 * 1262 * <p> 1263 * A string instance is valid against this keyword if its length is greater than, or equal to, the value of this keyword. 1264 * <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>. 1265 * <br>The value <c>-1</c> is always ignored. 1266 * 1267 * <p> 1268 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 1269 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 1270 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 1271 * 1272 * <p> 1273 * Only allowed for the following types: <js>"string"</js>. 1274 * 1275 * <h5 class='section'>Used for:</h5> 1276 * <ul class='spaced-list'> 1277 * <li> 1278 * Server-side schema-based parsing validation. 1279 * <li> 1280 * Server-side generated Swagger documentation. 1281 * <li> 1282 * Client-side schema-based serializing validation. 1283 * </ul> 1284 * 1285 * @return The annotation value. 1286 */ 1287 long minLength() default -1; 1288 1289 /** 1290 * Synonym for {@link #minProperties()}. 1291 * 1292 * @return The annotation value. 1293 */ 1294 long minp() default -1; 1295 1296 /** 1297 * <mk>minProperties</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1298 * 1299 * <h5 class='section'>Notes:</h5><ul> 1300 * <li class='note'> 1301 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> object. 1302 * <br>Multiple lines are concatenated with newlines. 1303 * </ul> 1304 * 1305 * @return The annotation value. 1306 */ 1307 long minProperties() default -1; 1308 1309 /** 1310 * Synonym for {@link #multipleOf()}. 1311 * 1312 * @return The annotation value. 1313 */ 1314 String mo() default ""; 1315 1316 /** 1317 * <mk>multipleOf</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1318 * 1319 * <p> 1320 * A numeric instance is valid if the result of the division of the instance by this keyword's value is an integer. 1321 * <br>The value must be a valid JSON number. 1322 * 1323 * <p> 1324 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 1325 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 1326 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 1327 * 1328 * <p> 1329 * Only allowed for the following types: <js>"integer"</js>, <js>"number"</js>. 1330 * 1331 * <h5 class='section'>Used for:</h5> 1332 * <ul class='spaced-list'> 1333 * <li> 1334 * Server-side schema-based parsing validation. 1335 * <li> 1336 * Server-side generated Swagger documentation. 1337 * <li> 1338 * Client-side schema-based serializing validation. 1339 * </ul> 1340 * 1341 * @return The annotation value. 1342 */ 1343 String multipleOf() default ""; 1344 1345 /** 1346 * Dynamically apply this annotation to the specified classes/methods/fields. 1347 * 1348 * <p> 1349 * Used in conjunction with {@link org.apache.juneau.BeanContext.Builder#applyAnnotations(Class...)} to dynamically apply an annotation to an existing class/method/field. 1350 * It is ignored when the annotation is applied directly to classes/methods/fields. 1351 * 1352 * <h5 class='section'>Valid patterns:</h5> 1353 * <ul class='spaced-list'> 1354 * <li>Classes: 1355 * <ul> 1356 * <li>Fully qualified: 1357 * <ul> 1358 * <li><js>"com.foo.MyClass"</js> 1359 * </ul> 1360 * <li>Fully qualified inner class: 1361 * <ul> 1362 * <li><js>"com.foo.MyClass$Inner1$Inner2"</js> 1363 * </ul> 1364 * <li>Simple: 1365 * <ul> 1366 * <li><js>"MyClass"</js> 1367 * </ul> 1368 * <li>Simple inner: 1369 * <ul> 1370 * <li><js>"MyClass$Inner1$Inner2"</js> 1371 * <li><js>"Inner1$Inner2"</js> 1372 * <li><js>"Inner2"</js> 1373 * </ul> 1374 * </ul> 1375 * <li>Methods: 1376 * <ul> 1377 * <li>Fully qualified with args: 1378 * <ul> 1379 * <li><js>"com.foo.MyClass.myMethod(String,int)"</js> 1380 * <li><js>"com.foo.MyClass.myMethod(java.lang.String,int)"</js> 1381 * <li><js>"com.foo.MyClass.myMethod()"</js> 1382 * </ul> 1383 * <li>Fully qualified: 1384 * <ul> 1385 * <li><js>"com.foo.MyClass.myMethod"</js> 1386 * </ul> 1387 * <li>Simple with args: 1388 * <ul> 1389 * <li><js>"MyClass.myMethod(String,int)"</js> 1390 * <li><js>"MyClass.myMethod(java.lang.String,int)"</js> 1391 * <li><js>"MyClass.myMethod()"</js> 1392 * </ul> 1393 * <li>Simple: 1394 * <ul> 1395 * <li><js>"MyClass.myMethod"</js> 1396 * </ul> 1397 * <li>Simple inner class: 1398 * <ul> 1399 * <li><js>"MyClass$Inner1$Inner2.myMethod"</js> 1400 * <li><js>"Inner1$Inner2.myMethod"</js> 1401 * <li><js>"Inner2.myMethod"</js> 1402 * </ul> 1403 * </ul> 1404 * <li>Fields: 1405 * <ul> 1406 * <li>Fully qualified: 1407 * <ul> 1408 * <li><js>"com.foo.MyClass.myField"</js> 1409 * </ul> 1410 * <li>Simple: 1411 * <ul> 1412 * <li><js>"MyClass.myField"</js> 1413 * </ul> 1414 * <li>Simple inner class: 1415 * <ul> 1416 * <li><js>"MyClass$Inner1$Inner2.myField"</js> 1417 * <li><js>"Inner1$Inner2.myField"</js> 1418 * <li><js>"Inner2.myField"</js> 1419 * </ul> 1420 * </ul> 1421 * <li>A comma-delimited list of anything on this list. 1422 * </ul> 1423 * 1424 * <h5 class='section'>See Also:</h5><ul> 1425 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a> 1426 * </ul> 1427 * 1428 * @return The annotation value. 1429 */ 1430 String[] on() default {}; 1431 1432 /** 1433 * Dynamically apply this annotation to the specified classes. 1434 * 1435 * <p> 1436 * Identical to {@link #on()} except allows you to specify class objects instead of a strings. 1437 * 1438 * <h5 class='section'>See Also:</h5><ul> 1439 * <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/DynamicallyAppliedAnnotations">Dynamically Applied Annotations</a> 1440 * </ul> 1441 * 1442 * @return The annotation value. 1443 */ 1444 Class<?>[] onClass() default {}; 1445 1446 /** 1447 * Synonym for {@link #pattern()}. 1448 * 1449 * @return The annotation value. 1450 */ 1451 String p() default ""; 1452 1453 /** 1454 * <mk>pattern</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1455 * 1456 * <p> 1457 * A string input is valid if it matches the specified regular expression pattern. 1458 * 1459 * <p> 1460 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 1461 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 1462 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 1463 * 1464 * <h5 class='section'>Example:</h5> 1465 * <p class='bjava'> 1466 * <ja>@RestPut</ja> 1467 * <jk>public void</jk> doPut(<ja>@Content</ja> <ja>@Schema</ja>(pattern=<js>"/\\w+\\.\\d+/"</js>) String <jv>input</jv>) {...} 1468 * </p> 1469 * 1470 * <p> 1471 * Only allowed for the following types: <js>"string"</js>. 1472 * 1473 * <h5 class='section'>Used for:</h5> 1474 * <ul class='spaced-list'> 1475 * <li> 1476 * Server-side schema-based parsing validation. 1477 * <li> 1478 * Server-side generated Swagger documentation. 1479 * <li> 1480 * Client-side schema-based serializing validation. 1481 * </ul> 1482 * 1483 * @return The annotation value. 1484 */ 1485 String pattern() default ""; 1486 1487 /** 1488 * <mk>prefixItems</mk> field of the JSON Schema. 1489 * 1490 * <p> 1491 * The value of "prefixItems" MUST be a non-empty array of valid JSON Schemas. 1492 * Validation succeeds if each element of the instance validates against the schema at the same position, if any. 1493 * 1494 * <p> 1495 * This is a JSON Schema Draft 2020-12 property that provides tuple validation for arrays. 1496 * 1497 * <h5 class='section'>Notes:</h5><ul> 1498 * <li class='note'> 1499 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanJsonSchema">juneau-bean-jsonschema</a> object. 1500 * <br>Multiple lines are concatenated with newlines. 1501 * </ul> 1502 * 1503 * <h5 class='section'>See Also:</h5><ul> 1504 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.10.3.1.1">JSON Schema Core § 10.3.1.1</a> 1505 * </ul> 1506 * 1507 * @return The annotation value. 1508 */ 1509 String[] prefixItems() default {}; 1510 1511 /** 1512 * <mk>properties</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1513 * 1514 * <h5 class='section'>Notes:</h5><ul> 1515 * <li class='note'> 1516 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> object. 1517 * <br>Multiple lines are concatenated with newlines. 1518 * </ul> 1519 * 1520 * @return The annotation value. 1521 */ 1522 String[] properties() default {}; 1523 1524 /** 1525 * Synonym for {@link #required()}. 1526 * 1527 * @return The annotation value. 1528 */ 1529 boolean r() default false; 1530 1531 /** 1532 * <mk>readOnly</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1533 * 1534 * <h5 class='section'>Notes:</h5><ul> 1535 * <li class='note'> 1536 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> object. 1537 * <br>Multiple lines are concatenated with newlines. 1538 * </ul> 1539 * 1540 * @return The annotation value. 1541 */ 1542 boolean readOnly() default false; 1543 1544 /** 1545 * <mk>required</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1546 * 1547 * <p> 1548 * Determines whether the parameter is mandatory. 1549 * 1550 * <p> 1551 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 1552 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 1553 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 1554 * 1555 * <h5 class='section'>Examples:</h5> 1556 * <p class='bjava'> 1557 * <jc>// Used on parameter</jc> 1558 * <ja>@RestPost</ja> 1559 * <jk>public void</jk> addPet( 1560 * <ja>@Content</ja> <ja>@Schema</ja>(required=<jk>true</jk>) Pet <jv>input</jv> 1561 * ) {...} 1562 * </p> 1563 * <p class='bjava'> 1564 * <jc>// Used on class</jc> 1565 * <ja>@RestPost</ja> 1566 * <jk>public void</jk> addPet(Pet <jv>input</jv>) {...} 1567 * 1568 * <ja>@Content</ja>(required=<jk>true</jk>) 1569 * <jk>public class</jk> Pet {...} 1570 * </p> 1571 * 1572 * <h5 class='section'>Used for:</h5> 1573 * <ul class='spaced-list'> 1574 * <li> 1575 * Server-side schema-based parsing validation. 1576 * <li> 1577 * Server-side generated Swagger documentation. 1578 * <li> 1579 * Client-side schema-based serializing validation. 1580 * </ul> 1581 * 1582 * @return The annotation value. 1583 */ 1584 boolean required() default false; 1585 1586 /** 1587 * Synonym for {@link #readOnly()}. 1588 * 1589 * @return The annotation value. 1590 */ 1591 boolean ro() default false; 1592 1593 /** 1594 * Synonym for {@link #skipIfEmpty()}. 1595 * 1596 * @return The annotation value. 1597 */ 1598 boolean sie() default false; 1599 1600 /** 1601 * Skips this value during serialization if it's an empty string or empty collection/array. 1602 * 1603 * <p> 1604 * Note that <jk>null</jk> values are already ignored. 1605 * 1606 * <h5 class='section'>Used for:</h5> 1607 * <ul class='spaced-list'> 1608 * <li> 1609 * Client-side schema-based serializing. 1610 * </ul> 1611 * 1612 * @return The annotation value. 1613 */ 1614 boolean skipIfEmpty() default false; 1615 1616 /** 1617 * Synonym for {@link #type()}. 1618 * 1619 * @return The annotation value. 1620 */ 1621 String t() default ""; 1622 1623 /** 1624 * <mk>title</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1625 * 1626 * <h5 class='section'>Notes:</h5><ul> 1627 * <li class='note'> 1628 * The format is plain text. 1629 * </ul> 1630 * 1631 * @return The annotation value. 1632 */ 1633 String title() default ""; 1634 1635 /** 1636 * <mk>type</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1637 * 1638 * <p> 1639 * The type of the parameter. 1640 * 1641 * <h5 class='section'>Examples:</h5> 1642 * <p class='bjava'> 1643 * <jc>// Used on parameter</jc> 1644 * <ja>@RestPost</ja> 1645 * <jk>public void</jk> addPet( 1646 * <ja>@Content</ja> <ja>@Schema</ja>(type=<js>"object"</js>) Pet <jv>input</jv> 1647 * ) {...} 1648 * </p> 1649 * <p class='bjava'> 1650 * <jc>// Used on class</jc> 1651 * <ja>@RestPost</ja> 1652 * <jk>public void</jk> addPet(Pet <jv>input</jv>) {...} 1653 * 1654 * <ja>@Content</ja> <ja>@Schema</ja>(type=<js>"object"</js>) 1655 * <jk>public class</jk> Pet {...} 1656 * </p> 1657 * 1658 * <h5 class='section'>Used for:</h5> 1659 * <ul class='spaced-list'> 1660 * <li> 1661 * Server-side schema-based parsing. 1662 * <li> 1663 * Server-side generated Swagger documentation. 1664 * <li> 1665 * Client-side schema-based serializing. 1666 * </ul> 1667 * 1668 * <ul class='values spaced-list'> 1669 * <li> 1670 * <js>"string"</js> 1671 * <br>Parameter must be a string or a POJO convertible from a string. 1672 * <li> 1673 * <js>"number"</js> 1674 * <br>Parameter must be a number primitive or number object. 1675 * <br>If parameter is <c>Object</c>, creates either a <c>Float</c> or <c>Double</c> depending on the size of the number. 1676 * <li> 1677 * <js>"integer"</js> 1678 * <br>Parameter must be a integer/long primitive or integer/long object. 1679 * <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. 1680 * <li> 1681 * <js>"boolean"</js> 1682 * <br>Parameter must be a boolean primitive or object. 1683 * <li> 1684 * <js>"array"</js> 1685 * <br>Parameter must be an array or collection. 1686 * <br>Elements must be strings or POJOs convertible from strings. 1687 * <br>If parameter is <c>Object</c>, creates an {@link JsonList}. 1688 * <li> 1689 * <js>"object"</js> 1690 * <br>Parameter must be a map or bean. 1691 * <br>If parameter is <c>Object</c>, creates an {@link JsonMap}. 1692 * <br>Note that this is an extension of the OpenAPI schema as Juneau allows for arbitrarily-complex POJOs to be serialized as HTTP parts. 1693 * <li> 1694 * <js>"file"</js> 1695 * <br>This type is currently not supported. 1696 * </ul> 1697 * 1698 * <h5 class='section'>Notes:</h5><ul> 1699 * <li class='note'>Static strings are defined in {@link ParameterType}. 1700 * </ul> 1701 * 1702 * <h5 class='section'>See Also:</h5><ul> 1703 * <li class='extlink'><a class="doclink" href="https://swagger.io/specification#dataTypes">Swagger Data Types</a> 1704 * </ul> 1705 * 1706 * @return The annotation value. 1707 */ 1708 String type() default ""; 1709 1710 /** 1711 * Synonym for {@link #uniqueItems()}. 1712 * 1713 * @return The annotation value. 1714 */ 1715 boolean ui() default false; 1716 1717 /** 1718 * <mk>unevaluatedItems</mk> field of the JSON Schema. 1719 * 1720 * <p> 1721 * The value of "unevaluatedItems" MUST be a valid JSON Schema. 1722 * This schema applies to array items that were not evaluated by "items", "prefixItems", "contains", etc. 1723 * 1724 * <p> 1725 * This is a JSON Schema Draft 2020-12 property. 1726 * 1727 * <h5 class='section'>Notes:</h5><ul> 1728 * <li class='note'> 1729 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanJsonSchema">juneau-bean-jsonschema</a> object. 1730 * <br>Multiple lines are concatenated with newlines. 1731 * </ul> 1732 * 1733 * <h5 class='section'>See Also:</h5><ul> 1734 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.11.3">JSON Schema Core § 11.3</a> 1735 * </ul> 1736 * 1737 * @return The annotation value. 1738 */ 1739 String[] unevaluatedItems() default {}; 1740 1741 /** 1742 * <mk>unevaluatedProperties</mk> field of the JSON Schema. 1743 * 1744 * <p> 1745 * The value of "unevaluatedProperties" MUST be a valid JSON Schema. 1746 * This schema applies to object properties that were not evaluated by "properties", "patternProperties", etc. 1747 * 1748 * <p> 1749 * This is a JSON Schema Draft 2020-12 property. 1750 * 1751 * <h5 class='section'>Notes:</h5><ul> 1752 * <li class='note'> 1753 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanJsonSchema">juneau-bean-jsonschema</a> object. 1754 * <br>Multiple lines are concatenated with newlines. 1755 * </ul> 1756 * 1757 * <h5 class='section'>See Also:</h5><ul> 1758 * <li class='extlink'><a class="doclink" href="https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.11.3">JSON Schema Core § 11.3</a> 1759 * </ul> 1760 * 1761 * @return The annotation value. 1762 */ 1763 String[] unevaluatedProperties() default {}; 1764 1765 /** 1766 * <mk>uniqueItems</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1767 * 1768 * <p> 1769 * If <jk>true</jk> the input validates successfully if all of its elements are unique. 1770 * 1771 * <p> 1772 * If validation fails during serialization or parsing, the part serializer/parser will throw a {@link SchemaValidationException}. 1773 * <br>On the client-side, this gets converted to a <c>RestCallException</c> which is thrown before the connection is made. 1774 * <br>On the server-side, this gets converted to a <c>BadRequest</c> (400). 1775 * 1776 * <p> 1777 * If the parameter type is a subclass of {@link Set}, this validation is skipped (since a set can only contain unique items anyway). 1778 * <br>Otherwise, the collection or array is checked for duplicate items. 1779 * 1780 * <p> 1781 * Only allowed for the following types: <js>"array"</js>. 1782 * 1783 * <h5 class='section'>Used for:</h5> 1784 * <ul class='spaced-list'> 1785 * <li> 1786 * Server-side schema-based parsing validation. 1787 * <li> 1788 * Server-side generated Swagger documentation. 1789 * <li> 1790 * Client-side schema-based serializing validation. 1791 * </ul> 1792 * 1793 * @return The annotation value. 1794 */ 1795 boolean uniqueItems() default false; 1796 1797 /** 1798 * <mk>xml</mk> field of the <a class="doclink" href="https://swagger.io/specification/v2#schemaObject">Swagger Schema Object</a>. 1799 * 1800 * <h5 class='section'>Notes:</h5><ul> 1801 * <li class='note'> 1802 * The format is a <a class="doclink" href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2">juneau-bean-swagger-v2</a> object. 1803 * <br>Multiple lines are concatenated with newlines. 1804 * </ul> 1805 * 1806 * @return The annotation value. 1807 */ 1808 String[] xml() default {}; 1809}