0
# Schema and Media Types
1

2
This document covers annotations for defining data schemas, array schemas, content types, examples, and encoding specifications for OpenAPI documentation.
3

4
## Imports
5

6
```java { .api }
7
import io.swagger.v3.oas.annotations.media.Schema;
8
import io.swagger.v3.oas.annotations.media.ArraySchema;
9
import io.swagger.v3.oas.annotations.media.Content;
10
import io.swagger.v3.oas.annotations.media.ExampleObject;
11
import io.swagger.v3.oas.annotations.media.Encoding;
12
import io.swagger.v3.oas.annotations.media.DiscriminatorMapping;
13
import io.swagger.v3.oas.annotations.media.SchemaProperty;
14
import io.swagger.v3.oas.annotations.media.SchemaProperties;
15
import io.swagger.v3.oas.annotations.media.DependentRequired;
16
import io.swagger.v3.oas.annotations.media.DependentSchema;
17
import io.swagger.v3.oas.annotations.media.PatternProperty;
18
import io.swagger.v3.oas.annotations.media.PatternProperties;
19
import io.swagger.v3.oas.annotations.media.DependentRequiredMap;
20
import io.swagger.v3.oas.annotations.media.DependentSchemas;
21
```
22

23
## Schema
24

25
Defines comprehensive schemas for OpenAPI elements with extensive validation properties, type definitions, and OpenAPI 3.1 enhanced features.
26

27
### Basic Schema Definition
28

29
```java { .api }
30
@Schema(
31
    name = "Pet",
32
    description = "Pet information model with comprehensive validation",
33
    title = "Pet",
34
    type = "object",
35
    requiredProperties = {"name", "status"},
36
    example = "{ \"id\": 1, \"name\": \"Fluffy\", \"category\": { \"id\": 1, \"name\": \"Dogs\" }, \"status\": \"available\" }"
37
)
38
public class Pet {
39
    @Schema(
40
        description = "Pet identifier",
41
        example = "123",
42
        accessMode = Schema.AccessMode.READ_ONLY,
43
        type = "integer",
44
        format = "int64"
45
    )
46
    private Long id;
47
    
48
    @Schema(
49
        description = "Pet name",
50
        example = "Fluffy",
51
        minLength = 1,
52
        maxLength = 50,
53
        pattern = "^[a-zA-Z0-9\\s]+$",
54
        nullable = false
55
    )
56
    private String name;
57
    
58
    @Schema(
59
        description = "Pet category information", 
60
        implementation = Category.class,
61
        nullable = true
62
    )
63
    private Category category;
64
    
65
    @Schema(
66
        description = "Pet status in the store",
67
        allowableValues = {"available", "pending", "sold"},
68
        defaultValue = "available",
69
        example = "available"
70
    )
71
    private String status;
72
    
73
    @Schema(
74
        description = "Pet price",
75
        type = "number",
76
        format = "decimal", 
77
        minimum = "0",
78
        maximum = "10000",
79
        multipleOf = 0.01,
80
        exclusiveMinimum = true
81
    )
82
    private BigDecimal price;
83
}
84
```
85

86
### Advanced Schema Features
87

88
```java { .api }
89
@Schema(
90
    description = "Advanced pet model with complex validation",
91
    minProperties = 2,
92
    maxProperties = 20,
93
    additionalProperties = Schema.AdditionalPropertiesValue.FALSE,
94
    discriminatorProperty = "type",
95
    discriminatorMapping = {
96
        @DiscriminatorMapping(value = "dog", schema = Dog.class),
97
        @DiscriminatorMapping(value = "cat", schema = Cat.class)
98
    },
99
    subTypes = {Dog.class, Cat.class}
100
)
101
public abstract class Pet {
102
    @Schema(description = "Pet type discriminator", required = true)
103
    protected String type;
104
    
105
    @Schema(
106
        description = "Pet tags",
107
        uniqueItems = true,
108
        maxItems = 10,
109
        minItems = 0
110
    )
111
    private Set<String> tags;
112
}
113
```
114

