Specification extensions

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 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).
  • apigenie 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 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).

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

X-Apigenie-Mock-* and X-Apigenie-Test are HTTP headers and gRPC metadata, not extensions: see Responses, Protobuf and gRPC and 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).
Value: An RFC 3339 date (2027-01-31) or date-time after which the element may go.
Read by: apigenie diff, the sunset_passed condition of OpenAPI and Swagger 2.0 rules; written by apigenie evolve plan
x-deprecated-enum Where: A schema with an enum.
Value: The enum values that are deprecated; the schema’s x-sunset says when they may go.
Read by: apigenie diff, the deprecated condition; written by apigenie evolve plan
x-audience Where: info.
Value: internal-team, internal-company, partner or public.
Read by: The audience-defined rule of OpenAPI, Swagger 2.0 and AsyncAPI
x-id Where: info.
Value: A UUID, or a value matching the rule’s pattern; the rule’s attribute can name another extension.
Read by: The id-defined rule of OpenAPI and Swagger 2.0

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.
Value: itemSchema: the schema of each item of a streamed body.
Read by: client csharp, fetch, go, java, rust, swift; server aspnet, axum, express, hummingbird, orpc, vapor
x-defaultMapping Where: A discriminator.
Value: defaultMapping: the schema of the values the mapping does not list.
Read by: client csharp, elixir, fetch, go, java, python, rust, swift; server aspnet, axum, express, fastapi, go, hummingbird, orpc, phoenix, spring, vapor
x-webhooks Where: The root of an OpenAPI 3.0 document.
Value: An object: webhooks (OpenAPI 3.1), the requests the API sends to its subscribers. Another value stays an extension.
Read by: The OpenAPI reader, so the linter, diff, changelog and the generators see them; server aspnet, express and orpc generate their senders
x-nodeType Where: An XML object.
Value: nodeType: element, attribute, text, cdata or none.
Read by: apigenie-server for XML bodies; written by apigenie convert from WSDL

Code generation

Most of these are the names of OpenAPI Generator and, for Go, of oapi-codegen, 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.
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).
Read by: client csharp, elixir, fetch, go, java, python, rust, swift; server aspnet, axum, fastapi (since 0.12.0), go (since 0.12.0), hummingbird, mcp, phoenix, spring, vapor. The other targets generate the operation.
x-mcp Where: An operation or its path item.
Value: false: the operation is not a tool.
Read by: server mcp
x-codegen-request-body-name Where: An operation or its request body.
Value: The name of the body parameter.
Read by: client java, server fastapi, spring; written by the editor’s Swagger 2.0 import
x-enum-varnames Where: A schema with an enum.
Value: The names of the constants, in the order of the values.
Read by: client csharp, csharp (AsyncAPI), go, go (AsyncAPI), java, python, python (AsyncAPI), rust, swift; server aspnet, axum, aspnet (AsyncAPI), faststream, go, go (AsyncAPI), hummingbird, spring, vapor
x-enumNames Where: A schema with an enum.
Value: The same as x-enum-varnames.
Read by: client go, go (AsyncAPI), python, python (AsyncAPI), rust, swift; server axum, faststream, go, go (AsyncAPI), hummingbird, vapor
x-enum-names Where: A schema with an enum.
Value: The same as x-enum-varnames.
Read by: client csharp, csharp (AsyncAPI); server aspnet, aspnet (AsyncAPI)
x-enum-descriptions Where: A schema with an enum.
Value: The documentation comments of the constants, in the order of the values.
Read by: client csharp, csharp (AsyncAPI), go, go (AsyncAPI), java, rust, swift; server aspnet, axum, aspnet (AsyncAPI), go, go (AsyncAPI), hummingbird, spring, vapor
x-enumDescriptions Where: A schema with an enum.
Value: The same as x-enum-descriptions.
Read by: client csharp, csharp (AsyncAPI); server aspnet, aspnet (AsyncAPI)

Go

Read by client go and go (AsyncAPI), and server go and 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 and 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 and server hummingbird and 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 and 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.
Value: true: null is a valid value.
Read by: apigenie convert (adds null to the type), schema zod, the documentation components, the editor’s Swagger 2.0 import
x-example Where: A parameter or a schema.
Value: An example value.
Read by: apigenie 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 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
Was this helpful?