Export Formats Overview

The Hermodr.Schema package can export event schemas in multiple formats, each serving different purposes.

Available Export Formats

Format	Use Case	Machine-Readable	Human-Readable	Tooling Support
JSON	Schema registries, validation libraries, API gateways	✅ Excellent	⚠️ Moderate	✅ Excellent
YAML	Documentation, version control, configuration files	✅ Good	✅ Excellent	✅ Good
AsyncAPI	Complete async API specifications, broker documentation	✅ Excellent	✅ Excellent	✅ Excellent
OpenAPI 3.1	Webhook contracts for REST-centric tooling (Swagger UI, Kiota)	✅ Excellent	✅ Excellent	✅ Excellent

---

JSON Export

Best for: Schema registries, automated validation, tooling integration

When to Use JSON

• ✅ Integrating with schema registries (e.g., Schema Registry, custom solutions)
• ✅ Using JSON Schema validation libraries
• ✅ API gateways that consume JSON Schema
• ✅ Automated CI/CD validation pipelines
• ✅ Programmatic schema comparison

Example

{
  "type": "order.placed",
  "version": "1.0",
  "contentType": "application/json",
  "description": "Raised when a customer places an order",
  "properties": [
    {
      "name": "OrderId",
      "dataType": "guid",
      "required": true
    },
    {
      "name": "Amount",
      "dataType": "money",
      "required": true,
      "constraints": {
        "min": 0.01,
        "max": 1000000.0
      }
    }
  ]
}

Learn More

→ Export as JSON

---

YAML Export

Best for: Human-readable documentation, version control diffs, configuration

When to Use YAML

• ✅ Including in documentation sites (GitBook, Docusaurus, etc.)
• ✅ Storing in version control (cleaner diffs than JSON)
• ✅ Reviewing schema changes in pull requests
• ✅ Configuration files for external tools
• ✅ Sharing schemas with non-technical stakeholders

Example

type: order.placed
version: '1.0'
contentType: application/json
description: Raised when a customer places an order
properties:
  - name: OrderId
    dataType: guid
    required: true
  - name: Amount
    dataType: money
    required: true
    constraints:
      min: 0.01
      max: 1000000.0

Learn More

→ Export as YAML

---

AsyncAPI Export

Best for: Complete API specifications, documentation generation, consumer onboarding

When to Use AsyncAPI

• ✅ Publishing complete API specifications for consumers
• ✅ Generating interactive documentation (e.g., AsyncAPI Studio, ReDoc)
• ✅ Describing channels, bindings, and security requirements
• ✅ Integrating with API governance platforms
• ✅ Creating mock servers and test environments

What AsyncAPI Provides

AsyncAPI is to async APIs what OpenAPI is to REST APIs. It describes:

• Event schemas — Structure of messages
• Channels — Where messages are published/subscribed
• Bindings — Protocol-specific details (AMQP, Kafka, WebSockets, etc.)
• Security — Authentication and authorization requirements
• Servers — Broker endpoints and configurations

Example

asyncapi: 2.6.0
info:
  title: Order Service API
  version: 1.0.0
  description: Order management event API

channels:
  orders/placed:
    publish:
      operationId: publishOrderPlaced
      message:
        $ref: '#/components/messages/OrderPlaced'

components:
  messages:
    OrderPlaced:
      contentType: application/json
      payload:
        type: object
        properties:
          OrderId:
            type: string
            format: uuid
          Amount:
            type: number
            minimum: 0.01
            maximum: 1000000.0

Learn More

→ Export as AsyncAPI

---

OpenAPI 3.1 Webhook Export

Best for: Webhook contracts consumable by REST-centric tooling (Swagger UI, Stoplight, Postman, Kiota code generation)

When to use OpenAPI 3.1

• ✅ Publishing event contracts to teams already standardised on OpenAPI
• ✅ Generating typed clients with Kiota or OpenAPI Generator
• ✅ Surfacing webhooks in Swagger UI / Stoplight
• ✅ Contract-first workflows where the downstream stack is HTTP-centric

Learn More

→ Export as OpenAPI 3.1

---

CLI Export Tool

A dotnet global tool that produces AsyncAPI / OpenAPI documents without a running host — ideal for CI pipelines and contract-first workflows.

→ CLI Export Tool

---

Format Selection Guide

I need to... → Use...

Scenario	Recommended Format
Validate events programmatically	JSON
Store in a schema registry	JSON
Include in documentation	YAML or AsyncAPI
Review changes in Git	YAML
Publish API specification for consumers	AsyncAPI
Generate interactive docs	AsyncAPI
Configure API gateway	JSON
Share with business stakeholders	YAML

---

Exporting Multiple Formats

You can export the same schema in multiple formats for different audiences:

var schema = EventSchema.FromDataType<OrderPlacedData>();

// JSON for schema registry
var jsonWriter = new EventSchemaJsonWriter();
await jsonWriter.WriteToAsync(jsonStream, schema);

// YAML for documentation
var yamlWriter = new EventSchemaYamlWriter();
await yamlWriter.WriteToAsync(yamlStream, schema);

// AsyncAPI for consumer portal
var asyncApiWriter = new EventSchemaAsyncApiWriter(AsyncApiFormat.Yaml);
await asyncApiWriter.WriteToAsync(asyncApiStream, schema);

---

Related Pages

• Fluent Builder
• From Annotations
• Export as JSON
• Export as YAML
• Export as AsyncAPI
• Export as OpenAPI 3.1
• CLI Export Tool