asyncapi-authoring

name	asyncapi-authoring
description	Author and validate AsyncAPI 3.0 specifications for event-driven API design, message brokers, and async communication patterns
allowed-tools	Read, Write, Edit, Glob, Grep, Bash

AsyncAPI Authoring Skill

When to Use This Skill

Use this skill when:

• Asyncapi Authoring tasks - Working on author and validate asyncapi 3.0 specifications for event-driven api design, message brokers, and async communication patterns
• Planning or design - Need guidance on Asyncapi Authoring approaches
• Best practices - Want to follow established patterns and standards

Overview

Author AsyncAPI 3.0 specifications for event-driven architectures and async communication patterns.

AsyncAPI 3.0 Structure

Root Document

asyncapi: "3.0.0"

info:
  title: "{Service Name} Events API"
  version: "1.0.0"
  description: |
    Event-driven API for {service} domain events and commands.
  contact:
    name: "{Team Name}"
    email: "{[e-mail]}"
  license:
    name: "MIT"

servers:
  production:
    host: "kafka.example.com:9092"
    protocol: "kafka"
    description: "Production Kafka cluster"
    security:
      - $ref: "#/components/securitySchemes/sasl"

  development:
    host: "localhost:9092"
    protocol: "kafka"
    description: "Local development"

defaultContentType: "application/json"

channels:
  # Channel definitions

operations:
  # Operation definitions

components:
  # Reusable components

Channels (AsyncAPI 3.0)

channels:
  orderEvents:
    address: "orders.events.{orderId}"
    description: "Channel for order lifecycle events"
    parameters:
      orderId:
        description: "Order unique identifier"
        schema:
          type: string
          format: uuid
    messages:
      orderCreated:
        $ref: "#/components/messages/OrderCreated"
      orderShipped:
        $ref: "#/components/messages/OrderShipped"
      orderDelivered:
        $ref: "#/components/messages/OrderDelivered"
      orderCancelled:
        $ref: "#/components/messages/OrderCancelled"

  orderCommands:
    address: "orders.commands"
    description: "Channel for order command messages"
    messages:
      createOrder:
        $ref: "#/components/messages/CreateOrderCommand"
      cancelOrder:
        $ref: "#/components/messages/CancelOrderCommand"

  inventoryUpdates:
    address: "inventory.updates.{productId}"
    description: "Real-time inventory level updates"
    parameters:
      productId:
        
           
    
      
         

Operations (AsyncAPI 3.0)

operations:
  # Publishing operations (this service sends)
  publishOrderCreated:
    action: send
    channel:
      $ref: "#/channels/orderEvents"
    summary: "Publish order created event"
    description: |
      Published when a new order is successfully created.
      Consumers should use this to trigger downstream processes.
    messages:
      - $ref: "#/channels/orderEvents/messages/orderCreated"
    tags:
      - name: "orders"
      - name: "lifecycle"

  publishOrderShipped:
    action: send
    channel:
      $ref: "#/channels/orderEvents"
    summary: "Publish order shipped event"
    messages:
      - $ref: "#/channels/orderEvents/messages/orderShipped"

  # Receiving operations (this service receives)
  receiveCreateOrderCommand:
    action: receive
    channel:
      $ref: "#/channels/orderCommands"
    summary: "Process create order commands"
    description: |
      Receives commands to create new orders.
      Will publish OrderCreated event on success.
    messages:
        

  
  
     
    
       
     
         
        

Message Definitions

components:
  messages:
    OrderCreated:
      name: "OrderCreated"
      title: "Order Created Event"
      summary: "Indicates a new order has been created"
      contentType: "application/json"
      headers:
        $ref: "#/components/schemas/EventHeaders"
      payload:
        $ref: "#/components/schemas/OrderCreatedPayload"
      correlationId:
        location: "$message.header#/correlationId"
      traits:
        - $ref: "#/components/messageTraits/commonHeaders"

    OrderShipped:
      name: "OrderShipped"
      title: "Order Shipped Event"
      summary: "Indicates an order has been shipped"
      contentType: "application/json"
      headers:
        $ref: "#/components/schemas/EventHeaders"
      payload:
        $ref: "#/components/schemas/OrderShippedPayload"
      traits:
        - $ref: "#/components/messageTraits/commonHeaders"

    OrderCancelled:
      name: "OrderCancelled"
      title: "Order Cancelled Event"
       
       
      
         
      
         

    
       
       
       
       
      
         
      
         

    
       
       
       
       
      
         

Payload Schemas

