If you have globally defined schemas that directly use
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.
Various API description formats support type combining constructs like
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
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.
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
- $ref: '#/components/schemas/Cat'
- $ref: '#/components/schemas/Dog'
Similarly, schemas using
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
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
anyOf when transforming to OpenAPI
v3, which was not supported before.
Special Considerations for Discriminators Used Alongside
Information of discriminators can only be exported alongside
anyOf in OpenAPI
v3. as other formats do not allow this. For formats where discriminator is allowed but
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
anyOf types then inherit that information by using an equivalent of the
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:
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.
v0.8 supports defining global schemas with unique names using JSON schema syntax. These schemas support
not constructs along with descriptive content and this information is preserved when exporting to other formats.
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