Changelog

  • 2026-09-28

    • new improved look of the guide:

      • chapters on different pages and a search box

      • reorganized chapter structure:

        • standard problem types, lists of HTTP methods and status codes, reserved words and changelog moved to annexes

        • the HTTP chapter bundles the rules on use of appropriate HTTP methods, status codes, media types and content negotiation

    • update rule [evo-compat] and Versioning chapter to also cover asynchronous messages. Improve list of compatible extensions : update guideline on input enum values updates and remove redirection.

    • update rule [col-get]: add alternative POST /search controller for complex input structure.

    • update rule [addi-prop]: explicitly recommend against the use of additionalProperties: false

    • update rule [oas-comp]: $ref should always point to a named component under /components, not inline definitions

    • updates in Events and asynchronous messaging chapter:

      • distinguish between event, command and query archetypes

      • update rule [async-svctype]: new naming convention of type

      • update rule [async-ctxt]: specversion attribute and handling unknown context attributes

      • new rule [async-prbl]: problem replies

      • new rule [async-size]: size of Asynchronous Messages and the claim check pattern

    • examples throughout the guide were updated. Problem examples now use JSON Pointer to refer to input properties in a message body

  • 2026-06-12

    • new rule [rule-sens-dat] on sensitive data in URLs or headers

    • new rule [sch-discr] split of from [sch-oneof] and [sch-allof] on URI-reference syntax for discriminator mapping

    • added link to example schema to Pagination

    • update [sch-oneof]: discriminator mapping should include all oneOf subschemas

    • new rule [sec-req]: security requirements must be consistent with security schemes

    • new rule [sch-opbody-req]: required should be specified explicitly on request bodies

    • reference the RFCs on requirements levels (MUST, SHOULD, etc.) in Introduction, and replace MANDATORY by REQUIRED throughout the guide

  • 2026-04-28

    • update [sch-allof] and [sch-oneof]: guidelines on use of discriminator and mapping

    • new rule [child-ent] on representation of child entities

    • update rule [oas-descr] with exception for title within allOf and not inline schemas

    • update [async-svctype]: service should be prefixed with a reverse-DNS name

    • new rule [async-order] on out-of-order and duplicate messages

    • update rule [async-cespec]:

      • clarify that an Asynchronous Message is immutable and all functional data should be part of it (i.e. not exclusively in exchange protocol)

      • guidelines on context attributes were split off to [async-ctxt]

    • new rule [async-generic] with guidelines on generic endpoints for Asynchronous Messages

    • add a list of organizations that endorse this guide (Introduction)

  • 2026-02-16

    • new rule [oas-doc] on providing documentation in OpenAPI. This replaces the previous [ext-docs] rule.

    • update rule [oas-descr]:

      • extended with all OpenAPI free-text documentation properties

      • a summary should now be present for each operation

      • for inline schemas of type object, a title is now recommended. For schema components, it shouldn’t override the component name if present.

    • update rule [sch-oneof]: changed allowed usage to ensure tooling compatibility (object subschemas with discriminator, subschemas with only required and enum subschemas)

    • update [trc-header]: make UUIDv4 optional for trace ids and recommend randomness

  • 2025-11-25

  • 2025-09-24

    • add rules about composition, inheritance and polymorphism in schemas using oneOf, allOf and discriminator in [sch-allof] and [sch-oneof]

    • add linked documentation pages for each issue type in Bad Request

    • improve internationalization.adoc#internationalization guidelines:

      • clarifications on the Content-Language header

      • language choice may also be based on a user profile

      • update [int-negot]: language priority using q param, matching regional language variants and fallback behavior

    • (minor): apply OAS definitions for an OpenAPI (entry) document and OpenAPI description throughout the guide

  • 2025-06-16

    • recommend OpenAPI 3.0 and remove OpenAPI 2.0 throughout the guide

    • new in Bad Request Problem: standardized invalidInput issue type

    • update section Identifier: describe potential compatibility problems with escaped slash values in path params

    • update rule [id-name]: always prefix id and code path param names with their resource type

    • update description 409 Conflict status: conflict with "data on the server" instead of "current state of the target resource". Remove optimistic locking issue (usually 412)

  • 2025-01-28

    • new in Bad Request Problem: standardized referencedResourceNotFound issue type

    • update of Standardized problem types: add WWW-Authenticate header for access token or scope problems

    • update rule [int-negot]: a default fallback language should be used when Accept-Language header can’t be respected

Older changes