115
### Composition Schemas
116

117
```java { .api }
118
// OneOf Schema
119
@Schema(
120
    description = "Payment method",
121
    oneOf = {CreditCard.class, PayPal.class, BankTransfer.class},
122
    discriminatorProperty = "type"
123
)
124
public abstract class PaymentMethod {
125
    protected String type;
126
}
127

128
// AllOf Schema  
129
@Schema(
130
    description = "Enhanced pet with location",
131
    allOf = {Pet.class, Location.class}
132
)
133
public class EnhancedPet {
134
    // Inherits all properties from Pet and Location
135
}
136

137
// AnyOf Schema
138
@Schema(
139
    description = "Contact information",
140
    anyOf = {EmailContact.class, PhoneContact.class, Address.class}
141
)
142
public class Contact {
143
    // Can be validated against any of the specified schemas
144
}
145

146
// Not Schema
147
@Schema(
148
    description = "Valid pet data",
149
    not = InvalidPet.class,
150
    implementation = Pet.class
151
)
152
public class ValidPet extends Pet {
153
    // Must not match InvalidPet schema
154
}
155
```
156

157
### OpenAPI 3.1 Features
158

159
```java { .api }
160
@Schema(
161
    description = "OpenAPI 3.1 enhanced schema",
162
    types = {"object", "null"},           // Multiple types
163
    $id = "https://example.com/pet.json", // Schema ID
164
    $schema = "https://json-schema.org/draft/2020-12/schema", // Schema dialect
165
    $anchor = "pet",                      // Schema anchor
166
    contentEncoding = "base64",           // Content encoding
167
    contentMediaType = "image/png",       // Content media type
168
    exclusiveMaximumValue = 100,          // Numeric exclusive maximum
169
    exclusiveMinimumValue = 0             // Numeric exclusive minimum
170
)
171
public class EnhancedPetSchema {
172
    @Schema(description = "Pet image data", contentEncoding = "base64")
173
    private String imageData;
174
}
175
```
176

177
### Schema Attributes
178

179
```java { .api }
180
public @interface Schema {
181
    // Core properties
182
    Class<?> implementation() default Void.class;
183
    Class<?> not() default Void.class;
184
    Class<?>[] oneOf() default {};
185
    Class<?>[] anyOf() default {};
186
    Class<?>[] allOf() default {};
187
    String name() default "";
188
    String title() default "";
189
    String description() default "";
190
    
191
    // Type and format
192
    String type() default "";
193
    String format() default "";
194
    String[] types() default {};         // OpenAPI 3.1
195
    
196
    // Validation constraints
197
    boolean nullable() default false;
198
    boolean deprecated() default false;
199
    double multipleOf() default 0;
200
    String maximum() default "";
201
    boolean exclusiveMaximum() default false;
202
    String minimum() default "";
203
    boolean exclusiveMinimum() default false;
204
    int maxLength() default Integer.MAX_VALUE;
205
    int minLength() default 0;
206
    String pattern() default "";
207
    int maxProperties() default 0;
208
    int minProperties() default 0;
209
    String[] requiredProperties() default {};
210
    
211
    @Deprecated
212
    boolean required() default false;                    // Deprecated since 2.2.5, use requiredMode
213
    
214
    // Enum and examples
215
    String[] allowableValues() default {};
216
    String defaultValue() default "";
217
    String example() default "";
218
    
219
    // OpenAPI 3.1 specific
220
    int exclusiveMaximumValue() default 0;
221
    int exclusiveMinimumValue() default 0;
222
    String $id() default "";
223
    String $schema() default "";
224
    String $anchor() default "";
225
    String $vocabulary() default "";                   // OpenAPI 3.1
226
    String $dynamicAnchor() default "";               // OpenAPI 3.1
227
    String $comment() default "";                      // OpenAPI 3.1
228
    String contentEncoding() default "";
229
    String contentMediaType() default "";
230
    
231
    // Access control
232
    AccessMode accessMode() default AccessMode.AUTO;
233
    RequiredMode requiredMode() default RequiredMode.AUTO;
234
    
235
    // Schema resolution control
236
    SchemaResolution schemaResolution() default SchemaResolution.AUTO;
237
    
238
    // OpenAPI 3.1 conditional schemas
239
    Class<?> _if() default Void.class;
240
    Class<?> _then() default Void.class;
241
    Class<?> _else() default Void.class;
242
    Class<?> then() default Void.class;                  // Alternative to _then
243
    
244
    // Additional properties and extensions
245
    AdditionalPropertiesValue additionalProperties() default AdditionalPropertiesValue.USE_ADDITIONAL_PROPERTIES_ANNOTATION;
246
    Extension[] extensions() default {};
247
    
248
    // Enums
249
    enum AccessMode { READ_ONLY, WRITE_ONLY, READ_WRITE, AUTO }
250
    enum AdditionalPropertiesValue { TRUE, FALSE, USE_ADDITIONAL_PROPERTIES_ANNOTATION }
251
    enum RequiredMode { AUTO, REQUIRED, NOT_REQUIRED }
252
    enum SchemaResolution { AUTO, DEFAULT, INLINE, ALL_OF, ALL_OF_REF }
253
}
254
```
255

