Import and Export Settings

The APIMatic Metadata file carries two sets of configuration settings that control how an API definition is read in and written back out:

Import settings control how your API specification document is interpreted when APIMatic reads it, for example, whether schema keys are preferred over schema titles during OpenAPI import.
Export settings control how your API definition is written when APIMatic converts it into another specification format, for example, whether vendor extensions are included in the output.

Both sets of settings apply wherever APIMatic reads or writes an API definition, including the API Transformer, the APIMatic CLI, and the APIMatic extension for VS Code.

Import Settings

The import configuration settings can be placed in an Import Settings Object in the root object of the Metadata file using the ImportSettings property as shown below:

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

Import Settings Object

The available properties and their respective types are as follows:

Setting	Type	Purpose
ExampleResolvingMaxDepth	Integer	Default: `1`. The maximum depth for importing models from nested schemas present within examples. If you are facing performance issues, consider setting this to a lower value.
PreferJsonSchemaNameOverTitle	Boolean	Default: `false`. If a `title` is specified in a JSON Schema definition we consider that as the model name. However, when this flag is set as `true`, we give precedence to the definition name instead of the one specified using property `title`.
AppendParentNameForClashes	Boolean	Default: `false`. When loading models/complex types, if there is a clash in names we append a number with the name of the clashing type. When this flag is set as `true`, the name of the parent component is appended with the name instead.
IgnoreRamlTypeDeclarationDisplayName	Boolean	Default: `false`. When set to `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.
PreferSwaggerOperationSummaryOverId	Boolean	Default: `false`. When set to `true`, we will give more precedence to OpenAPI/Swagger Operation Object's `summary` instead of `operationId` during endpoint name extraction.
AutoGenerateTestCases	Boolean	Default: `true`. For 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). This can be disabled by setting this flag to `false`.
AllowModelTypesWithNoFields	Boolean	Default: `false`. When set to `true`, model definitions containing no properties/fields will also be imported.
IgnoreInlineEnumModelDescription	Boolean	Default: `false`. When set to `true`, ignores any `description` defined inline for an enum schema.
ImportMultipleResponses	Boolean	Default: `true`. When set to `false`, any data related to multiple responses including additional types created for these responses will be removed.
LoadOneOfAsOptionalFields	Boolean	Default: `false`. When set to `true`, `oneOf` schemas will be combined and imported as a single model with all fields considered as optional.
ImportArrayOfMapsAndMapOfArrays	Boolean	Default: `false`. Schemas containing arrays of maps or maps of arrays will be treated as dynamic types during import, by default. When this flag is set to `true`, however, such schema definitions will be imported and the type set accordingly.
ImportTypeCombinators	Boolean	Default: `true`. Type combining constructs like union types, `anyOf`, `oneOf` and `not` will be imported by default. Any extra types associated with these constructs will also be loaded. To disable this, set the flag value to `false`.
UseRamlUnionTypeAsOneOf	Boolean	Default: `true`. RAML `v1.0` union types are loaded as the equivalent of `oneOf` type construct by default. When set to `false`, the union types are loaded as an equivalent of the `anyOf` type construct.
ImportWsdlWithJsonMediaTypes	Boolean	Default: `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.
EnableCookieAuthentication	Boolean	Default: `false`. When set to `true`, allows the import of `cookie` authentication schemes.
AllowAuthForEmptySecurityObject	Boolean	Default: `false`. When set to `true`, allows authentication to be enabled even when the operation level `security` object is empty.
ImportFromOpenApiDiscriminatorMapping	Boolean	Default: `true`. When set to `false`, information from the `mapping` property in the OpenAPI v3 Discriminator object isn't imported.
ImportRequestBodyContentTypeHeader	Boolean	Default: `true`. When set to `false`, request's content type information won't be imported as explicit Content-Type header.
ImportMultipleAuthentication	Boolean	Default: `true`. All authentication schemes available in the API are loaded as is, by default. When set to `false`, however, only the first authentication scheme from the API will be imported.
ImportOpenApi3EmptySchema	Boolean	Default: `true`. Empty schema declarations won't be ignored by default. If set to `false` an empty schema will be treated as if no schema was declared.
LoadBaseTypesForOneOfAnyOfDiscriminator	Boolean	Default: `false`. By default, no additional base types will be created and exporting to formats where discriminator isn't supported alongside `oneOf`/`anyOf` may see loss of information related to it. When set to `true`, additional base types will be created for cases where discriminator information is present alongside `oneOf` or `anyOf`.
ImportTypeCombinatorsWithOnlyOneType	Boolean	Default: `true`. By default, type combinators (for example, anyOf, oneOf, not) containing only one type definition in their list will be imported as is. When set to `false`, the type combinators lists won't be populated. Instead, the single type definition will be extracted from the list and considered as the default type of the component.
AppendParentSchemaNameToOneOfAnyOfBaseType	Boolean	Default: `false`. 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.
IgnoreEndpointSummary	Boolean	Default: `false`. By default, an endpoint's summary won't be assigned to the endpoint's description if it's missing. When set to `true`, the summary is set as the endpoint's description in the scenario where the description hasn't been explicitly defined.
PreserveSingleValueEnum	Boolean	Default: `false`. By default, an enum containing only a single value will be converted to a constant for OpenAPI 3.0. When set to `true`, the enum isn't converted to a constant and remains an enum.
UseStrictValidation	Boolean	Default: `false`. The default validation is flexible and may disregard some issues in the spec to make it easier for users to import their specs. When set to `true`, all mandatory/recommended validation and lint checks will be enforced.
ImportAdditionalHeader	Boolean	Default: `true`. By default, an additional header is imported when multiple authentication schemes have been defined. When set to `false`, this additional header isn't imported.
ImportAdditionalErrorModels	Boolean	Default: `true`. When set to `false`, any additional error models generated for multiple error responses upon import are removed.
ImportAdditionalCustomTypeAdditionalFields	Boolean	Default: `true`. When set to `false`, `additionalProperties` defined within a schema aren't imported.
AllowAdditionalEnumItems	Boolean	Default: `false`. When set to `true`, allows all enumeration schemas to accept any unknown properties defined.
ImportAdditionalTypeCombinatorModels	Boolean	Default: `true`. When set to `false`, prevents importing additional unused models associated with type combinators.
RemoveUndeclaredPropertiesFromExample	Boolean	Default: `null`. Removes properties from examples that don't exist in schema definitions. When using `RemoveSchemaPropertiesWithTags`, example cleanup happens automatically unless explicitly set to `false`. Setting to `false` prevents example cleanup even during property filtering processes. Can be used standalone by setting to `true` to clean up all examples in the spec without any filtering.

