Working With Composite Schemas In Integration Server Using OpenAPI

Knowledge base
, , ,
1

Concepts

A composite schema combines multiple schemas. The OpenAPI 3.0 specification provides keywords derived from the JSON Schema validation library to combine multiple schemas. For more information, see the JSON Schema specification. You can use the following keywords to create a composite schema or validate a value against multiple criteria.

  • oneOf: Validates a value against exactly one of the schemas.
  • allOf: Validates a value against all the schemas.
  • anyOf: Validates a value against any (one or more) of the schemas.
  • not: Ensures that the value is not valid against a specified schema.

Use cases

Actors

  • An integration developer who creates the provider RAD.
  • An Integration Server which is an endpoint for REST requests.
  • A REST client that sends the REST API request.

Use case #1 How to validate data against a schema using the ‘oneOf’ keyword?

Description

In an OpenAPI document, the ‘oneOf’ keyword validates data against one of the specified schemas.
For example, consider the following snippet of an OpenAPI document.

oneOf:
    - $ref: '#/components/schemas/mySchema1'
    - $ref: '#/components/schemas/mySchema2'

This use case starts when you have an OpenAPI document containing multiple schemas, and you need to validate a value against any one of the schemas. It ends when you have successfully validated the value against one of the schemas.

Basic flow

  1. Start Software AG Designer.
  2. Create a provider REST API Descriptor (RAD) using the attached OpenAPI document (oneOf.yml) that contains the ‘oneOf’ keyword.
    oneOf.zip (721 Bytes)

For more information on creating a RAD using an OpenAPI document, see Integration Server as a Contract-First REST API Provider using OpenAPI.
Integration Server generates the following assets containing the JSON document types (mySchema1 and mySchema2).

oneof3

  1. Open the flow service under services and go to the Input/Output tab. The service signature of the flow service displays the schemas (‘mySchema1’ and ‘mySchema2’) in the request body.

oneof1
oneof11034×453 12.5 KB

  1. Select the document under ‘requestBody’ and click the browse button under Properties > JSON Schema > Validations.
    The Validations dialog box opens, which displays the JSON Schema properties under Core Properties.

oneof2
oneof2684×608 8.2 KB

  1. Select Validate input in the Input/Output tab to validate the input against the specified schemas using the ‘oneOf’ keyword.

  2. Send a REST API request with a request body. For example, consider the following REST request followed by a request body,
    POST http://:/rad/composite_schema:oneOf/oneOfOperation
    a.

{
     “name”:”John”,
     “address”:”Bangalore, India”
 }

In this case, Integration Server finds a match for the request body against 'mySchema1’.
b.

{
      “name”:”John”
      “phone”:”111-222-3334”
 }

In this case, Integration Server finds a match for the request body against ‘mySchema2’.

Note:
Ensure that the request body matches with one of the schemas in the service. If the request body contains any variations, the validation fails.

  • On success: Integration Server returns 200: <operation_status> as response back to the client.
  • On failure: Integration Server returns 400 Invalid Input as a response to the REST request.

Use case #2 How to validate data against a schema using the ‘allOf’ keyword?

Description

Consider this use case when you have multiple schemas sharing common properties in your OpenAPI document, and you want to define these common properties for different schemas in the same document. Instead of defining these properties separately for each schema, you can use the ‘allOf’ keyword to reuse the properties of another schema. Data provided by a client is valid against ‘allOf’ when data is valid against all the given schemas.
In the following example, ‘allOf’ acts as a tool to combine multiple schemas.

allOf:
    - $ref: '#/components/schemas/mySchema1'
    - $ref: '#/components/schemas/mySchema2'

This use case starts when you have an OpenAPI document containing multiple schemas and you need to combine properties of one schema to another. It ends when you have successfully handled a schema inheriting properties from another schema.

Basic flow

  1. Start Software AG Designer.
  2. Create a provider REST API Descriptor (RAD) using the attached OpenAPI document (allOf.yml) that contains the ‘allOf’ keyword.
    allOf.zip (740 Bytes)

For more information on creating a RAD using an OpenAPI document, see Integration Server as a Contract-First REST API Provider using OpenAPI.
Integration Server generates the following assets containing the JSON document types (mySchema1 and mySchema2).

allof1

  1. Open the flow service under services and go to the Input/Output tab. The service signature of the flow service displays the schemas (‘mySchema1’ and ‘mySchema2’) in the request body.

allof2
allof21049×452 12.8 KB

  1. Select the document under ‘requestBody’ and click the browse button under Properties > JSON Schema > Validations.
    The Validations dialog box opens, which displays the JSON Schema properties under Core Properties.

allof3
allof3684×608 8.17 KB

  1. Select Validate input in the Input/Output tab to validate the input against the specified schemas using the ‘allOf’ keyword.

  2. Send a REST API request with a request body. For example, consider the following REST request followed by a request body,
    POST http://:/rad/composite_schema:anyOf/allOfOperation