256
## ArraySchema
257

258
Defines schemas specifically for array types with comprehensive array-specific validation and OpenAPI 3.1 enhanced features.
259

260
### Basic Array Schema
261

262
```java { .api }
263
@ArraySchema(
264
    schema = @Schema(implementation = Pet.class),
265
    arraySchema = @Schema(
266
        description = "List of pets in the store",
267
        example = "[{\"id\": 1, \"name\": \"Fluffy\"}, {\"id\": 2, \"name\": \"Buddy\"}]"
268
    ),
269
    minItems = 0,
270
    maxItems = 100,
271
    uniqueItems = true
272
)
273
private List<Pet> pets;
274

275
// Multi-dimensional arrays
276
@ArraySchema(
277
    schema = @ArraySchema(
278
        schema = @Schema(type = "integer"),
279
        arraySchema = @Schema(description = "Row of integers")
280
    ),
281
    arraySchema = @Schema(description = "Matrix of integers"),
282
    minItems = 1,
283
    maxItems = 10
284
)
285
private List<List<Integer>> matrix;
286
```
287

288
### OpenAPI 3.1 Array Features
289

290
```java { .api }
291
@ArraySchema(
292
    schema = @Schema(implementation = Pet.class),
293
    arraySchema = @Schema(description = "Enhanced pet list with 3.1 features"),
294
    
295
    // OpenAPI 3.1 specific properties
296
    contains = @Schema(
297
        description = "At least one pet must match this schema",
298
        properties = {
299
            @SchemaProperty(name = "featured", schema = @Schema(type = "boolean", allowableValues = "true"))
300
        }
301
    ),
302
    minContains = 1,
303
    maxContains = 5,
304
    
305
    // Prefix items for tuple validation
306
    prefixItems = {
307
        @Schema(description = "First pet (must be featured)", implementation = FeaturedPet.class),
308
        @Schema(description = "Second pet (any type)", implementation = Pet.class)
309
    },
310
    
311
    unevaluatedItems = @Schema(
312
        description = "Additional pets beyond prefix items",
313
        implementation = StandardPet.class
314
    )
315
)
316
private List<Pet> enhancedPetList;
317
```
318

319
### ArraySchema Attributes
320

321
```java { .api }
322
public @interface ArraySchema {
323
    Schema schema() default @Schema;
324
    Schema arraySchema() default @Schema;
325
    int maxItems() default Integer.MIN_VALUE;
326
    int minItems() default Integer.MAX_VALUE;
327
    boolean uniqueItems() default false;
328
    Extension[] extensions() default {};
329
    
330
    // OpenAPI 3.1 features
331
    Schema contains() default @Schema;
332
    int maxContains() default 0;
333
    int minContains() default 0;
334
    Schema unevaluatedItems() default @Schema;
335
    Schema[] prefixItems() default {};
336
}
337
```
338

