Table of Contents

OpenAPI schema payloads

Bielu.AspNetCore.AsyncApi.OpenApiSchema describes message payloads as OpenAPI 3.0 Schema Objects. AsyncAPI lets a payload use a schema format other than its own through schemaFormat, and the OpenAPI 3.0 Schema Object is one the specification lists. Use it when the tools that read your event payloads were built for OpenAPI, such as code generators, mock servers or validators, so they read event payloads the same way they read HTTP request and response bodies.

dotnet add package Bielu.AspNetCore.AsyncApi.OpenApiSchema
builder.Services.AddAsyncApi(options => options
    .AddServer("kafka", "broker:9092", "kafka")
    .AddOpenApiSchemaPayloads());

Each message payload becomes a multi-format schema:

"payload": {
  "schemaFormat": "application/vnd.oai.openapi;version=3.0.0",
  "schema": {
    "type": "object",
    "properties": {
      "orderId": { "type": "string", "format": "uuid" },
      "total": { "type": "number", "format": "double", "minimum": 0, "exclusiveMinimum": true },
      "note": { "type": "string", "nullable": true }
    }
  }
}

In an AsyncAPI 2.6 document the schemaFormat sits on the message, as that version defines it.

How JSON Schema maps to OpenAPI 3.0

The OpenAPI schema is converted from the JSON Schema the generator already produces, so it follows the same .NET types, naming policy and schema transformers. There is no second definition to keep in sync. OpenAPI 3.0's Schema Object is a dialect of JSON Schema, so most keywords carry over unchanged. These are rewritten:

JSON Schema OpenAPI 3.0
"type": ["null", "string"] "type": "string", "nullable": true
several types, "type": ["string", "integer"] anyOf with one type per branch (an array branch gets the items), and "enum": [null] as a branch when null is one of them
"type": "null" "enum": [null]
a null branch in oneOf / anyOf kept as an "enum": [null] branch
"exclusiveMinimum": 0 "minimum": 0, "exclusiveMinimum": true (likewise for the maximum)
const a one-value enum; beside an enum, the values both allow
examples example, the first of them
"discriminator": "kind" "discriminator": { "propertyName": "kind" }
false schema "not": {}, or false as additionalProperties
$ref to components/schemas the referenced schema, written inline

OpenAPI 3.0 allows no keywords beyond its own, so if/then/else, contains, patternProperties, propertyNames and additionalItems are dropped. Extensions (x-…) are kept.

References

Referenced component schemas are written inline, so the whole payload is in the OpenAPI dialect. A recursive type cannot be inlined forever: the reference that would repeat a schema already being written points at an OpenAPI copy of that component, added under components/schemas as <name>.openapi with its own schemaFormat, so the payload never refers to JSON Schema. AsyncAPI 2.6 component schemas cannot declare a schema format, so in a 2.6 document the copy is written as the JSON Schema and the reference points at the original component. A reference outside components/schemas, or one that cannot be resolved, is kept as it is.

Options

Option Effect
ForMessages("orderPlaced", …) / MessageFilter Only these messages, by their key under components/messages.

The declared format is always application/vnd.oai.openapi;version=3.0.0, the only OpenAPI version the AsyncAPI specification lists.

What stays the same

  • The JSON Schemas stay under components/schemas, so anything else that references them keeps working.
  • Headers stay JSON Schema.
  • A payload already in another schema format, such as Avro or Protobuf, is left alone.

AddOpenApiSchemaPayloads() adds a document transformer. Document transformers run in the order they are added, so add it after anything else that adds messages, such as AddWolverine().

Conformance

The test suite validates the output against the official AsyncAPI 2.6.0 and 3.1.0 JSON Schemas. Those schemas include the OpenAPI 3.0 Schema Object definition, so the converted payloads are checked too.