Skip to main content

Added Support for Export of Reusable "oneOf", "anyOf", "not" Constructs and Union Types in API Transformer

· 4 min read

If you have globally defined schemas that directly use oneOf, anyOf, not constructs or union types, you will be pleased to know that API Transformer now converts between formats by preserving the global structure of such schemas.

Details​

Various API description formats support type combining constructs like anyOf, oneOf and not. Others like RAML support "union" types which are a kind of an equivalent of one of these constructs. Depending on the API description format, It is quite possible to define these constructs once globally with a unique name and then reference them repeatedly across the API description file without needing to redefine them at each step. We have now improved support for such schemas for our API Transformer.

What Has Changed?​

Until now, during transformation, we embedded the information of globally defined schemas inline within all schemas that referenced them. Due to this, repetition of information was observed in the exported API description files. However, we now support exporting reusable or globally defined schemas (containing oneOf, anyOf, not constructs or union types) with user-defined names, and other related information. Referencing schemas then reference these global definitions, which reduces duplication of information. A detailed breakdown of changes introduced in our support for each format is given below.

OpenAPI v3​

A schema in OpenAPI v3 can be defined globally under #/components/schemas with a unique name. See an example below of a global schema containing oneOf information and named Pet:

Pet:
  oneOf:
  - $ref: '#/components/schemas/Cat'
  - $ref: '#/components/schemas/Dog'
  discriminator:
    propertyName: pet_type
    mapping:
      cat: Cat
      dog: Dog

Similarly, schemas using anyOf or not constructs can also be globally defined. A user can provide additional information in these schemas including descriptive content, examples or discriminator details. Such schemas can then be referenced by other schemas using the $ref notation.

We now support preserving all of the above information in its true form when exporting to other formats. This includes exporting discriminator related information alongside oneOf/anyOf when transforming to OpenAPI v3, which was not supported before.

Special Considerations for Discriminators Used Alongside OneOf/AnyOf​

Information of discriminators can only be exported alongside oneOf/anyOf in OpenAPI v3. as other formats do not allow this. For formats where discriminator is allowed but oneOf/anyOf is not supported (e.g. Swagger v2.0) or where discriminator is not allowed to be used alongside union types (e.g. RAML v1.0), the information by default is imported and exported by creation of additional base types that contain the discriminator information and the oneOf/anyOf types then inherit that information by using an equivalent of the allOf construct.

If, however, you are looking to import an OpenAPI v3 file, make a few changes, then export back to OpenAPI v3, we recommend that you disable the behavior described above by importing your OpenAPI v3 file along with a metadata file where the import setting LoadBaseTypesForOneOfAnyOfDiscriminator is disabled. See an example below:

{
    "ImportSettings": {
        "LoadBaseTypesForOneOfAnyOfDiscriminator": false
    }
}

RAML (v0.8, v1.0)​

RAML v1.0 allows defining global schemas under the types section. These schemas can define union types with a unique name, descriptive content and examples. They can then be referenced by other schemas using the type keyword. We now preserve this information when exporting to other formats.

RAML v0.8 supports defining global schemas with unique names using JSON schema syntax. These schemas support oneOf/anyOf/not constructs along with descriptive content and this information is preserved when exporting to other formats.

XML Schema​

XML schema supports union types xsd:union that can be globally defined with a unique name along with descriptive content. When importing WSDL/WADL files containing XML schemas, such information is now preserved when exporting to other formats.

How to Avoid Changes in Output?​

If you want to avoid any kind of changes to output that are discussed in the previous section, you will need to upload a metadata file along with your API description file with the export setting ExportGlobalTypeCombinators set to false.

Example:

{
    "ExportSettings": {
        "ExportGlobalTypeCombinators": false
    }
}