339
## Content
340

341
Defines content and media types for parameters, request bodies, or responses with comprehensive schema and example definitions.
342

343
### Basic Content Definition
344

345
```java { .api }
346
@Content(
347
    mediaType = "application/json",
348
    schema = @Schema(implementation = Pet.class),
349
    examples = {
350
        @ExampleObject(
351
            name = "petExample",
352
            summary = "Example pet",
353
            description = "A complete example of a pet object",
354
            value = "{ \"id\": 1, \"name\": \"Fluffy\", \"category\": { \"id\": 1, \"name\": \"Dogs\" }, \"status\": \"available\" }"
355
        ),
356
        @ExampleObject(
357
            name = "minimalPet",
358
            summary = "Minimal pet example",
359
            value = "{ \"name\": \"Buddy\", \"status\": \"available\" }"
360
        )
361
    }
362
)
363

364
// Multiple content types
365
@Content(mediaType = "application/json", schema = @Schema(implementation = Pet.class))
366
@Content(mediaType = "application/xml", schema = @Schema(implementation = Pet.class))
367
@Content(mediaType = "text/plain", schema = @Schema(type = "string"))
368
```
369

370
### Advanced Content with Schema Properties
371

372
```java { .api }
373
@Content(
374
    mediaType = "application/json",
375
    schemaProperties = {
376
        @SchemaProperty(
377
            name = "pet",
378
            schema = @Schema(implementation = Pet.class)
379
        ),
380
        @SchemaProperty(
381
            name = "metadata",
382
            schema = @Schema(
383
                type = "object",
384
                description = "Additional metadata"
385
            )
386
        ),
387
        @SchemaProperty(
388
            name = "tags",
389
            array = @ArraySchema(
390
                schema = @Schema(type = "string"),
391
                minItems = 0,
392
                maxItems = 10
393
            )
394
        )
395
    }
396
)
397
```
398

399
### Form Data Content with Encoding
400

401
```java { .api }
402
@Content(
403
    mediaType = "multipart/form-data",
404
    schema = @Schema(implementation = PetUploadRequest.class),
405
    encoding = {
406
        @Encoding(
407
            name = "petData",
408
            contentType = "application/json",
409
            style = "form",
410
            explode = true,
411
            headers = {
412
                @Header(
413
                    name = "X-Pet-Version",
414
                    description = "Pet data format version",
415
                    schema = @Schema(type = "string", defaultValue = "1.0")
416
                )
417
            }
418
        ),
419
        @Encoding(
420
            name = "image",
421
            contentType = "image/jpeg, image/png",
422
            headers = {
423
                @Header(
424
                    name = "Content-Disposition",
425
                    schema = @Schema(type = "string", defaultValue = "form-data")
426
                )
427
            }
428
        )
429
    }
430
)
431
```
432

433
### OpenAPI 3.1 Content Features
434

435
```java { .api }
436
@Content(
437
    mediaType = "application/json",
438
    
439
    // OpenAPI 3.1 conditional schemas
440
    dependentSchemas = {
441
        @DependentSchema(
442
            name = "petType",
443
            schema = @Schema(
444
                _if = @Schema(properties = {
445
                    @SchemaProperty(name = "type", schema = @Schema(allowableValues = "dog"))
446
                }),
447
                _then = @Schema(properties = {
448
                    @SchemaProperty(name = "breed", schema = @Schema(type = "string", required = true))
449
                }),
450
                _else = @Schema(properties = {
451
                    @SchemaProperty(name = "species", schema = @Schema(type = "string", required = true))
452
                })
453
            )
454
        )
455
    },
456
    
457
    contentSchema = @Schema(implementation = Pet.class),
458
    propertyNames = @Schema(pattern = "^[a-zA-Z_][a-zA-Z0-9_]*$"),
459
    
460
    // Composition schemas in content
461
    oneOf = {
462
        @Schema(implementation = Dog.class),
463
        @Schema(implementation = Cat.class),
464
        @Schema(implementation = Bird.class)
465
    },
466
    anyOf = {
467
        @Schema(implementation = Pet.class),
468
        @Schema(implementation = Toy.class)
469
    },
470
    allOf = {
471
        @Schema(implementation = Animal.class),
472
        @Schema(implementation = Domesticated.class)
473
    }
474
)
475
```
476