components:
  schemas:
    # Event headers
    EventHeaders:
      type: object
      required:
        - eventId
        - eventType
        - timestamp
        - version
      properties:
        eventId:
          type: string
          format: uuid
          description: "Unique event identifier"
        eventType:
          type: string
          description: "Event type name"
        timestamp:
          type: string
          format: date-time
          description: "Event timestamp (ISO 8601)"
        version:
          type: string
          description: "Event schema version"
          example: "1.0"
        correlationId:
          type: string
          format: uuid
          description: "Correlation ID for tracing"
        causationId:
          type: string
           
           

    
       
      
         
         
         
      
        
           
           
           
        
           
           
        
           
           
        
           
           
        
           
           

    
    
       
      
         
         
         
         
         
      
        
           
           
        
           
           
        
           
          
             
        
           
        
           
        
           
           

    
       
      
         
         
         
         
      
        
           
           
        
           
        
           
          
             
             
             
             
        
           
           
        
           
           

    
       
      
         
         
         
      
        
           
           
        
           
          
             
             
             
             
        
           
        
           
           
        
           
           

    
    
       
      
         
         
      
        
           
           
        
           
           
          
             
        
           
        
           
        
           

    
    
       
      
         
         
         
         
      
        
           
           
        
           
        
           
           
        
           

    
       
      
         
         
      
        
           
           
        
           
           

    
       
      
         
         
      
        
           
           
           
        
           
           
           

    
       
      
         
         
         
      
        
           
        
           
        
           
        
           
        
           
           

    
       
      
         
         
         
         
         
      
        
           
           
        
           
        
           
        
           
          
             
             
             
             
             
        
           
           

Message Traits and Security

components:
  messageTraits:
    commonHeaders:
      headers:
        type: object
        properties:
          x-trace-id:
            type: string
            description: "Distributed tracing ID"
          x-span-id:
            type: string
            description: "Span ID for tracing"

  securitySchemes:
    sasl:
      type: scramSha256
      description: "SASL/SCRAM-SHA-256 authentication"

    apiKey:
      type: apiKey
      in: user
      description: "API key authentication"

    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: "https://auth.example.com/token"
          scopes:
            "events:publish": "Publish events"
            "events:subscribe": "Subscribe to events"

  serverBindings:
    kafka:
      schemaRegistryUrl: "https://schema-registry.example.com"
      schemaRegistryVendor: "confluent"

C# Models for AsyncAPI

namespace SpecDrivenDevelopment.AsyncApi;

/// <summary>
/// Represents an AsyncAPI 3.0 specification document
/// </summary>
public record AsyncApiSpec
{
    public required string AsyncApi { get; init; } = "3.0.0";
    public required AsyncApiInfo Info { get; init; }
    public Dictionary<string, AsyncApiServer> Servers { get; init; } = [];
    public string? DefaultContentType { get; init; }
    public Dictionary<string, AsyncApiChannel> Channels { get; init; } = [];
    public Dictionary<string, AsyncApiOperation> Operations { get; init; } = [];
    public AsyncApiComponents? Components { get; init; }
}

public record AsyncApiInfo
{
    public required string Title { get; init; }
    public required  Version { ; ; }
     ? Description { ; ; }
     AsyncApiContact? Contact { ; ; }
     AsyncApiLicense? License { ; ; }
}

  
{
     ? Name { ; ; }
     ? Email { ; ; }
     ? Url { ; ; }
}

  
{
       Name { ; ; }
     ? Url { ; ; }
}

  
{
       Host { ; ; }
       Protocol { ; ; }
     ? ProtocolVersion { ; ; }
     ? Description { ; ; }
     List<Dictionary<, List<>>>? Security { ; ; }
     Dictionary<, >? Bindings { ; ; }
}

  
{
       Address { ; ; }
     ? Description { ; ; }
     Dictionary<, AsyncApiParameter>? Parameters { ; ; }
     Dictionary<, AsyncApiMessage>? Messages { ; ; }
     Dictionary<, >? Bindings { ; ; }
}

  
{
     ? Description { ; ; }
     AsyncApiSchema? Schema { ; ; }
     ? Location { ; ; }
}

  
{
      OperationAction Action { ; ; }
      AsyncApiChannelRef Channel { ; ; }
     ? Summary { ; ; }
     ? Description { ; ; }
     List<AsyncApiMessageRef>? Messages { ; ; }
     List<AsyncApiTag>? Tags { ; ; }
     List<Dictionary<, List<>>>? Security { ; ; }
     Dictionary<, >? Bindings { ; ; }
}

  OperationAction
{
    Send,
    Receive
}

  
{
     ? Ref { ; ; }
}

  
{
     ? Ref { ; ; }
}

  
{
     ? Name { ; ; }
     ? Title { ; ; }
     ? Summary { ; ; }
     ? Description { ; ; }
     ? ContentType { ; ; }
     AsyncApiSchema? Headers { ; ; }
     AsyncApiSchema? Payload { ; ; }
     AsyncApiCorrelationId? CorrelationId { ; ; }
     List<AsyncApiMessageTraitRef>? Traits { ; ; }
     Dictionary<, >? Bindings { ; ; }
}

  
{
     ? Description { ; ; }
       Location { ; ; }
}

  
{
     ? Ref { ; ; }
}

  
{
       Name { ; ; }
     ? Description { ; ; }
}

  
{
     ? Type { ; ; }
     ? Format { ; ; }
     ? Description { ; ; }
     List<>? Enum { ; ; }
     ? Default { ; ; }
     ? Example { ; ; }
     List<>? Required { ; ; }
     Dictionary<, AsyncApiSchema>? Properties { ; ; }
     AsyncApiSchema? Items { ; ; }
     ? MinItems { ; ; }
     ? MaxItems { ; ; }
     ? MinLength { ; ; }
     ? MaxLength { ; ; }
     ? Minimum { ; ; }
     ? Maximum { ; ; }
     ? Pattern { ; ; }
     List<AsyncApiSchema>? AllOf { ; ; }
     List<AsyncApiSchema>? OneOf { ; ; }
     List<AsyncApiSchema>? AnyOf { ; ; }
     ? Ref { ; ; }
}

  
{
     Dictionary<, AsyncApiSchema>? Schemas { ; ; }
     Dictionary<, AsyncApiMessage>? Messages { ; ; }
     Dictionary<, AsyncApiParameter>? Parameters { ; ; }
     Dictionary<, AsyncApiSecurityScheme>? SecuritySchemes { ; ; }
     Dictionary<, AsyncApiMessageTrait>? MessageTraits { ; ; }
     Dictionary<, AsyncApiOperationTrait>? OperationTraits { ; ; }
}

  
{
       Type { ; ; }
     ? Description { ; ; }
     ? In { ; ; }
     ? Name { ; ; }
     AsyncApiOAuthFlows? Flows { ; ; }
}

  
{
     AsyncApiOAuthFlow? ClientCredentials { ; ; }
}

  
{
       TokenUrl { ; ; }
      Dictionary<, > Scopes { ; ; }
}

  
{
     AsyncApiSchema? Headers { ; ; }
     ? ContentType { ; ; }
}

  
{
     ? Summary { ; ; }
     ? Description { ; ; }
     List<AsyncApiTag>? Tags { ; ; }
}

