Skip to main content

Configuring Transformer

You can import/convert your API definition file along with a Metadata file that will allow you to configure various settings for your API when it is imported, and even customize how additional settings can be catered once the file is transformed and exported. You can also configure API Merging for multiple API definition files by specifying the configuration settings.

Import Settings

These settings allow you to configure the import of your API definition through various options e.g. settings that let you override names of components, etc.

Import Settings Object

The available properties and their respective types are as follows:

PreferJsonSchemaNameOverTitleBooleanBy default, this is set to false and if a title is specified in a JSON Schema definition we consider this as the model name. However, when true, we give precedence to the definition name instead of the one specified using property title.
AppendParentNameForClashesBooleanBy default, this is set to false and when loading models/complex types, if there is a clash in names we append a number with the name of the clashing type. When true, the name of the parent component is appended with the name instead.
IgnoreRamlTypeDeclarationDisplayNameBooleanBy default, this is set to false. When true, the displayName property for any RAML v.1.0 Type Declaration Object will be ignored and the key name specified at the time of declaring this object will be preferred instead.
PreferSwaggerOperationSummaryOverIdBooleanBy default, this is set to false. When true, we will give more precedence to Swagger Operation Object's summary instead of operationId during endpoint name extraction
AutoGenerateTestCasesBooleanFor several formats like OpenAPI (v3.x), API Blueprint, RAML, Postman and HAR, we support auto-generating test cases from request/response examples (if any are present). By default, this will be enabled but can be disabled by setting this flag to false.
AllowModelTypesWithNoFieldsBooleanBy default, this is set to false. When true, model definitions containing no properties/fields will also be imported.
ImportMultipleResponsesBooleanBy default, this is set to true. When false, any data related to multiple responses including additional types created for these responses will be removed
LoadOneOfAsOptionalFieldsBooleanBy default, this is set to false. When set to true, oneOf schemas will be combined and imported as a single model with all fields considered as optional.
ImportArrayOfMapsAndMapOfArraysBooleanBy default, this is set to false and schemas containing arrays of maps or maps of arrays will be treated as dynamic types during import. When set to true, however, such schema definitions will be imported and the type set accordingly.
ImportTypeCombinatorsBooleanBy default, this is set to true and type combining constructs like union types, anyOf, oneOf and not will be imported. Any extra types associated with these constructs will also be loaded.
UseRamlUnionTypeAsOneOfBooleanBy default, this is set to true and RAML v1.0 union types are loaded as the equivalent of oneOf type construct. If false, the union types are loaded as an equivalent of the anyOf type construct.
ImportWsdlWithJsonMediaTypesBooleanBy default, this is set to false. When set to true, all application/xml request/response media types will be treated as application/json during WSDL import. XML metadata (including details about XML node name, namespace, prefix etc.) will also not be imported.
ImportFromOpenApiDiscriminatorMappingBooleanBy default, this is set to true. When set to false, information from the mapping property in the OpenAPI v3 Discriminator object is not imported.
ImportRequestBodyContentTypeHeaderBooleanBy default, this is set to true. When set to false, request's content type information will not be imported as explicit Content-Type header.
ImportMultipleAuthenticationBooleanBy default, this is set to true and all authentication schemes available in the API are loaded as is. When set to false, however, only the first authentication scheme from the API will be imported.
ImportOpenApi3EmptySchemaBooleanBy default, this is set to true and the schema declaration will not be ignored. If set to false an empty schema will be treated as if no schema was declared.
LoadBaseTypesForOneOfAnyOfDiscriminatorBooleanBy default, this is set to true and additional base types will be created for cases where discriminator information is present alongside oneOf or anyOf. When set to false, no additional base types will be created and exporting to formats where discriminator is not supported alongside oneOf/anyOf may see loss of information related to it.
ImportTypeCombinatorsWithOnlyOneTypeBooleanBy default, this is set to true and type combinators (e.g. anyOf, oneOf, not) containing only one type definition in their list will be imported as is. When set to false, the type combinators lists will not be populated. Instead, the single type definition will be extracted from the list and considered as the default type of the component.
AppendParentSchemaNameToOneOfAnyOfBaseTypeBooleanBy default, this is set to false and base types auto-generated from cases involving oneOf/anyOf discriminators will have default names. When set to true, the name of the parent schema may be appended with the default name, if applicable. This is recommended for cases where multiple oneOf/anyOf schemas are expected to have the same discriminator property name.