477
### Content Attributes
478

479
```java { .api }
480
public @interface Content {
481
    String mediaType() default "";
482
    ExampleObject[] examples() default {};
483
    Schema schema() default @Schema();
484
    SchemaProperty[] schemaProperties() default {};
485
    Schema additionalPropertiesSchema() default @Schema();
486
    ArraySchema additionalPropertiesArraySchema() default @ArraySchema();
487
    ArraySchema array() default @ArraySchema();
488
    Encoding[] encoding() default {};
489
    Extension[] extensions() default {};
490
    
491
    // OpenAPI 3.1 features
492
    DependentSchema[] dependentSchemas() default {};
493
    Schema contentSchema() default @Schema();
494
    Schema propertyNames() default @Schema();
495
    Schema _if() default @Schema();
496
    Schema _then() default @Schema();
497
    Schema _else() default @Schema();
498
    Schema not() default @Schema();
499
    Schema[] oneOf() default {};
500
    Schema[] anyOf() default {};
501
    Schema[] allOf() default {};
502
}
503
```
504

505
## ExampleObject
506

507
Provides comprehensive examples for parameters, request bodies, and response content with support for external references and extensions.
508

509
### Basic Examples
510

511
```java { .api }
512
@ExampleObject(
513
    name = "createPetExample",
514
    summary = "Create a new pet",
515
    description = "Example showing how to create a new pet with all required fields",
516
    value = """
517
        {
518
            "name": "Fluffy",
519
            "category": {
520
                "id": 1,
521
                "name": "Dogs"
522
            },
523
            "status": "available",
524
            "tags": ["friendly", "trained"],
525
            "photoUrls": ["https://example.com/photos/fluffy1.jpg"]
526
        }
527
        """
528
)
529

530
@ExampleObject(
531
    name = "updatePetExample", 
532
    summary = "Update existing pet",
533
    description = "Example showing partial update of pet information",
534
    value = """
535
        {
536
            "name": "Fluffy Updated",
537
            "status": "sold"
538
        }
539
        """
540
)
541

542
// External example reference
543
@ExampleObject(
544
    name = "complexPetExample",
545
    summary = "Complex pet with all fields",
546
    externalValue = "https://api.petstore.io/examples/complex-pet.json",
547
    description = "Comprehensive example hosted externally"
548
)
549
```
550

551
### Multiple Examples in Content
552

553
```java { .api }
554
@Content(
555
    mediaType = "application/json",
556
    schema = @Schema(implementation = Pet.class),
557
    examples = {
558
        @ExampleObject(
559
            name = "dog",
560
            summary = "Dog example",
561
            description = "Example of a dog pet",
562
            value = """
563
                {
564
                    "id": 1,
565
                    "name": "Buddy",
566
                    "category": {"id": 1, "name": "Dogs"},
567
                    "breed": "Golden Retriever",
568
                    "status": "available"
569
                }
570
                """
571
        ),
572
        @ExampleObject(
573
            name = "cat", 
574
            summary = "Cat example",
575
            description = "Example of a cat pet",
576
            value = """
577
                {
578
                    "id": 2,
579
                    "name": "Whiskers", 
580
                    "category": {"id": 2, "name": "Cats"},
581
                    "indoor": true,
582
                    "status": "available"
583
                }
584
                """
585
        ),
586
        @ExampleObject(
587
            name = "errorExample",
588
            summary = "Error response example",
589
            description = "Example error when pet not found",
590
            value = """
591
                {
592
                    "error": "Pet not found",
593
                    "code": 404,
594
                    "message": "No pet exists with the provided ID"
595
                }
596
                """
597
        )
598
    }
599
)
600
```
601