Event Design Patterns

Event Naming Conventions

event_naming:
  format: "{Aggregate}{Action}"

  past_tense_events:
    description: "Events describe something that happened"
    examples:
      - "OrderCreated"
      - "OrderShipped"
      - "PaymentProcessed"
      - "UserRegistered"
      - "InventoryReserved"

  command_naming:
    format: "{Action}{Aggregate}Command"
    examples:
      - "CreateOrderCommand"
      - "CancelOrderCommand"
      - "ProcessPaymentCommand"

  channel_naming:
    pattern: "{domain}.{type}.{resource}"
    examples:
      - "orders.events" (all order events)
      - "orders.events.{orderId}" (specific order)
      - "orders.commands" (order commands)
      - "inventory.updates.{productId}" (inventory changes)

Event Envelope Pattern

event_envelope:
  description: "Standardized wrapper for all events"

  structure:
    metadata:
      eventId: "UUID - unique event ID"
      eventType: "String - event type name"
      version: "String - schema version"
      timestamp: "ISO 8601 timestamp"
      correlationId: "UUID - request correlation"
      causationId: "UUID - causing event ID"
      source: "String - producing service"

    data: "Actual event payload"

  example:
    metadata:
      eventId: "550e8400-e29b-41d4-a716-446655440000"
      eventType: "OrderCreated"
      version: "1.0"
      timestamp: "2025-01-15T10:30:00Z"
      correlationId: "660e8400-e29b-41d4-a716-446655440001"
      source: "order-service"
    data:
      orderId: "order-123"
      customerId: "customer-456"
      totalAmount:
        amount: 99.99
        currency: "USD"

Schema Evolution

schema_evolution:
  strategies:
    backward_compatible:
      description: "New schema can read old data"
      allowed_changes:
        - "Add optional fields"
        - "Add new enum values at end"
        - "Widen numeric ranges"
      disallowed_changes:
        - "Remove required fields"
        - "Change field types"
        - "Rename fields"

    forward_compatible:
      description: "Old schema can read new data"
      approach: "Ignore unknown fields"

    full_compatible:
      description: "Both directions work"
      best_practice: "Default for most systems"

  versioning:
    header_based:
      example: "version: '1.0'"

    channel_based:
      example: "orders.events.v2"

    semantic:
      format: "major.minor"
      major: "Breaking changes"
      minor: "Backward-compatible additions"

Validation Checklist

asyncapi_validation_checklist:
  structure:
    - "Valid AsyncAPI 3.0.0 syntax"
    - "All required fields present"
    - "No undefined $ref references"
    - "Consistent naming conventions"

  channels:
    - "Clear channel addressing scheme"
    - "Parameters defined for dynamic channels"
    - "All messages referenced exist"

  operations:
    - "Action (send/receive) correctly specified"
    - "Channel reference valid"
    - "Summary and description provided"
    - "Appropriate tags assigned"

  messages:
    - "Unique message names"
    - "Clear title and summary"
    - "Headers schema defined"
    - "Payload schema complete"
    - "Correlation ID specified where needed"

  schemas:
    - "All required fields listed"
    - "Types and formats specified"
    - "Examples provided"
    - "Validation constraints appropriate"

  security:
    - "Security schemes defined for production"
     

  
     
     
     

References

• references/messaging-patterns.md - Event-driven messaging patterns
• references/protocol-bindings.md - Protocol-specific configurations

---

Last Updated: 2025-12-26