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