602
### ExampleObject Attributes
603

604
```java { .api }
605
public @interface ExampleObject {
606
    String name() default "";
607
    String summary() default "";
608
    String value() default "";
609
    String externalValue() default "";
610
    Extension[] extensions() default {};
611
    String ref() default "";
612
    String description() default "";
613
}
614
```
615

616
## Encoding
617

618
Defines encoding details for multipart and form data content types, including headers and serialization options.
619

620
### Multipart Form Encoding
621

622
```java { .api }
623
@Content(
624
    mediaType = "multipart/form-data",
625
    schema = @Schema(implementation = PetUploadForm.class),
626
    encoding = {
627
        @Encoding(
628
            name = "petJson",
629
            contentType = "application/json",
630
            style = "form",
631
            explode = true,
632
            allowReserved = false,
633
            headers = {
634
                @Header(
635
                    name = "X-Pet-Format-Version",
636
                    description = "Version of the pet JSON format",
637
                    schema = @Schema(type = "string", defaultValue = "2.0")
638
                )
639
            }
640
        ),
641
        @Encoding(
642
            name = "photos",
643
            contentType = "image/jpeg, image/png, image/gif",
644
            style = "form",
645
            explode = true,
646
            headers = {
647
                @Header(
648
                    name = "Content-Disposition",
649
                    description = "File disposition header",
650
                    schema = @Schema(type = "string")
651
                ),
652
                @Header(
653
                    name = "X-Image-Quality",
654
                    description = "Image quality indicator",
655
                    schema = @Schema(type = "string", allowableValues = {"low", "medium", "high"})
656
                )
657
            }
658
        ),
659
        @Encoding(
660
            name = "metadata",
661
            contentType = "application/json",
662
            style = "deepObject", 
663
            explode = true
664
        )
665
    }
666
)
667
```
668

669
### Form URL Encoded Data
670

671
```java { .api }
672
@Content(
673
    mediaType = "application/x-www-form-urlencoded",
674
    schema = @Schema(implementation = SearchForm.class),
675
    encoding = {
676
        @Encoding(
677
            name = "categories",
678
            style = "form",
679
            explode = true,
680
            allowReserved = false
681
        ),
682
        @Encoding(
683
            name = "dateRange",
684
            style = "deepObject",
685
            explode = true
686
        )
687
    }
688
)
689
```
690

691
### Encoding Attributes
692

693
```java { .api }
694
public @interface Encoding {
695
    String name() default "";
696
    String contentType() default "";
697
    String style() default "";
698
    boolean explode() default false;
699
    boolean allowReserved() default false;
700
    Header[] headers() default {};
701
    Extension[] extensions() default {};
702
}
703
```
704

705
## Schema Properties and Dependent Schemas
706

707
### SchemaProperty and SchemaProperties
708

709
Define individual properties for object schemas with detailed configurations.
710

711
```java { .api }
712
@SchemaProperties({
713
    @SchemaProperty(
714
        name = "id",
715
        schema = @Schema(
716
            type = "integer",
717
            format = "int64", 
718
            description = "Pet identifier",
719
            minimum = "1"
720
        )
721
    ),
722
    @SchemaProperty(
723
        name = "name",
724
        schema = @Schema(
725
            type = "string",
726
            description = "Pet name",
727
            minLength = 1,
728
            maxLength = 50,
729
            pattern = "^[a-zA-Z0-9\\s]+$"
730
        )
731
    ),
732
    @SchemaProperty(
733
        name = "categories",
734
        array = @ArraySchema(
735
            schema = @Schema(implementation = Category.class),
736
            minItems = 0,
737
            maxItems = 5,
738
            uniqueItems = true
739
        )
740
    )
741
})
742
```
743

744
### DependentRequired (OpenAPI 3.1)
745

746
Define conditional required fields based on the presence of other fields.
747