"ImportSettings": {
"PreferJsonSchemaNameOverTitle": true,
"AppendParentNameForClashes": true,
"AllowModelTypesWithNoFields": true

Export Settings

These settings let you configure export to various formats e.g. enabling/disabling extensions when exporting to Swagger.

Export Settings Object

The available properties and their respective types are as follows:

ExportExtensionsBooleanIf true, any extensions, if supported in the selected export format, will be exported to the output file.
GenerateModelSamplesBooleanBy default, when exporting to Postman (v1.0,2.0), parameter/request/response samples will be auto-generated (where needed) except when importing from WSDL or WADL. Sample generation can be enabled/disabled using this flag.
UseDateTimeOnlyInRamlBooleanIf true, then all date-time fields are exported with type datetime-only instead of datetime in RAML v1.0.
SetPostmanParamValuesAsVariablesBooleanIf true, auto-generated sample values for Postman params (query/path) will be stored inside collection variables instead of being directly embedded in the param definitions. The name of the variable will be the param's name. The values stored in the variables can then be adjusted through the Variables section in Postman's Collection editor.
AddRefSiblingDataInAllOfSchemaBooleanAny sibling data added alongside a $ref is ignored. If any data needs to be added, OpenAPI recommends using allOf to wrap both $ref and that additional data. By default, we ignore sibling data when exporting OpenAPI schemas. However, when set to true, $ref and the data will be added to allOf.
EncodeUrlParamsInPostmanBooleanEnable/disable request URL encoding when exporting to Postman. This is set to true by default.
UseXsdBase64BinaryTypeBooleanBy default, the File or Binary types are exported as xs:hexBinary in XML schemas. If true, the types will be exported as xs:base64Binary instead.
ExportXmlMetaDataBooleanBy default, XML metadata (e.g. XML node name, namespace, prefix, etc.) is set for XML entities when exporting to OpenAPI v3.x, v2.0 or RAML v1.0. If false the XML metadata will not be exported.
ExportDiscriminatorMappingValuesBooleanBy default, this is set to true. When set to false, information about discriminator values are not exported to mapping information of the Discriminator object in OpenAPI v3.
ExportAnyTypeBooleanBy default, this is set to true and type any will be exported where applicable. When set to false, type any will be exported as object/string instead.
ExportGlobalTypeCombinatorsBooleanBy default, this is set to true and global type combining constructs e.g. anyOf, oneOf, not or union types will be defined once globally and the referencing schemas will refer them via their unique name/path in applicable formats like OpenAPI v3.0 and RAML. When set to false, the global type combining schemas will be embedded inline in all schemas referencing them.
ExportOptionalParametersAsDisabledBooleanBy default, this is set to false and optional parameters are enabled in exported Insomnia and Postman Collection files. When set to true, request parameters marked as optional will appear disabled in the aforementioned types of files, upon export.
ExportApiKeyAuthInPostmanBooleanBy default, this is set to true and if a request in Postman needs an API key to be sent as a header/query parameter, it is set as its authentication type. When set to false, the API key is instead added as an explicit request parameter. This is especially recommended for cases where a request needs multiple API keys to be sent as part of its authentication, which is a scenario otherwise not supported in Postman authentication types.
GenerateSampleValueFromRegexPatternBooleanBy default, this is set to false due to performance overhead. When set to true and a regex pattern is specified, the sample value will be generated based on the specified regex pattern in case of export to Insomnia or Postman Collection.
UseHttpMethodPrefixForAutoGeneratedWsdlNamesBooleanBy default, this is set to true. When set to false, WSDL export will not add endpoint's HTTP method as a prefix to auto-generated names of related components e.g. names of schema types, operation name, etc.


"ExportSettings": {
"ExportExtensions": true,
"GenerateModelSamples": true

API Merging Settings

You can import multiple API specifications and merge them together to create a unified API Portal and SDK for each language. By default, APIMatic merges APIs using the Take Left merge strategy. When two API definition files are being merged, APIMatic will try to keep elements such as endpoints and schemas from both the APIs. If there is a conflict, the value from the first API will take precedence.


For API merging, place the APIMATIC-META.json metadata file (containing the configuration settings) at the root of a directory, and put each API definition (whether it is a single file or composed of multiple files) into individual sub-directories. This directory, with the metadata and API definition sub-directories, is to be provided as a .zip file during import.

SettingTypePurposeDefault Value
MergeApisBooleanEnables merging of APIs.false
MergeSettingsMerge Settings ObjectSettings to configure the merge process. See Merge Settings object for more detail.-
MergeOrderOfDirectories[String]Relative paths to directories that need to be merged. The order of the API definition files in this list matters, as the MergeSettings configuration will be applied based on this order.-
MergedApiNameStringName of the final merged API.-


"MergeConfiguration": {
"MergeApis": true,
"MergeOrderOfDirectories": ["SpecDirectory1", "SpecDirectory2"],
"MergedApiName": "Merged API",
"MergeSettings": {
"ConflictStrategy": "KeepLeft"

Merge Settings Object

The Merge Settings object allows setting the configuration while merging two APIs.

SettingTypePurposeDefault Value
ConflictStrategyEnum[String]Conflict strategy to use when a conflict arises during merge. Possible values are:
  • KeepLeft
  • KeepRight
  • KeepBoth
  • Merge
  • KeepLeft
    DeepCompareFieldTypesBooleanWhether to compare field level referenced custom types by names only or by actually retrieving and comparing their model type definitions.false
    AppendParentNameInNamingConflictBooleanAppend parent name to entity when there is a conflict between names instead of appending a number at the end.false
    SkipCodeGenValidationBooleanConfigures validation of individual APIs and the merged API.false
    NumberStartIndexForNameConflictNumberWhen resolving conflicts in names of components (e.g. endpoints), a number is appended at the end of the conflicting name to make it unique. This setting controls the starting value of this number.1
    MergeMultipleAuthenticationBooleanAllow more than one authentication schemes present in the individual APIs, or the APIs being combined, to be merged together.true

    Authentication Settings

    The details on the authentication options available in APIMatic are described here API Authentication. To enable these options via the metafile, you need to specify the authentication object that has the following properties:

    Authentication Object

    Name: Authentication

    TypeStringMUST be a value from one of [None,Basic, OAuth_v2_BearerToken, CustomQuery,CustomHeader, OAuth_v1_TokenSecret, CustomAuth, JWT, OAuth_v1_Cert_PKCS12_RSA, OAuth_v1a_OneLeggedFlow]
    Parameters[Parameter Object]Array of type Parameter Object


    "Authentication": {
    "Type": "Basic",
    "Parameters": [
    "Name": "username",
    "Description": "your username"
    "Name": "key",
    "Description": "your api key"

    Parameter Object

    NameStringName of the authentication parameter
    DescriptionStringDetails of the authentication parameter
    DefaultValueStringAny default value for the authentication parameter


    "Name": "apikey",
    "Description": "An API key is required for authentication"