OpenAPI 3.1 Callbacks – Missing Deterministic Ordering

Answer

OpenAPI 3.1 does not define a deterministic invocation order for callbacks. The spec defines callbacks as a map of names to callback objects and treats the map as unordered. There is no standard field for priority or sequence, and no standard API in client generators to retrieve callbacks in definition order.

Confirmed facts

• Callbacks are specified as a map. The OpenAPI 3.1 specification states that map order is not significant.
• JSON object key order is not guaranteed by the JSON language spec. Different parsers and serializers may traverse keys in different orders.
• Client code generators such as OpenAPI Generator and Swagger Codegen typically iterate over the callbacks map. The iteration order you see is an implementation detail, often lexical by key, and is not exposed as a stable API.

Likely explanation

Because the spec provides no ordering semantics, tooling defaults to whatever the underlying map implementation provides. Swagger UI and many generators will serialize callbacks in lexical order by default, which may appear deterministic but does not reflect author intent and can change after re-serialization. Server frameworks that read the spec will usually ignore map order entirely.

Vendor extensions and best practice

There is no standardized extension for callback priority. In practice some teams use non-standard extensions such as x-order or x-callback-order on the callback entry to hint at desired priority. These are not part of OpenAPI 3.1, are not widely adopted, and will be ignored by tools that do not explicitly look for them. Use of such extensions reduces portability.

Enforcing deterministic order in a server framework

If you must enforce order, make it explicit in your implementation, not in the spec ordering:

1. Require an explicit priority. Define a convention in your project, e.g., a numeric x-order on each callback entry, and document it as a project-specific contract.
2. Normalize on load. When the spec is parsed, collect callback entries into an array and sort by the explicit priority, falling back to a stable secondary key such as the callback name.
3. Register and invoke in sorted order. Build the callback registry from the sorted array instead of iterating the raw map.

Do not rely on YAML/JSON source order or lexical key order for correctness.

Verification step: create a minimal spec with two callbacks, add an x-order value to each, load it with your parser, log the registration order, and confirm the sort is applied before invocation.

One missing diagnostic detail that changes the recommendation: which server framework and spec parser you are using. The exact loading and sorting code depends on that stack.