OpenAPI Markdown Grammar (OMG)

A human-first domain-specific language for API specification

OMG is a Markdown-native language for describing APIs that compiles to standard OpenAPI 3.1 specifications. It's designed to be written by technical product managers and technical writers, understood by developers at a glance, and used as both documentation and a contract testing tool.

Files use the .omg.md extension - because who doesn't love that reaction when reviewing API specs?

Project Status

This project is in the MVP Implementation phase. The core toolchain (parser, compiler, CLI) is functional.

Documentation

• DESIGN.md - Vision, problem statement, and design principles
• SYNTAX.md - Complete syntax reference
• COMPARISON.md - OMG vs OpenAPI comparison
• BEHAVIORS.md - Behavioral conventions and defaults
• TOOLCHAIN.md - Compiler and tooling architecture
• LEGIBILITY.md - Legibility analysis
• Open issues - Roadmap and known work

Repository Structure

├── packages/
│   ├── omg-parser/       # OMG markdown parser
│   ├── omg-compiler/     # OMG to OpenAPI compiler
│   ├── omg-importer/     # OpenAPI to OMG importer
│   ├── omg-linter/       # OMG file linting
│   ├── omg-lsp/          # Language Server Protocol server
│   ├── omg-md-cli/       # Command-line interface
│   ├── omg-mock-server/  # Mock server generator
│   └── omg-vscode/       # VS Code extension
└── *.md                  # Design documentation

Installation via OpenSkills

Install the OpenAPI skill for Claude Code using OpenSkills:

npm i -g openskills
openskills install mcclowes/omg

Installation

npm install -g omg-md-cli

Or use directly with npx:

npx omg-md-cli init my-api

GitHub Action

Build, lint, and check OMG API specs for breaking changes in CI:

steps:
  - uses: actions/checkout@v4
  - uses: mcclowes/omg@v1
    with:
      command: lint
      input: api

The Action supports build, lint, breaking, and changelog commands. It sets up Node.js, runs the OMG CLI, and installs oasdiff when a command needs change detection.

See the GitHub Action guide for every input and more workflow examples.

Getting Started

# Initialize a new OMG project
omg init my-api

# Compile OMG to OpenAPI
omg build api.omg.md -o openapi.yaml

# Import an existing OpenAPI spec to OMG
omg import openapi.yaml -o my-api/

# Start a mock server
omg mock api.omg.md

Example

Create a file get-invoices.omg.md:

---
method: GET
path: /companies/{companyId}/data/invoices
operationId: list-invoices
tags: [Invoices]
---

# List Invoices

Returns a paginated list of invoices for a company.

\`\`\`omg.path
{
  companyId: uuid
}
\`\`\`

\`\`\`omg.query
{
  page: integer? @min(1),
  pageSize: integer? @min(1) @max(100)
}
\`\`\`

\`\`\`omg.response
{
  results: [{
    id: uuid,
    customerName: string,
    totalAmount: decimal,
    status: "draft" | "sent" | "paid"
  }],
  pageNumber: integer,
  totalResults: integer
}
\`\`\`

This compiles to a complete OpenAPI 3.1 specification with proper schemas, error responses, and all the boilerplate handled automatically.

Why OMG?

• ~6x reduction in lines - A typical 30,000 line OpenAPI spec becomes ~5,000 lines in OMG
• Single source of truth - One endpoint per file, not scattered across 5-8 YAML files
• DRY by design - Define errors, pagination, and auth once, reuse everywhere
• Writer-friendly - Technical writers can understand and edit specs
• Full OpenAPI compatibility - Compiles to standard OpenAPI 3.1

License

MIT