Import and Export Settings

Settings in the APIMatic Metadata file that change how your API definition is read, and how it's written when you transform it.

Import settings change how APIMatic reads your API definition. Export settings change how it's written when you transform it to another format. Both go at the top level of the APIMatic Metadata file. Set only the ones you want to change; the rest keep their defaults.

APIMatic ignores keys it doesn't recognize under ImportSettings, so check the spelling of each setting name. Keys it doesn't recognize under ExportSettings are reported by the Metadata File Validation ruleset.

src/spec/APIMATIC-META.json

{
  "ImportSettings": {
    "PreferSwaggerOperationSummaryOverId": true,
    "ImportMultipleAuthentication": false
  },
  "ExportSettings": {
    "ExportExtensions": true
  }
}

Import settings

All import settings are booleans except ExampleResolvingMaxDepth.

Naming

Setting	Default	What it does
`PreferJsonSchemaNameOverTitle`	`false`	Names models after their definition name instead of their `title`.
`AppendParentNameForClashes`	`false`	When two models have the same name, adds the parent's name instead of a number.
`IgnoreRamlTypeDeclarationDisplayName`	`false`	RAML 1.0: ignores `displayName` and uses the declared key name.
`PreferSwaggerOperationSummaryOverId`	`false`	OpenAPI: names endpoints from `summary` instead of `operationId`.
`IgnoreEndpointSummary`	`false`	OpenAPI 3: doesn't import an operation's `summary` as the endpoint summary. Instead, it's used as the endpoint description when the operation has no description.

Models and schemas

Setting	Default	What it does
`ExampleResolvingMaxDepth`	`1`	Integer. How many levels of nested objects become models when a model is built from a JSON example. For formats whose models come only from examples, such as Postman, HAR, and RAML 1.0, the default `1` is raised to `10`.
`AllowModelTypesWithNoFields`	`false`	Imports models that have no properties.
`ImportArrayOfMapsAndMapOfArrays`	`false`	Imports arrays of maps and maps of arrays with their types, instead of as dynamic types.
`ImportOpenApi3EmptySchema`	`true`	OpenAPI 3: keeps empty schemas. When `false`, they're treated as undeclared.
`ImportCustomTypeAdditionalFields`	`true`	Imports `additionalProperties` defined in schemas that also define properties or use `allOf`, `oneOf`, or `anyOf`.
`ImportUnusedCustomTypes`	`true`	OpenAPI 3: when `false`, removes models that nothing in the API uses.
`RemoveUndeclaredPropertiesFromExample`	not set	Removes example properties that aren't in the schema. Turns on automatically with `RemoveSchemaPropertiesWithTags` or `RemoveInformationWithTags` unless you set it to `false`.

Type combinators

Setting	Default	What it does
`ImportTypeCombinators`	`true`	Imports `oneOf`, `anyOf`, `not`, and union types along with the extra types they need.
`ImportTypeCombinatorsWithOnlyOneType`	`true`	When `false`, a combinator with a single type is replaced by that type.
`ImportAdditionalTypeCombinatorModels`	`true`	When `false`, doesn't create a model for a schema that uses `oneOf` or `anyOf`. The schema is imported as a generic object that holds the combinator's types.
`PromoteInlineTypeCombinatorsToGlobal`	`false`	Turns inline `oneOf`, `anyOf`, and `not` combinators that aren't defined as named schemas into global type combinators with generated names.
`LoadOneOfAsOptionalFields`	`false`	Merges `oneOf` schemas into one model whose fields are all optional.
`UseRamlUnionTypeAsOneOf`	`true`	RAML 1.0: loads union types as `oneOf`. When `false`, loads them as `anyOf`.
`LoadBaseTypesForOneOfAnyOfDiscriminator`	`false`	Creates base types where a discriminator is used with `oneOf` or `anyOf`.
`AppendParentSchemaNameToOneOfAnyOfBaseType`	`false`	Adds the parent schema's name to those generated base types.
`ImportFromOpenApiDiscriminatorMapping`	`true`	OpenAPI 3: imports the discriminator `mapping`.

Enums

Setting	Default	What it does
`IgnoreInlineEnumModelDescription`	`false`	Ignores descriptions defined inline on enum schemas.
`PreserveSingleValueEnum`	`false`	Keeps a single-value enum on a required property as an enum instead of turning it into a constant.
`AllowAdditionalEnumItems`	`false`	Lets enums accept values that aren't listed.

Responses and requests

