Packets

A packet is a typed schema that describes the data traveling along an edge. Every edge optionally declares a packet type in its delivery policy — the runtime uses this to validate the shape of data passing between nodes and to generate documentation in Studio.

Native packets

Define packets directly in your FlowDSL document under components.packets. Each packet is a JSON Schema Draft-07 object:

components:
  packets:
    OrderPayload:
      type: object
      properties:
        orderId:
          type: string
          description: Unique order identifier
        customerId:
          type: string
        items:
          type: array
          items:
            type: object
            properties:
              sku: { type: string }
              qty: { type: integer, minimum: 1 }
              price: { type: number }
            required: [sku, qty, price]
        total:
          type: number
          minimum: 0
        currency:
          type: string
          enum: [USD, EUR, GBP]
      required: [orderId, customerId, items, total, currency]

    PaymentResult:
      type: object
      properties:
        orderId: { type: string }
        chargeId: { type: string }
        status:
          type: string
          enum: [succeeded, failed, pending]
        amount: { type: number }
      required: [orderId, chargeId, status]

Reference a packet from an edge:

edges:
  - from: ValidateOrder
    to: ChargePayment
    delivery:
      mode: durable
      packet: OrderPayload    # References components.packets.OrderPayload

AsyncAPI-referenced packets

When you have an existing AsyncAPI document, reference its message schemas directly instead of duplicating them:

# In your FlowDSL document
asyncapi: "./events.asyncapi.yaml"

edges:
  - from: OrderReceived
    to: ProcessOrder
    delivery:
      mode: durable
      packet: "asyncapi#/components/messages/OrderPlaced"

The runtime resolves the reference by loading the AsyncAPI document and extracting the message schema at the given JSON Pointer path. The packet is validated at runtime against the resolved schema.

Packet naming

Validation

The runtime validates packets at each edge:

• At startup: Verifies that all referenced packet names exist in components.packets or can be resolved from the referenced AsyncAPI document.
• At runtime: Validates each packet against its JSON Schema before delivery. Invalid packets are rejected and moved to the dead letter queue.

When to define packets

Define a packet when:

• Multiple edges share the same schema (reuse the name)
• The schema is complex enough to benefit from a named definition
• You want Studio to show the packet structure in the NodeContractCard

Omit the packet field when:

• The edge is using direct mode between two nodes you control and schema validation is handled inside the node
• You are early in development and the schema is still evolving

Summary

• Packets are JSON Schema Draft-07 objects defined under components.packets.
• Reference them by name on edge delivery policies.
• Or reference AsyncAPI messages using asyncapi#/components/messages/MessageName.
• PascalCase naming convention for all packet names.

Next steps

• Edges — how packets are used on edges
• Connecting AsyncAPI — referencing AsyncAPI schemas
• Components reference — full components section reference