748
```java { .api }
749
@DependentRequired(name = "creditCard", value = {"cardNumber", "expiryDate", "cvv"})
750
@DependentRequired(name = "paypal", value = {"paypalEmail"})
751
@DependentRequired(name = "bankTransfer", value = {"accountNumber", "routingNumber"})
752
@Schema(description = "Payment information with dependent requirements")
753
public class PaymentInfo {
754
    private String paymentMethod; // "creditCard", "paypal", "bankTransfer"
755
    private String cardNumber;
756
    private String expiryDate;
757
    private String cvv;
758
    private String paypalEmail;
759
    private String accountNumber;
760
    private String routingNumber;
761
}
762
```
763

764
### DependentSchema (OpenAPI 3.1)
765

766
Define conditional schemas that apply when certain conditions are met.
767

768
```java { .api }
769
@Content(
770
    mediaType = "application/json",
771
    dependentSchemas = {
772
        @DependentSchema(
773
            name = "petType",
774
            schema = @Schema(
775
                // If pet type is "dog", then breed is required
776
                _if = @Schema(
777
                    properties = @SchemaProperty(
778
                        name = "type", 
779
                        schema = @Schema(allowableValues = "dog")
780
                    )
781
                ),
782
                _then = @Schema(
783
                    properties = @SchemaProperty(
784
                        name = "breed",
785
                        schema = @Schema(type = "string", required = true)
786
                    )
787
                ),
788
                // If pet type is "cat", then indoor status is required
789
                _else = @Schema(
790
                    _if = @Schema(
791
                        properties = @SchemaProperty(
792
                            name = "type",
793
                            schema = @Schema(allowableValues = "cat") 
794
                        )
795
                    ),
796
                    _then = @Schema(
797
                        properties = @SchemaProperty(
798
                            name = "indoor",
799
                            schema = @Schema(type = "boolean", required = true)
800
                        )
801
                    )
802
                )
803
            )
804
        )
805
    }
806
)
807
```
808

809
## DiscriminatorMapping
810

811
Define mappings for polymorphic schemas using discriminator properties.
812

813
```java { .api }
814
@Schema(
815
    description = "Base animal class with discriminator",
816
    discriminatorProperty = "animalType",
817
    discriminatorMapping = {
818
        @DiscriminatorMapping(value = "dog", schema = Dog.class),
819
        @DiscriminatorMapping(value = "cat", schema = Cat.class),
820
        @DiscriminatorMapping(value = "bird", schema = Bird.class)
821
    },
822
    oneOf = {Dog.class, Cat.class, Bird.class}
823
)
824
public abstract class Animal {
825
    @Schema(description = "Type of animal", required = true)
826
    protected String animalType;
827
    
828
    @Schema(description = "Animal name", required = true)
829
    protected String name;
830
}
831

832
@Schema(description = "Dog specific properties")
833
public class Dog extends Animal {
834
    @Schema(description = "Dog breed")
835
    private String breed;
836
    
837
    @Schema(description = "Is house trained")
838
    private Boolean houseTrained;
839
    
840
    public Dog() {
841
        this.animalType = "dog";
842
    }
843
}
844
```
845

846
## Pattern Properties (OpenAPI 3.1)
847

848
Define schema properties based on property name patterns.
849

850
```java { .api }
851
@PatternProperty(
852
    pattern = "^[a-zA-Z]+_[0-9]+$",
853
    schema = @Schema(
854
        type = "object",
855
        description = "Properties matching pattern prefix_number",
856
        properties = {
857
            @SchemaProperty(name = "value", schema = @Schema(type = "string")),
858
            @SchemaProperty(name = "type", schema = @Schema(type = "string"))
859
        }
860
    )
861
)
862
@PatternProperty(
863
    pattern = "^temp_.*",
864
    schema = @Schema(
865
        type = "string",
866
        description = "Temporary properties (strings only)"
867
    )
868
)
869
@Schema(description = "Dynamic properties with pattern-based validation")
870
public class DynamicConfig {
871
    // Static properties
872
    @Schema(description = "Configuration name")
873
    private String name;
874
    
875
    // Dynamic properties will be validated against patterns
876
    // Examples: config_1, config_2 (matches first pattern)
877
    //           temp_data, temp_cache (matches second pattern)
878
}
879
```
880

