# Specification extensions

Source: https://apigenie.pl/docs/reference/cli/extensions
See also: [Configuration](https://apigenie.pl/docs/reference/cli/configuration.md), [Formats](https://apigenie.pl/docs/reference/cli/formats.md), [faker](https://apigenie.pl/docs/reference/cli/faker.md), [Compatibility](https://apigenie.pl/docs/reference/cli/compatibility.md), [apigenie-mcp](https://apigenie.pl/docs/reference/cli/mcp.md).

OpenAPI, Swagger 2.0 and AsyncAPI documents keep what the specification has no field for in `x-`
fields, the specification extensions. This page lists the extensions API Genie reads: its own, under
`x-apigenie`, and those of other tools that its generators, linters, differ and mock server
understand. Each entry says where the extension goes, the value it takes and which tools read it;
the page of each tool holds the details.

An extension that is not listed here is kept as it is, and read by no tool:

- [`apigenie format`](/docs/reference/cli/format) keeps it. An order of properties never lists
  extensions, so they follow the listed fields, and the `extension` order applies inside their
  values ([Property order](/docs/reference/cli/format/property-order#objects)).
- [`apigenie diff`](/docs/reference/cli/diff) reports an extension added, removed or changed, and
  rates the change with the `extensions` map of the node type's rules, `*` for the names not
  listed, or with `defaults.extensions`.
- [`apigenie convert`](/docs/reference/cli/convert) copies extensions from a Swagger 2.0 document
  to the OpenAPI document it writes.
- The documentation components show none of these. The Redoc extensions (`x-tagGroups`,
  `x-displayName`, `x-logo`, `x-codeSamples`) are not read.

The extensions a generator reads can live in an overlay of that generator instead of in the
document, passed with `--overlay` ([Overlays](/docs/reference/generator#overlays)).

## API Genie's own

| Extension | Where it goes, its value, and the tools that read it |
| --------- | ---------------------------------------------------- |
| `x-apigenie.codegen.name` | **Where:** A component schema; in AsyncAPI also a channel, a message or an operation.<br>**Value:** The name of the generated type, class, module or schema; on a channel or a message, the base of its names; on an operation, the name of its function.<br>**Read by:** The generators: client [elixir](/docs/reference/generator/client-elixir), [fetch](/docs/reference/generator/client-fetch), [go](/docs/reference/generator/client-go), [go (AsyncAPI)](/docs/reference/generator/client-go-asyncapi), [java (AsyncAPI)](/docs/reference/generator/client-java-asyncapi), [kafkajs](/docs/reference/generator/client-kafkajs), [python](/docs/reference/generator/client-python), [python (AsyncAPI)](/docs/reference/generator/client-python-asyncapi), [rust](/docs/reference/generator/client-rust), [swift](/docs/reference/generator/client-swift), [ws](/docs/reference/generator/client-ws); server [axum](/docs/reference/generator/server-axum), [express](/docs/reference/generator/server-express), [faststream](/docs/reference/generator/server-faststream), [go](/docs/reference/generator/server-go), [go (AsyncAPI)](/docs/reference/generator/server-go-asyncapi), [hummingbird](/docs/reference/generator/server-hummingbird), [kafkajs](/docs/reference/generator/server-kafkajs), [orpc](/docs/reference/generator/server-orpc), [phoenix](/docs/reference/generator/server-phoenix), [spring (AsyncAPI)](/docs/reference/generator/server-spring-asyncapi), [vapor](/docs/reference/generator/server-vapor), [ws](/docs/reference/generator/server-ws); [schema zod](/docs/reference/generator/schema-zod) |
| `x-apigenie.codegen.controller-name` | **Where:** An operation or its path item.<br>**Value:** The class, module, resource or interface the operation goes into, instead of its tag or path.<br>**Read by:** client [csharp](/docs/reference/generator/client-csharp), [java](/docs/reference/generator/client-java), [python](/docs/reference/generator/client-python) (since 0.12.0); server [aspnet](/docs/reference/generator/server-aspnet), [express](/docs/reference/generator/server-express), [fastapi](/docs/reference/generator/server-fastapi), [spring](/docs/reference/generator/server-spring) |
| `x-apigenie.codegen.action-name` | **Where:** An operation.<br>**Value:** The name of the method, function, handler or procedure, or of a webhook sender, instead of the `operationId`.<br>**Read by:** client [csharp](/docs/reference/generator/client-csharp), [elixir](/docs/reference/generator/client-elixir), [fetch](/docs/reference/generator/client-fetch), [go](/docs/reference/generator/client-go), [java](/docs/reference/generator/client-java), [python](/docs/reference/generator/client-python), [rust](/docs/reference/generator/client-rust), [swift](/docs/reference/generator/client-swift); server [aspnet](/docs/reference/generator/server-aspnet), [axum](/docs/reference/generator/server-axum), [express](/docs/reference/generator/server-express), [fastapi](/docs/reference/generator/server-fastapi), [go](/docs/reference/generator/server-go), [hummingbird](/docs/reference/generator/server-hummingbird), [orpc](/docs/reference/generator/server-orpc), [phoenix](/docs/reference/generator/server-phoenix), [spring](/docs/reference/generator/server-spring), [vapor](/docs/reference/generator/server-vapor) |
| `x-apigenie.codegen.disabled` | **Where:** An operation or its path item; in AsyncAPI a channel or an operation.<br>**Value:** `true` leaves it out of the generated code.<br>**Read by:** The generators of clients and servers from OpenAPI and AsyncAPI documents, except client [elixir (AsyncAPI)](/docs/reference/generator/client-elixir-asyncapi), and server [orpc](/docs/reference/generator/server-orpc) and [phoenix (AsyncAPI)](/docs/reference/generator/server-phoenix-asyncapi) |
| `x-apigenie-lint-disable`, alias `x-lint-disable` | **Where:** Any object, the root included.<br>**Value:** A list of rule ids, disabled for the object and everything nested in it.<br>**Read by:** [`apigenie lint`](/docs/reference/cli/lint#disabling-rules-in-a-document) of OpenAPI, Swagger 2.0 and AsyncAPI documents |
| `x-apigenie-mock` | **Where:** An OpenAPI operation or its path item.<br>**Value:** `status`, `example`, `dynamic`, `body`, `body_file`, `headers`, `latency`, `jitter`, `drop`, `bandwidth`, `delay`, `probability`, `validate_request`, `scenarios`, `resource`.<br>**Read by:** [`apigenie-server`](/docs/reference/server/scenarios); `resource` makes a [CRUD resource](/docs/reference/server/store#crud-resources) |
| `x-apigenie-mock` | **Where:** An OpenAPI response.<br>**Value:** `delay`, `latency`, `jitter`, `headers`.<br>**Read by:** [`apigenie-server`](/docs/reference/server/scenarios) |
| `x-apigenie-mock` | **Where:** An AsyncAPI `send` operation.<br>**Value:** `interval` (milliseconds), `count`, `jitter`, `messages`, `publish: false`.<br>**Read by:** [`apigenie-server`](/docs/reference/server/asyncapi) |
| `x-apigenie-mock-faker`, alias `x-faker` | **Where:** A schema.<br>**Value:** A [faker provider](/docs/reference/cli/faker): a name, `{name: [arguments]}`, or `{provider, args, options}`; `x-apigenie-mock-faker` wins over `x-faker`.<br>**Read by:** [`apigenie-server`](/docs/reference/server/scenarios), [data](/docs/reference/generator/data) |
| `x-apigenie-broadway` | **Where:** The Kafka binding of an AsyncAPI operation or channel.<br>**Value:** `batch_size` and `batch_timeout` of the Broadway pipeline.<br>**Read by:** [server phoenix (AsyncAPI)](/docs/reference/generator/server-phoenix-asyncapi) |

`x-apigenie-lint-disable`, `x-apigenie-mock`, `x-apigenie-mock-faker` and the `codegen` members of
`x-apigenie` are part of the [compatibility promise](/docs/reference/cli/compatibility#what-the-promise-covers).

`X-Apigenie-Mock-*` and `X-Apigenie-Test` are HTTP headers and gRPC metadata, not extensions: see
[Responses](/docs/reference/server/responses), [Protobuf and gRPC](/docs/reference/server/grpc)
and [Recording](/docs/reference/server/recording).

## Lifecycle and governance

| Extension | Where it goes, its value, and the tools that read it |
| --------- | ---------------------------------------------------- |
| `x-sunset` | **Where:** Next to `deprecated: true`: an operation, a parameter, a schema, a property (beside its `$ref` or where it is defined).<br>**Value:** An RFC 3339 date (`2027-01-31`) or date-time after which the element may go.<br>**Read by:** [`apigenie diff`](/docs/reference/cli/diff), the `sunset_passed` condition of OpenAPI and Swagger 2.0 rules; written by [`apigenie evolve plan`](/docs/reference/cli/evolve) |
| `x-deprecated-enum` | **Where:** A schema with an `enum`.<br>**Value:** The enum values that are deprecated; the schema's `x-sunset` says when they may go.<br>**Read by:** [`apigenie diff`](/docs/reference/cli/diff), the `deprecated` condition; written by [`apigenie evolve plan`](/docs/reference/cli/evolve) |
| `x-audience` | **Where:** `info`.<br>**Value:** `internal-team`, `internal-company`, `partner` or `public`.<br>**Read by:** The `audience-defined` rule of [OpenAPI](/docs/linter/openapi/rules/audience-defined), [Swagger 2.0](/docs/linter/swagger/rules/audience-defined) and [AsyncAPI](/docs/linter/asyncapi/rules/audience-defined) |
| `x-id` | **Where:** `info`.<br>**Value:** A UUID, or a value matching the rule's `pattern`; the rule's `attribute` can name another extension.<br>**Read by:** The `id-defined` rule of [OpenAPI](/docs/linter/openapi/rules/id-defined) and [Swagger 2.0](/docs/linter/swagger/rules/id-defined) |

## OpenAPI 3.2 fields in 3.0 and 3.1 documents

The OpenAPI reader reads these extensions as the field of a later version they stand for:
`x-webhooks` in a 3.0 document, the others in a 3.0 or 3.1 document. The tools that write such a
document write the field back as the extension.

| Extension | Where it goes, its value, and the tools that read it |
| --------- | ---------------------------------------------------- |
| `x-itemSchema` | **Where:** A media type.<br>**Value:** `itemSchema`: the schema of each item of a streamed body.<br>**Read by:** client [csharp](/docs/reference/generator/client-csharp), [fetch](/docs/reference/generator/client-fetch), [go](/docs/reference/generator/client-go), [java](/docs/reference/generator/client-java), [rust](/docs/reference/generator/client-rust), [swift](/docs/reference/generator/client-swift); server [aspnet](/docs/reference/generator/server-aspnet), [axum](/docs/reference/generator/server-axum), [express](/docs/reference/generator/server-express), [hummingbird](/docs/reference/generator/server-hummingbird), [orpc](/docs/reference/generator/server-orpc), [vapor](/docs/reference/generator/server-vapor) |
| `x-defaultMapping` | **Where:** A discriminator.<br>**Value:** `defaultMapping`: the schema of the values the `mapping` does not list.<br>**Read by:** client [csharp](/docs/reference/generator/client-csharp), [elixir](/docs/reference/generator/client-elixir), [fetch](/docs/reference/generator/client-fetch), [go](/docs/reference/generator/client-go), [java](/docs/reference/generator/client-java), [python](/docs/reference/generator/client-python), [rust](/docs/reference/generator/client-rust), [swift](/docs/reference/generator/client-swift); server [aspnet](/docs/reference/generator/server-aspnet), [axum](/docs/reference/generator/server-axum), [express](/docs/reference/generator/server-express), [fastapi](/docs/reference/generator/server-fastapi), [go](/docs/reference/generator/server-go), [hummingbird](/docs/reference/generator/server-hummingbird), [orpc](/docs/reference/generator/server-orpc), [phoenix](/docs/reference/generator/server-phoenix), [spring](/docs/reference/generator/server-spring), [vapor](/docs/reference/generator/server-vapor) |
| `x-webhooks` | **Where:** The root of an OpenAPI 3.0 document.<br>**Value:** An object: `webhooks` (OpenAPI 3.1), the requests the API sends to its subscribers. Another value stays an extension.<br>**Read by:** The OpenAPI reader, so the linter, `diff`, `changelog` and the generators see them; server [aspnet](/docs/reference/generator/server-aspnet), [express](/docs/reference/generator/server-express) and [orpc](/docs/reference/generator/server-orpc) generate their senders |
| `x-nodeType` | **Where:** An XML object.<br>**Value:** `nodeType`: `element`, `attribute`, `text`, `cdata` or `none`.<br>**Read by:** [`apigenie-server`](/docs/reference/server/validation#xml-bodies) for XML bodies; written by [`apigenie convert`](/docs/reference/cli/convert) from WSDL |

## Code generation

Most of these are the names of [OpenAPI Generator](https://openapi-generator.tech/docs/templating/)
and, for Go, of [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen#openapi-extensions),
read by the API Genie generators of the same languages.

| Extension | Where it goes, its value, and the tools that read it |
| --------- | ---------------------------------------------------- |
| `x-internal` | **Where:** An operation or its path item.<br>**Value:** `true` leaves the operation out; client fetch, go and elixir, server phoenix and mcp and, since 0.12.0, client python, server go, client swift and the Swift servers (vapor, hummingbird) keep it with `internal_operations`; since 0.12.0, server fastapi serves it but leaves it out of the served OpenAPI document. Client rust and server axum generate it behind the cargo feature `internal` (`internal_operations: include` or `exclude` instead).<br>**Read by:** client [csharp](/docs/reference/generator/client-csharp), [elixir](/docs/reference/generator/client-elixir), [fetch](/docs/reference/generator/client-fetch), [go](/docs/reference/generator/client-go), [java](/docs/reference/generator/client-java), [python](/docs/reference/generator/client-python), [rust](/docs/reference/generator/client-rust), [swift](/docs/reference/generator/client-swift); server [aspnet](/docs/reference/generator/server-aspnet), [axum](/docs/reference/generator/server-axum), [fastapi](/docs/reference/generator/server-fastapi) (since 0.12.0), [go](/docs/reference/generator/server-go) (since 0.12.0), [hummingbird](/docs/reference/generator/server-hummingbird), [mcp](/docs/reference/generator/server-mcp), [phoenix](/docs/reference/generator/server-phoenix), [spring](/docs/reference/generator/server-spring), [vapor](/docs/reference/generator/server-vapor). The other targets generate the operation. |
| `x-mcp` | **Where:** An operation or its path item.<br>**Value:** `false`: the operation is not a tool.<br>**Read by:** [server mcp](/docs/reference/generator/server-mcp) |
| `x-codegen-request-body-name` | **Where:** An operation or its request body.<br>**Value:** The name of the body parameter.<br>**Read by:** [client java](/docs/reference/generator/client-java), server [fastapi](/docs/reference/generator/server-fastapi), [spring](/docs/reference/generator/server-spring); written by the editor's Swagger 2.0 import |
| `x-enum-varnames` | **Where:** A schema with an `enum`.<br>**Value:** The names of the constants, in the order of the values.<br>**Read by:** client [csharp](/docs/reference/generator/client-csharp), [csharp (AsyncAPI)](/docs/reference/generator/client-csharp-asyncapi), [go](/docs/reference/generator/client-go), [go (AsyncAPI)](/docs/reference/generator/client-go-asyncapi), [java](/docs/reference/generator/client-java), [python](/docs/reference/generator/client-python), [python (AsyncAPI)](/docs/reference/generator/client-python-asyncapi), [rust](/docs/reference/generator/client-rust), [swift](/docs/reference/generator/client-swift); server [aspnet](/docs/reference/generator/server-aspnet), [axum](/docs/reference/generator/server-axum), [aspnet (AsyncAPI)](/docs/reference/generator/server-aspnet-asyncapi), [faststream](/docs/reference/generator/server-faststream), [go](/docs/reference/generator/server-go), [go (AsyncAPI)](/docs/reference/generator/server-go-asyncapi), [hummingbird](/docs/reference/generator/server-hummingbird), [spring](/docs/reference/generator/server-spring), [vapor](/docs/reference/generator/server-vapor) |
| `x-enumNames` | **Where:** A schema with an `enum`.<br>**Value:** The same as `x-enum-varnames`.<br>**Read by:** client [go](/docs/reference/generator/client-go), [go (AsyncAPI)](/docs/reference/generator/client-go-asyncapi), [python](/docs/reference/generator/client-python), [python (AsyncAPI)](/docs/reference/generator/client-python-asyncapi), [rust](/docs/reference/generator/client-rust), [swift](/docs/reference/generator/client-swift); server [axum](/docs/reference/generator/server-axum), [faststream](/docs/reference/generator/server-faststream), [go](/docs/reference/generator/server-go), [go (AsyncAPI)](/docs/reference/generator/server-go-asyncapi), [hummingbird](/docs/reference/generator/server-hummingbird), [vapor](/docs/reference/generator/server-vapor) |
| `x-enum-names` | **Where:** A schema with an `enum`.<br>**Value:** The same as `x-enum-varnames`.<br>**Read by:** client [csharp](/docs/reference/generator/client-csharp), [csharp (AsyncAPI)](/docs/reference/generator/client-csharp-asyncapi); server [aspnet](/docs/reference/generator/server-aspnet), [aspnet (AsyncAPI)](/docs/reference/generator/server-aspnet-asyncapi) |
| `x-enum-descriptions` | **Where:** A schema with an `enum`.<br>**Value:** The documentation comments of the constants, in the order of the values.<br>**Read by:** client [csharp](/docs/reference/generator/client-csharp), [csharp (AsyncAPI)](/docs/reference/generator/client-csharp-asyncapi), [go](/docs/reference/generator/client-go), [go (AsyncAPI)](/docs/reference/generator/client-go-asyncapi), [java](/docs/reference/generator/client-java), [rust](/docs/reference/generator/client-rust), [swift](/docs/reference/generator/client-swift); server [aspnet](/docs/reference/generator/server-aspnet), [axum](/docs/reference/generator/server-axum), [aspnet (AsyncAPI)](/docs/reference/generator/server-aspnet-asyncapi), [go](/docs/reference/generator/server-go), [go (AsyncAPI)](/docs/reference/generator/server-go-asyncapi), [hummingbird](/docs/reference/generator/server-hummingbird), [spring](/docs/reference/generator/server-spring), [vapor](/docs/reference/generator/server-vapor) |
| `x-enumDescriptions` | **Where:** A schema with an `enum`.<br>**Value:** The same as `x-enum-descriptions`.<br>**Read by:** client [csharp](/docs/reference/generator/client-csharp), [csharp (AsyncAPI)](/docs/reference/generator/client-csharp-asyncapi); server [aspnet](/docs/reference/generator/server-aspnet), [aspnet (AsyncAPI)](/docs/reference/generator/server-aspnet-asyncapi) |

### Go

Read by client [go](/docs/reference/generator/client-go) and
[go (AsyncAPI)](/docs/reference/generator/client-go-asyncapi), and server
[go](/docs/reference/generator/server-go) and
[go (AsyncAPI)](/docs/reference/generator/server-go-asyncapi).

| Extension | Where | Value |
| --------- | ----- | ----- |
| `x-go-name` | A schema or a property | The name of the type or of the field |
| `x-go-type` | A schema | The Go type to use, e.g. `decimal.Decimal` |
| `x-go-type-import` | A schema with `x-go-type` | `{path: ...}`: the package of the type |
| `x-go-type-skip-optional-pointer` | A property | `true`: the optional field is not a pointer |
| `x-go-json-ignore` | A property | `true`: the field gets the tag `json:"-"` |
| `x-omitempty` | A property | `true` or `false` overrides the `omitempty` of the field |

### Rust

Read by [client rust](/docs/reference/generator/client-rust) and
[server axum](/docs/reference/generator/server-axum), since 0.12.0.

| Extension | Where | Value |
| --------- | ----- | ----- |
| `x-rust-name` | A schema | The name of its type |
| `x-rust-type` | A schema | The Rust type to use, a path such as `my_crate::Money`, or a name `type_mappings` maps to one |

### Swift

Read by client [swift](/docs/reference/generator/client-swift) and server [hummingbird](/docs/reference/generator/server-hummingbird) and [vapor](/docs/reference/generator/server-vapor).

| Extension | Where | Value |
| --------- | ----- | ----- |
| `x-swift-name` | A schema or a property | The name of the type or of the property |

### Java and Spring

Read by [client java](/docs/reference/generator/client-java) and
[server spring](/docs/reference/generator/server-spring); a value that is a list of annotations or
arguments can also be one string.

| Extension | Where | Value |
| --------- | ----- | ----- |
| `x-class-extra-annotation` | A schema | Annotations of its class, e.g. `['@Entity']` |
| `x-implements` | A schema | Interfaces its class implements |
| `x-field-extra-annotation` | A property or a parameter | Annotations of the field or of the method parameter |
| `x-extra-annotation` | A property | Annotations of the getter |
| `x-setter-extra-annotation` | A property | Annotations of the setter |
| `x-pattern-message`, `x-size-message`, `x-minimum-message`, `x-maximum-message` | A property | The `message` of `@Pattern`, `@Size`, `@Min` or `@DecimalMin`, `@Max` or `@DecimalMax` |
| `x-jackson-json-include-policy` | A property | The `@JsonInclude` policy, e.g. `non_empty`; `none` for no annotation |
| `x-jackson-json-setter-nulls` | A property | `@JsonSetter(nulls = ...)`, e.g. `skip`; `none` for no annotation |
| `x-parent` | A schema | `true`: the superclass of the schemas extending it with `allOf`, without a discriminator |
| `x-discriminator-value` | A schema extending one with a discriminator | Its value in `@JsonSubTypes`; the name of the schema by default |
| `x-jackson-default-impl` | A schema with a discriminator | The `defaultImpl` of its `@JsonTypeInfo` |
| `x-operation-extra-annotation` | An operation | Annotations of its method; not with `spring-http-interface` |
| `x-version-param` | A header or query parameter | `true` adds it to the `headers` or `params` of `@RequestMapping`; not with `spring-http-interface` |
| `x-spring-paginated` | An operation | `true` replaces `page`, `size` and `sort` with a `Pageable`; `false` keeps them with `autoXSpringPaginated`. Spring only |
| `x-spring-provide-args` | An operation | Further arguments of its method, e.g. `['@RequestAttribute("tenant") String tenant']`. Spring only, not with `spring-http-interface` |

## Swagger 2.0

| Extension | Where it goes, its value, and the tools that read it |
| --------- | ---------------------------------------------------- |
| `x-nullable` | **Where:** A schema.<br>**Value:** `true`: `null` is a valid value.<br>**Read by:** [`apigenie convert`](/docs/reference/cli/convert) (adds `null` to the type), [schema zod](/docs/reference/generator/schema-zod), the documentation components, the editor's Swagger 2.0 import |
| `x-example` | **Where:** A parameter or a schema.<br>**Value:** An example value.<br>**Read by:** [`apigenie convert`](/docs/reference/cli/convert) (becomes `example`), the editor's Swagger 2.0 import; the documentation components, on a parameter |

## Written by `apigenie convert`

A document [converted from WSDL](/docs/reference/cli/convert) keeps what OpenAPI has no field for
in extensions. No tool reads them back.

| Extension | Where | Value |
| --------- | ----- | ----- |
| `x-wsdl-target-namespace` | `info` | The `targetNamespace` of the WSDL |
| `x-soap-address` | An operation | The address of the port |
| `x-soap-action` | An operation | The SOAPAction of the operation |