Setting	Default	What it does
`ImportMultipleResponses`	`true`	When `false`, keeps only responses with status codes 200–208 and 400–599, and drops the types the others need.
`ImportAdditionalErrorModels`	`true`	OpenAPI 3: imports `4XX`, `5XX`, and `default` responses as endpoint errors. When `false`, they're skipped.
`ImportRequestBodyContentTypeHeader`	`true`	Imports the request content type as an explicit `Content-Type` header.
`ImportWsdlWithJsonMediaTypes`	`false`	WSDL: treats `application/xml` media types as JSON and skips XML metadata.
`ImportHeadOptionsTraceOperations`	`false`	OpenAPI 3.x and Swagger 2.0: imports operations under `head`, `options`, and `trace` as endpoints. When `false`, they're skipped with a warning. Other formats never import these methods.

Authentication

Setting	Default	What it does
`ImportMultipleAuthentication`	`true`	When `false`, imports only the first authentication scheme.
`ImportAdditionalHeader`	`true`	OpenAPI 3: adds the header of each API key security scheme to the API's additional headers. When `false`, it isn't added.
`EnableCookieAuthentication`	`false`	OpenAPI 3: imports cookie authentication schemes.
`AllowAuthForEmptySecurityObject`	`false`	OpenAPI 3: when `ImportMultipleAuthentication` is `false`, still applies authentication to an operation whose first security requirement is an empty object (`{}`).

Validation

Setting	Default	What it does
`UseStrictValidation`	`false`	OpenAPI 3.0 and Swagger 2.0: runs the format's own validation and linting during import, and stops the import if they report an error.

Export settings

All export settings are booleans.

All formats

Setting	Default	What it does
`ExportExtensions`	`false`	Exports extensions when the output format supports them.
`ExportAnyType`	`true`	When `false`, exports `any` as `object` or `string`.

OpenAPI and RAML

Setting	Default	What it does
`AddRefSiblingDataInAllOfSchema`	`true`	OpenAPI 2.0 and 3.x: keeps data that sits next to a `$ref` by wrapping it in `allOf`. When `false`, that data is dropped.
`ExportXmlMetaData`	`true`	Exports XML metadata such as node name, namespace, and prefix (OpenAPI 2.0, 3.x, RAML 1.0).
`ExportDiscriminatorMappingValues`	`true`	OpenAPI 3: exports discriminator values in `mapping`.
`ExportGlobalTypeCombinators`	`true`	OpenAPI 3.0 and RAML: defines type combinators once and references them. When `false`, they're written inline.
`UseDateTimeOnlyInRaml`	`false`	RAML 1.0: exports date-time fields as `datetime-only` instead of `datetime`.

Postman and Insomnia

Setting	Default	What it does
`GenerateModelSamples`	`true`	Postman and Insomnia: generates sample values for parameters, requests, and responses. Defaults to `false` when the input is WSDL or WADL.
`SetPostmanParamValuesAsVariables`	`false`	Postman: stores sample query and path parameter values as collection variables.
`EncodeUrlParamsInPostman`	`true`	Postman: URL-encodes request URLs.
`ExportApiKeyAuthInPostman`	`true`	Postman: uses Postman's API key auth type. When `false`, adds the key as a parameter.
`UseEnvironmentNamesForServerVariables`	`false`	Postman: adds environment names to server variable names.
`ExportOptionalParametersAsDisabled`	`false`	Postman and Insomnia: marks optional parameters as disabled.
`GenerateSampleValueFromRegexPattern`	`false`	Postman and Insomnia: generates sample values from regex patterns. Off by default because it's slow.
`ForceAllowModelExampleExportForSampleGeneration`	`false`	Postman and Insomnia: reuses model-level examples for samples.

WSDL and XML

Setting	Default	What it does
`UseHttpMethodPrefixForAutoGeneratedWsdlNames`	`true`	WSDL: prefixes generated names with the HTTP method.
`UseXsdBase64BinaryType`	`false`	XML Schema: exports files and binary data as `xs:base64Binary` instead of `xs:hexBinary`.

GraphQL

Setting	Default	What it does
`UseHttpPrefixInQueryNames`	`true`	Starts each operation name with a verb that matches its HTTP method, such as `Get` or `Delete`, unless the name already starts with one. Defaults to `false` when the input is WSDL.

Import and Export Settings

Import settingsCopy Anchor Link

NamingCopy Anchor Link

Models and schemasCopy Anchor Link

Type combinatorsCopy Anchor Link

EnumsCopy Anchor Link

Responses and requestsCopy Anchor Link

AuthenticationCopy Anchor Link

ValidationCopy Anchor Link

Export settingsCopy Anchor Link

All formatsCopy Anchor Link

OpenAPI and RAMLCopy Anchor Link

Postman and InsomniaCopy Anchor Link

WSDL and XMLCopy Anchor Link

GraphQLCopy Anchor Link

On this page