Working With Composite Schemas In Integration Server Using OpenAPI
Tags: openapi, integration, schema, json
Published: 2021-08-04 12:44:03

---
title: Working With Composite Schemas In Integration Server Using OpenAPI
published: true
date: 2021-07-21 17:35:03 UTC
tags: #openapi, #integration, #schema, #json
canonical_url: https://tech.forums.softwareag.com/t/working-with-composite-schemas-in-integration-server-using-openapi/243040
---

## 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](https://json-schema.org/specification.html). 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](/uploads/short-url/AtsmoYmrcBpg3DZzVldMsEkgV7W.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](https://tech.forums.softwareag.com/t/integration-server-as-a-contract-first-rest-api-provider-using-openapi/241097).  
Integration Server generates the following assets containing the JSON document types (mySchema1 and mySchema2).
![oneof3](https://aws1.discourse-cdn.com/techcommunity/original/3X/3/b/3b7cb84ce2890532428c752cbb7ebfb159004a17.png)
3. 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](https://aws1.discourse-cdn.com/techcommunity/original/3X/3/2/329de9aea7116f4cb72ec6ff44281b87f7134247.png)
4. 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](https://aws1.discourse-cdn.com/techcommunity/original/3X/0/6/06aa2a4a8d3b5d29c9ce9c8ec5c60c80bca72050.png)
5. Select **Validate input** in the **Input/Output** tab to validate the input against the specified schemas using the ‘oneOf’ keyword.
6. 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](/uploads/short-url/lfrmPyT0qk0kNorYOTGOnsXAw9a.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](https://tech.forums.softwareag.com/t/integration-server-as-a-contract-first-rest-api-provider-using-openapi/241097).  
Integration Server generates the following assets containing the JSON document types (mySchema1 and mySchema2).
![allof1](https://aws1.discourse-cdn.com/techcommunity/original/3X/a/6/a6c10c6464d0484aa26678b40e079a4937e1abd2.png)
3. 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](https://aws1.discourse-cdn.com/techcommunity/original/3X/e/4/e43ce8b319ecc9233d588d87f7ff4e61d5920889.png)
4. 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](https://aws1.discourse-cdn.com/techcommunity/original/3X/e/7/e7fe6c8db99957caa2396928458edb2a431a56b9.png)
5. Select **Validate input** in the **Input/Output** tab to validate the input against the specified schemas using the ‘allOf’ keyword.
6. 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](/uploads/short-url/xK3p7R4wlzhvaSUz0Tz3omvF7bn.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](https://tech.forums.softwareag.com/t/integration-server-as-a-contract-first-rest-api-provider-using-openapi/241097).  
Integration Server generates the following assets containing the JSON document types (mySchema1 and mySchema2).
![anyof1](https://aws1.discourse-cdn.com/techcommunity/original/3X/9/e/9ec6b85579a2f8418434ec0e311e50945a590b67.png)
3. 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](https://aws1.discourse-cdn.com/techcommunity/original/3X/0/e/0e37d54f3d8b9de42e6193cbd3092c6c94a2fb15.png)
4. 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](https://aws1.discourse-cdn.com/techcommunity/original/3X/3/b/3b7d92ddf057061fc213b02604fe3658183bc8c8.png)
5. Select **Validate input** in the **Input/Output** tab to validate the input against the specified schemas using the ‘anyOf’ keyword.
6. 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](/uploads/short-url/tkihljXK5fKQbUNvjyRtPwoqOkx.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](https://tech.forums.softwareag.com/t/integration-server-as-a-contract-first-rest-api-provider-using-openapi/241097).  
Integration Server generates the following assets containing the JSON document type (mySchema1).
![not1](https://aws1.discourse-cdn.com/techcommunity/original/3X/d/b/dbe8436ff3c1e67a244495bedda438218d55ba1f.png)
3. 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](https://aws1.discourse-cdn.com/techcommunity/original/3X/7/2/72b239ed451ede51231669cb5531348e367929cf.png)
4. 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](https://aws1.discourse-cdn.com/techcommunity/optimized/3X/5/c/5cf058225c357a2a28be6b3a0e3d0701eced19e7_2_690x352.png)
5. Select **Validate input** in the **Input/Output** tab to validate the input against the specified schema using the ‘not’ keyword.
6. 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

- [OpenAPI Specification - Version 3.0.2 | Swagger](https://swagger.io/specification/)
- [REST Capabilities In Integration Server - Knowledge base - Software AG Tech Community & Forums](https://tech.forums.softwareag.com/t/rest-capabilities-in-integration-server/237435)
- [Service Development Help | 10.7 | About JSON Document Types](https://documentation.softwareag.com/webmethods/microservices_container/msc10-7/10-7_MSC_PIE_webhelp/index.html#page/integration-server-integrated-webhelp%2Frad_edit_15.html%23)

* * *

[Read full topic](https://tech.forums.softwareag.com/t/working-with-composite-schemas-in-integration-server-using-openapi/243040)