OpenAPI and AsyncAPI documents live in openapi/ and asyncapi/

Context

ADR#9316364013 reserves proto/, wit/ and otel/ for schema sources, and ADR#4711775939 fixes the layout inside each. OpenAPI and AsyncAPI documents describe HTTP and message-driven interfaces the same way, but neither ADR names a place for them. Repositories place them under docs/, api/, spec/ or the repository root, so tooling paths drift and the layout is learned again on every clone.

Unlike buf or Weaver, neither specification dictates a directory layout, so the second level has to be decided here.

Resolution

• You MUST add openapi/ and asyncapi/ to the schema source directories reserved by ADR#9316364013, one directory per specification, named after the specification and not after a tool.

• You MUST NOT place these documents in docs/, api/ or spec/, or loose at the repository root.

• You MUST keep only hand-written specification documents, and the specification fragments and examples they reference, in the directory. Configuration that drives a tool, such as linting or code generation, goes under .config/<tool>/. Generated code MUST live in the language workspace that consumes it.

• You MUST NOT commit a document generated from another schema source, such as proto/, or from code. Generate it at build time instead.

• You MUST write documents in YAML.

• You MUST name the document openapi.yaml or asyncapi.yaml, and place it directly in the directory when the repository describes one interface. When it describes more than one, you MUST use <interface>/ per interface, where <interface> is unique within the directory and names the component and, when that component exposes several, the audience or version, such as payments-public or payments-admin.

• You MAY place the directory next to a single component or service when the document belongs to that component alone. It MUST still use the same name.

• You MUST keep prose about the interface, such as guides and explanations, out of these directories. It follows ADR#3223845695.

  .
  ├── openapi
  │   ├── openapi.yaml              # one interface
  │   └── <interface>/openapi.yaml  # more than one interface
  └── asyncapi
      ├── asyncapi.yaml
      └── <interface>/asyncapi.yaml

Links

• ADR#9316364013: Reserved repository directories
• ADR#4711775939: Schema source directories
• ADR#3223845695: Documentation structure
• OpenAPI Specification, document structure
• AsyncAPI specification