881
## Dependent Required and Schemas (OpenAPI 3.1)
882

883
OpenAPI 3.1 introduces conditional validation through dependent required fields and dependent schemas.
884

885
### DependentRequired
886

887
Define conditional required fields based on the presence of other fields.
888

889
```java { .api }
890
@Schema(description = "Payment information with conditional requirements")
891
public class PaymentInfo {
892
    @Schema(description = "Payment method type")
893
    private String paymentMethod; // "creditCard", "paypal", "bankTransfer"
894
    
895
    // These fields are required only if paymentMethod is "creditCard"
896
    @DependentRequired(name = "creditCard", value = {"cardNumber", "expiryDate", "cvv"})
897
    private String cardNumber;
898
    
899
    @DependentRequired(name = "creditCard", value = {"cardNumber", "expiryDate", "cvv"}) 
900
    private String expiryDate;
901
    
902
    @DependentRequired(name = "creditCard", value = {"cardNumber", "expiryDate", "cvv"})
903
    private String cvv;
904
    
905
    // Required only if paymentMethod is "paypal"
906
    @DependentRequired(name = "paypal", value = {"paypalEmail"})
907
    private String paypalEmail;
908
    
909
    // Required only if paymentMethod is "bankTransfer"
910
    @DependentRequired(name = "bankTransfer", value = {"accountNumber", "routingNumber"})
911
    private String accountNumber;
912
    
913
    @DependentRequired(name = "bankTransfer", value = {"accountNumber", "routingNumber"})
914
    private String routingNumber;
915
}
916
```
917

918
### DependentSchema
919

920
Define conditional schemas that apply when certain conditions are met.
921

922
```java { .api }
923
@Schema(
924
    description = "Pet with type-dependent validation",
925
    dependentSchemas = {
926
        @StringToClassMapItem(key = "petType", value = PetTypeSchema.class)
927
    }
928
)
929
public class ConditionalPet {
930
    @Schema(description = "Pet type", allowableValues = {"dog", "cat", "bird"})
931
    private String type;
932
    
933
    @Schema(description = "Pet name")
934
    private String name;
935
    
936
    // Additional fields validated based on type
937
    @Schema(description = "Dog breed (required for dogs)")
938
    private String breed;
939
    
940
    @Schema(description = "Indoor status (required for cats)")
941
    private Boolean indoor;
942
    
943
    @Schema(description = "Wingspan (required for birds)")
944
    private Double wingspan;
945
}
946
```
947

948
### DependentRequired Attributes
949

950
```java { .api }
951
public @interface DependentRequired {
952
    String name();                    // Property name that triggers the requirement
953
    String[] value();                 // Array of properties that become required
954
    Extension[] extensions() default {};
955
}
956
```
957

958
### DependentRequiredMap
959

960
Container annotation for multiple dependent required definitions.
961

962
```java { .api }
963
@DependentRequiredMap({
964
    @DependentRequired(name = "creditCard", value = {"cardNumber", "expiryDate", "cvv"}),
965
    @DependentRequired(name = "paypal", value = {"paypalEmail"}),
966
    @DependentRequired(name = "bankTransfer", value = {"accountNumber", "routingNumber"})
967
})
968
public class PaymentConfiguration {
969
    // Payment configuration with multiple conditional requirements
970
}
971
```
972

973
## Enhanced Pattern Properties (OpenAPI 3.1)
974

975
### PatternProperties Attributes
976

977
```java { .api }
978
public @interface PatternProperty {
979
    String pattern();                           // Regular expression pattern
980
    Schema schema() default @Schema();          // Schema for matching properties
981
    Extension[] extensions() default {};
982
}
983

984
public @interface PatternProperties {
985
    PatternProperty[] value();                  // Array of pattern property definitions
986
}
987
```