Package com.asyncapi.schemas.openapi.v3._0_0

Class OpenAPISchema

java.lang.Object
com.asyncapi.schemas.openapi.v3._0_0.properties.Extensions
com.asyncapi.schemas.openapi.v3._0_0.OpenAPISchema
public class OpenAPISchema extends Extensions
The Schema Object allows the definition of input and output data types.

These types can be objects, but also primitives and arrays.

This object is an extended subset of the JSON Schema Specification Wright Draft 00.

For more information about the properties, see JSON Schema Core and JSON Schema Validation. Unless stated otherwise, the property definitions follow the JSON Schema.

Version:
3.0.0
Author:
Pavel Bodiachevskii
See Also:

  • Field Details

    • name

      public String name
      Schema name.

    • title

      @Nullable public @Nullable String title
      The value of these keyword MUST be a string.

      This keywords can be used to decorate a user interface with information about the data produced by this user interface.

      A title will preferably be short

      See Also:

    • multipleOf

      @Nullable public @Nullable BigDecimal multipleOf
      Use the multipleOf keyword to specify that a number must be the multiple of another number: 
      
 type: integer
 multipleOf: 10
      The example above matches 10, 20, 30, 0, -10, -20, and so on.

      multipleOf may be used with floating-point numbers, but in practice this can be unreliable due to the limited precision or floating point math. 

      
 type: number
 multipleOf: 2.5
      The value of multipleOf MUST be a positive number, that is, you cannot use multipleOf: -5.
      See Also:

    • maximum

      @Nullable public @Nullable BigDecimal maximum
      Use the minimum and maximum keywords to specify the range of possible values: 
      
 type: integer
 minimum: 1
 maximum: 20
      By default, the minimum and maximum values are included in the range, that is: 
      
 minimum ≤ value ≤ maximum
      To exclude the boundary values, specify exclusiveMinimum: true and exclusiveMaximum: true. 
      
 exclusiveMinimum: true
 exclusiveMaximum: true
      For example, you can define a floating-point number range as 0–50 and exclude the 0 value:
      See Also:

    • exclusiveMaximum

      @Nullable public @Nullable Boolean exclusiveMaximum
      The word “exclusive” in exclusiveMinimum and exclusiveMaximum means the corresponding boundary is excluded:
      Keyword Description
      exclusiveMinimum: false or not included value ≥ minimum
      exclusiveMinimum: true value > minimum
      exclusiveMaximum: false or not included value ≤ maximum
      exclusiveMaximum: true value < maximum
      See Also:

    • minimum

      @Nullable public @Nullable BigDecimal minimum
      Use the minimum and maximum keywords to specify the range of possible values: 
      
 type: integer
 minimum: 1
 maximum: 20
      By default, the minimum and maximum values are included in the range, that is: 
      
 minimum ≤ value ≤ maximum
      To exclude the boundary values, specify exclusiveMinimum: true and exclusiveMaximum: true. 
      
 exclusiveMinimum: true
 exclusiveMaximum: true
      For example, you can define a floating-point number range as 0–50 and exclude the 0 value:
      See Also:

    • exclusiveMinimum

      @Nullable public @Nullable Boolean exclusiveMinimum
      The word “exclusive” in exclusiveMinimum and exclusiveMaximum means the corresponding boundary is excluded:
      Keyword Description
      exclusiveMinimum: false or not included value ≥ minimum
      exclusiveMinimum: true value > minimum
      exclusiveMaximum: false or not included value ≤ maximum
      exclusiveMaximum: true value < maximum
      See Also:

    • maxLength

      @Nullable public @Nullable Integer maxLength
      String length can be restricted using minLength and maxLength: 
      
 type: string
 minLength: 3
 maxLength: 20
      See Also:

    • minLength

      @Nullable public @Nullable Integer minLength
      String length can be restricted using minLength and maxLength: 
      
 type: string
 minLength: 3
 maxLength: 20
      See Also:

    • pattern

      @Nullable public @Nullable String pattern
      The pattern keyword lets you define a regular expression template for the string value.

      Only the values that match this template will be accepted. The regular expression syntax used is from JavaScript (more specifically, ECMA 262).

      Regular expressions are case-sensitive, that is, [a-z] and [A-Z] are different expressions.

      For example, the following pattern matches a Social Security Number (SSN) in the 123-45-6789 format:

      See Also:

    • maxItems

      @Nullable public @Nullable Integer maxItems
      You can define the minimum and maximum length of an array like so: 
      
 type: array
 items:
   type: integer
 minItems: 1
 maxItems: 10
      See Also:

    • minItems

      @Nullable public @Nullable Integer minItems
      You can define the minimum and maximum length of an array like so: 
      
 type: array
 items:
   type: integer
 minItems: 1
 maxItems: 10
      See Also:

    • uniqueItems

      @Nullable public @Nullable Boolean uniqueItems
      You can use uniqueItems: true to specify that all items in the array must be unique: 
      
 type: array
 items:
   type: integer
 uniqueItems: true
 # [1, 2, 3] – valid
 # [1, 1, 3] – not valid
 # [ ] – valid

    • maxProperties

      @Nullable public @Nullable Integer maxProperties
      The minProperties and maxProperties keywords let you restrict the number of properties allowed in an object. This can be useful when using additionalProperties or free-form objects. 
      
 type: object
 minProperties: 2
 maxProperties: 10
      See Also:

    • minProperties

      @Nullable public @Nullable Integer minProperties
      The minProperties and maxProperties keywords let you restrict the number of properties allowed in an object. This can be useful when using additionalProperties or free-form objects. 
      
 type: object
 minProperties: 2
 maxProperties: 10
      See Also:

    • required

      @Nullable public @Nullable List<String> required
      By default, all object properties are optional. You can specify the required properties in the required list: 
      
 type: object
 properties:
   id:
     type: integer
   username:
     type: string
   name:
     type: string
 required:
   - id
   - username
      Note that required is an object-level attribute, not a property attribute: 
      
 type: object
 properties:
   id:
     type: integer
     required: true  # Wrong!
 required:           # Correct
   - id
      See Also:

    • type

      @Nullable public @Nullable String type
      The data type of a schema is defined by the type keyword, for example, type: string.

      OpenAPI defines the following basic types:

      • string (this includes dates and files)
      • number
      • integer
      • boolean
      • array
      • object
      These types exist in most programming languages, though they may go by different names. Using these types, you can describe any data structures.

      Note that there is no null type; instead, the nullable attribute is used as a modifier of the base type.

      Additional type-specific keywords can be used to refine the data type, for example, limit the string length or specify an enum of possible values.

      See Also:

    • allOf

      @Nullable public @Nullable List<OpenAPISchema> allOf
      OpenAPI lets you combine and extend model definitions using the allOf keyword. allOf takes an array of object definitions that are used for independent validation but together compose a single object.

      Still, it does not imply a hierarchy between the models. For that purpose, you should include the discriminator.

      To be valid against allOf, the data provided by the client must be valid against all of the given subschemas. In the following example, allOf acts as a tool for combining schemas used in specific cases with the general one.

      For more clearness, oneOf is also used with a discriminator. 

      
 components:
   schemas:
     Pet:
       type: object
       required:
         - pet_type
       properties:
         pet_type:
           type: string
       discriminator:
         propertyName: pet_type
     Dog:     # "Dog" is a value for the pet_type property (the discriminator value)
       allOf: # Combines the main `Pet` schema with `Dog`-specific properties
         - $ref: '#/components/schemas/Pet'
         - type: object
           # all other properties specific to a `Dog`
           properties:
             bark:
               type: boolean
             breed:
               type: string
               enum: [Dingo, Husky, Retriever, Shepherd]
     Cat:     # "Cat" is a value for the pet_type property (the discriminator value)
       allOf: # Combines the main `Pet` schema with `Cat`-specific properties
         - $ref: '#/components/schemas/Pet'
         - type: object
           # all other properties specific to a `Cat`
           properties:
             hunts:
               type: boolean
             age:
               type: integer
      As you can see, this example validates the request body content to make sure it includes all the information needed to update a pet item with the PUT operation.

      It requires user to specify which type of the item should be updated, and validates against the specified schema according to their choice. Note the inline or referenced schema must be a schema object, not a standard JSON schema.

      For that example, all of the following request bodies are valid: 

      
 {
   "pet_type": "Cat",
   "age": 3
 }
 
      
 {
   "pet_type": "Dog",
   "bark": true
 }
 
      
 {
   "pet_type": "Dog",
   "bark": false,
   "breed": "Dingo"
 }
      The following request bodies are not valid: 
      
 {
   "age": 3        # Does not include the pet_type property
 }
 
      
 {
   "pet_type": "Cat",
   "bark": true    # The `Cat` schema does not have the `bark` property
 }
      See Also:

    • anyOf

      @Nullable public @Nullable List<OpenAPISchema> anyOf
      Use the anyOf keyword to validate the data against any amount of the given subschemas. That is, the data may be valid against one or more subschemas at the same time. 
      
 paths:
   /pets:
     patch:
       requestBody:
         content:
           application/json:
             schema:
               anyOf:
                 - $ref: '#/components/schemas/PetByAge'
                 - $ref: '#/components/schemas/PetByType'
       responses:
         '200':
           description: Updated
 components:
   schemas:
     PetByAge:
       type: object
       properties:
         age:
           type: integer
         nickname:
           type: string
       required:
         - age

     PetByType:
       type: object
       properties:
         pet_type:
           type: string
           enum: [Cat, Dog]
         hunts:
           type: boolean
       required:
         - pet_type
      Note the inline or referenced schema must be a schema object, not a standard JSON schema. With this example, the following JSON request bodies are valid: 
      
 {
   "age": 1
 }
 
      
 {
   "pet_type": "Cat",
   "hunts": true
 }
 
      
 {
   "nickname": "Fido",
   "pet_type": "Dog",
   "age": 4
 }
      The following example is not valid, because it does not contain any of the required properties for both of the schemas: 
      
 {
   "nickname": "Mr. Paws",
   "hunts": false
 }
      See Also:

    • oneOf

      @Nullable public @Nullable List<OpenAPISchema> oneOf
      oneOf matches exactly one subschema, and anyOf can match one or more subschemas.

      To better understand the difference, use the anyOf example but replace anyOf with oneOf. When using oneOf, the following request body is not valid because it matches both schemas and not just one: 

      
 {
   "nickname": "Fido",
   "pet_type": "Dog",
   "age": 4
 }
      See Also:

    • not

      @Nullable public @Nullable OpenAPISchema not
      The not keyword does not exactly combine schemas, but as all of the keywords mentioned above it helps you to modify your schemas and make them more specific. 
      
 paths:
   /pets:
     patch:
       requestBody:
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/PetByType'
       responses:
         '200':
           description: Updated
 components:
   schemas:
     PetByType:
       type: object
       properties:
         pet_type:
           not:
             type: integer
       required:
         - pet_type
      In this example, user should specify the pet_type value of any type except integer (that is, it should be an array, boolean, number, object, or string). The following request body is valid: 
      
 {
   "pet_type": "Cat"
 }
      And the following is not valid: 
      
 {
   "pet_type": 11
 }
      See Also:

    • properties

      @Nullable public @Nullable Map<String,OpenAPISchema> properties
      The properties keyword is used to define the object properties – you need to list the property names and specify a schema for each property. 
      
 type: object
 properties:
   id:
     type: integer
   name:
     type: string
      See Also:

    • additionalProperties

      @Nullable public @Nullable Object additionalProperties
      The value can be a boolean (true or false) or an OpenAPISchema. 
      
 type: object
 additionalProperties: true
 
      
 type: object
 additionalProperties: {}

    • description

      @Nullable public @Nullable String description
      The value of these keyword MUST be a string.

      This keywords can be used to decorate a user interface with information about the data produced by this user interface.

      A description will provide explanation about the purpose of the instance described by this schema.

      See Also:

    • format

      @Nullable public @Nullable String format
      Format modifier serves as a hint at the contents and format of the string.
      See Also:

    • ref

      @Nullable public @Nullable String ref
      Reference to OpenAPI Schema definition.

    • nullable

      @Nullable public @Nullable Boolean nullable
      OpenAPI 3.0 does not have an explicit null type as in JSON Schema, but you can use nullable: true to specify that the value may be null. Note that null is different from an empty string "". 
      
 # Correct
 type: integer
 nullable: true
 # Incorrect
 type: null
 # Incorrect as well
 type:
   - integer
   - null
      See Also:

    • readOnly

      @Nullable public @Nullable Boolean readOnly
      You can use the readOnly and writeOnly keywords to mark specific properties as read-only or write-only.

      This is useful, for example, when GET returns more properties than used in POST – you can use the same schema in both GET and POST and mark the extra properties as readOnly.

      readOnly properties are included in responses but not in requests, and writeOnly properties may be sent in requests but not in responses. 

      
 type: object
 properties:
   id:
     # Returned by GET, not used in POST/PUT/PATCH
     type: integer
     readOnly: true
   username:
     type: string
   password:
     # Used in POST/PUT/PATCH, not returned by GET
     type: string
     writeOnly: true
      If a readOnly or writeOnly property is included in the required list, required affects just the relevant scope – responses only or requests only.

      That is, read-only required properties apply to responses only, and write-only required properties – to requests only.

      See Also:

    • writeOnly

      @Nullable public @Nullable Boolean writeOnly
      You can use the readOnly and writeOnly keywords to mark specific properties as read-only or write-only.

      This is useful, for example, when GET returns more properties than used in POST – you can use the same schema in both GET and POST and mark the extra properties as readOnly.

      readOnly properties are included in responses but not in requests, and writeOnly properties may be sent in requests but not in responses. 

      
 type: object
 properties:
   id:
     # Returned by GET, not used in POST/PUT/PATCH
     type: integer
     readOnly: true
   username:
     type: string
   password:
     # Used in POST/PUT/PATCH, not returned by GET
     type: string
     writeOnly: true
      If a readOnly or writeOnly property is included in the required list, required affects just the relevant scope – responses only or requests only.

      That is, read-only required properties apply to responses only, and write-only required properties – to requests only.

      See Also:

    • example

      @Nullable public @Nullable Object example
      You can add examples to parameters, properties and objects to make OpenAPI specification of your web service clearer. Examples can be read by tools and libraries that process your API in some way.

      For example, an API mocking tool can use sample values to generate mock requests. You can specify examples for objects, individual properties and operation parameters 

      
 parameters:
   - in: query
     name: status
     schema:
       type: string
       enum: [approved, pending, closed, new]
       example: approved     # Example of a parameter value
 
      
 parameters:
   - in: query
     name: limit
     schema:
       type: integer
       maximum: 50
     example:
       zero:         # Distinct name
         value: 0    # Example value
         summary: A sample limit value  # Optional description

    • externalDocs

      @Nullable public @Nullable ExternalDocumentation externalDocs
      External resource for extended documentation

    • deprecated

      @Nullable public @Nullable Boolean deprecated
      You can mark OpenAPI Schema as deprecated, by setting deprecated: true

    • xml

      @Nullable public @Nullable XML xml
      In your API specification, you can describe data in both XML and JSON formats as they are easily interchangeable.

      For example, the following declaration — 

      
 components:
   schemas:
     book:
       type: object
       properties:
         id:
           type: integer
         title:
           type: string
         author:
           type: string
      — is represented in the following way in JSON and XML:
      JSON 
      
 {
   "id": 0,
   "title": "string",
   "author": "string"
 }
      XML 
      
 <book>
   <id>0</id>
   <title>string</title>
   <author>string</author>
 </book>
      As you can see, in XML representation, the object name serves as a parent element and properties are translated to child elements.

      The OpenAPI 3 format offers a special xml object to help you fine-tune representation of XML data. You can use this object to transform some properties to attributes rather than elements, to change element names, to add namespaces and to control transformations of array items.

      See Also:

    • enumValue

      @Nullable public @Nullable List<Object> enumValue
      You can use the enum keyword to specify possible values of a request parameter or a model property.

      For example, the sort parameter in GET /items?sort=[asc|desc] can be described as: 

      
 paths:
   /items:
     get:
       parameters:
         - in: query
           name: sort
           description: Sort order
           schema:
             type: string
             enum: [asc, desc]
      A nullable enum can be defined as follows: 
      
 type: string
 nullable: true  # <---
 enum:
   - asc
   - desc
   - null        # <--- without quotes, i.e. null not "null"
      See Also:

    • defaultValue

      @Nullable public @Nullable Object defaultValue
      Default value.

    • discriminator

      @Nullable public @Nullable Discriminator discriminator
      Discriminator

  • Constructor Details

    • OpenAPISchema

      public OpenAPISchema()