Export Settings

You can configure how your input API definition is exported by providing export-specific configuration settings in the APIMatic Metadata file. Note that the Metadata file is always supplied alongside the input API specification document, so export settings are declared at the same time as import settings and take effect when the API definition is later written out.

The export configuration settings can be placed in an Export Settings Object in the root object of the Metadata file using the ExportSettings property as shown below:

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

Export Settings Object

The available properties and their respective types are as follows:

Setting	Type	Purpose
ExportExtensions	Boolean	Default: `false`. If `true`, any extensions, if supported in the selected export format, will be exported to the output file.
GenerateModelSamples	Boolean	Default: `true`. By 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.
UseDateTimeOnlyInRaml	Boolean	Default: `false`. If `true`, then all date-time fields are exported with type `datetime-only` instead of `datetime` in RAML `v1.0`.
SetPostmanParamValuesAsVariables	Boolean	Default: `false`. If `true`, auto-generated sample values for Postman parameters (query/path) will be stored inside collection variables instead of being directly embedded in the parameter definitions. The name of the variable will be the parameter's name. The values stored in the variables can then be adjusted through the `Variables` section in Postman's Collection editor.
AddRefSiblingDataInAllOfSchema	Boolean	Default: `true`. Any sibling data linked to a schema definition that also uses $ref will be exported by placing the reference and sibling data in the `allOf` construct. If set to `false`, the sibling data will be ignored.
EncodeUrlParamsInPostman	Boolean	Default: `true`. Enable/disable request URL encoding when exporting to Postman.
UseXsdBase64BinaryType	Boolean	Default: `false`. By 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.
ExportXmlMetaData	Boolean	Default: `true`. By default, XML metadata (For example, 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 won't be exported.
ExportDiscriminatorMappingValues	Boolean	Default: `true`. When set to `false`, information about discriminator values aren't exported to `mapping` information of the Discriminator object in OpenAPI v3.
ExportAnyType	Boolean	Default: `true`. By default, type `any` will be exported where applicable. When set to `false`, type `any` will be exported as `object`/`string` instead.
ExportGlobalTypeCombinators	Boolean	Default: `true`. By default, global type combining constructs, for example, `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.
ExportOptionalParametersAsDisabled	Boolean	Default: `false`. By default, 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.
ExportApiKeyAuthInPostman	Boolean	Default: `true`. By default, if a request in Postman needs an API key to be sent as a header/query parameter, it's 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.
GenerateSampleValueFromRegexPattern	Boolean	Default: `false`. By default, this is disabled 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.
ForceAllowModelExampleExportForSampleGeneration	Boolean	Default: `false`. By default, sample auto generation in Postman and Insomnia export don't reuse any examples specified at model level for risk of exporting examples that may contain read-only or write-only properties where they may not be allowed. This setting should be set to `true` if you don't believe that a risk of read-only or write-only fields exist and so any examples specified at model level shouldn't be ignored.
UseHttpMethodPrefixForAutoGeneratedWsdlNames	Boolean	Default: `true`. When set to `false`, WSDL export won't add endpoint's HTTP method as a prefix to auto-generated names of related components, for example, names of schema types, operation name, etc.
UseEnvironmentNamesForServerVariables	Boolean	Default: `false`. When set to `true`, environment names will be appended to server variable names in the generated Postman Collection to avoid duplication and improve clarity. Additionally, if each environment contains only a single server, the variable name will be replaced entirely with the environment name.

Import Settings​

Import Settings Object​

Export Settings​

Export Settings Object​

Import Settings

Import Settings Object

Export Settings

Export Settings Object