{
    "name":"John",
    "address":"Bangalore, India",
    "city":"Bangalore",
    "phone":"111 222 3333"
}

Note:
Ensure that the request body matches with the fields in both the schemas in the service. If the request body contains any variations, the validation fails.

  • On success: Integration Server returns 200: <operation_status> as response back to the client.
  • On failure: Integration Server returns 400 Invalid Input as a response to the REST request.

Use case #3 How to validate data against a schema using the ‘anyOf’ keyword?

Description

Consider this use case when you need to validate a value against one or more schemas in an OpenAPI document.

anyOf:
     - $ref: '#/components/schemas/mySchema1'
     - $ref: '#/components/schemas/mySchema2'

This use case starts when you have an OpenAPI document containing multiple schemas and you need to validate a value against one or more schemas. It ends when you have successfully validated the value against any one of the schemas.

Basic flow

  1. Start Software AG Designer.
  2. Create a provider REST API Descriptor (RAD) using the attached OpenAPI document (anyOf.yml) that contains the ‘anyOf’ keyword.
    anyOf.zip (731 Bytes)

For more information on creating a RAD using an OpenAPI document, see Integration Server as a Contract-First REST API Provider using OpenAPI.
Integration Server generates the following assets containing the JSON document types (mySchema1 and mySchema2).

anyof1

  1. Open the flow service under services and go to the Input/Output tab. The service signature of the flow service displays the schemas (‘mySchema1’ and ‘mySchema2’) in the request body.

anyof2
anyof21032×454 11.9 KB

  1. Select the document under ‘requestBody’ and click the browse button under Properties > JSON Schema > Validations.
    The Validations dialog box opens, which displays the JSON Schema properties under Core Properties.

anyof3
anyof3684×608 8.23 KB

  1. Select Validate input in the Input/Output tab to validate the input against the specified schemas using the ‘anyOf’ keyword.

  2. Send a REST API request with a request body. For example, consider the following REST request followed by a request body,
    POST http://:/rad/composite_schema:anyOf/anyOfOperation
    a.

{
     “name”:”1234” //as string
}

In this case, Integration Server finds a match for the request body against 'mySchema1’.
b.

{
      “phone”:1234 //as int32
}

In this case, Integration Server finds a match for the request body against ‘mySchema2’.

Note:
Ensure that the request body matches with the fields in either of the schemas as string or integer type. If the request body contains any variations, the validation fails.

  • On success: Integration Server returns 200: <operation_status> as response back to the client.
  • On failure: Integration Server returns 400 Invalid Input as response to the REST request.

Use case #4 How to validate data against a schema using the ‘not’ keyword?

Description

Consider this use case when you need to validate a value, which is invalid against a specified schema in an OpenAPI document. This keyword helps you to make your schema more specific.

/notOperation:
    post:
      summary: Finds Pets by status
      description: Multiple status values can be provided with comma separated strings
      operationId: findPetsByStatus
      requestBody:
        description: Update an existent user in the store
        content:
          application/json:
            schema:
                $ref: '#/components/schemas/mySchema1'

This use case starts when you have an OpenAPI document containing one or more schemas and you need to validate a value, which is invalid against a specified schema. It ends when you have successfully validated the invalid value against the specified schema.

Basic flow

  1. Start Software AG Designer.
  2. Create a provider REST API Descriptor (RAD) using the attached OpenAPI document (not.yml) that contains the ‘not’ keyword.
    not.zip (696 Bytes)

For more information on creating a RAD using an OpenAPI document, see Integration Server as a Contract-First REST API Provider using OpenAPI.
Integration Server generates the following assets containing the JSON document type (mySchema1).

not1

  1. Open the flow service under services and go to the Input/Output tab. The service signature of the flow service displays the schema (‘mySchema1’) in the request body.

not2
not2931×512 9.27 KB

  1. Select the document under ‘requestBody’ and click the browse button under Properties > JSON Schema > Validations.
    The Validations dialog box opens, which displays the JSON Schema properties under Core Properties.

not3
not3702×359 34.5 KB

  1. Select Validate input in the Input/Output tab to validate the input against the specified schema using the ‘not’ keyword.

  2. Send a REST API request with a request body. For example, consider the following REST request followed by a request body,
    POST http://:/rad/composite_schema:anyOf/notOperation
    a.

{
     “name”:”John” //as string
}

In this case, Integration Server finds a match for the request body against 'mySchema1’.

b.

{
 “name”:
 {
“firstName”:”John”,
“secondName”:”Michael”
 }
}

In this case, Integration Server finds a match for the request body against ‘mySchema2’.

Note:
Ensure that the request body is not sent as an integer type; otherwise the validation fails.

  • On success: Integration Server returns 200: <operation_status> as response back to the client.
  • On failure: Integration Server returns 400 Invalid Input as response to the REST request.

References

2 Likes