Skip to main content

EventCatalog Linter

A comprehensive linter for EventCatalog that validates frontmatter schemas and resource references to ensure your architecture documentation is correct and consistent.

The EventCatalog Linter helps you catch issues early in your development process, ensuring your documentation maintains high quality and accuracy across all your EventCatalog resources.

Use cases​

  • Quality Assurance: Ensure your documentation is correct and consistent
  • CI/CD: Integrate the linter into your CI/CD pipeline to catch issues early
  • Documentation: Run the linter regularly as part of your development workflow
  • Version Consistency: Use consistent version patterns across your EventCatalog resources

Features​

  • 📋 Schema Validation: Validates all resource frontmatter against defined schemas using Zod
  • 🔗 Reference Validation: Ensures all referenced resources (services, events, domains, etc.) actually exist
  • 📦 Semver Version Support: Supports semantic versions, ranges (^1.0.0, ~1.2.0), x-patterns (0.0.x), and latest
  • 🎯 Comprehensive Coverage: Supports all EventCatalog resource types
  • ⚡ Fast Performance: Efficiently scans large catalogs
  • 🎨 ESLint-Inspired Output: Clean, file-grouped error reporting with severity levels
  • ⚠️ Warnings Support: Distinguish between errors and warnings with --fail-on-warning option

Supported Resource Types​

The linter validates all EventCatalog resource types:

  • 🏢 Domains (including subdomains)
  • ⚙️ Services
  • 📨 Events
  • 📤 Commands
  • ❓ Queries
  • 📡 Channels
  • 🔄 Flows
  • 📊 Entities
  • 👤 Users
  • 👥 Teams

Installation​

Global Installation​

npm install -g @eventcatalog/linter
npx @eventcatalog/linter

Add to your project​

npm install --save-dev @eventcatalog/linter

Usage​

Basic Usage​

Run the linter in your EventCatalog directory:

// Lint current directory
eventcatalog-linter

// Lint specific directory
eventcatalog-linter ./my-eventcatalog

// Verbose output with detailed information
eventcatalog-linter --verbose

// Show help
eventcatalog-linter --help

CLI Options​

Usage: eventcatalog-linter [options] [directory]

Arguments:
  directory              EventCatalog directory to lint (default: ".")

Options:
  -V, --version          output the version number
  -v, --verbose          Show verbose output (default: false)
  --fail-on-warning      Exit with non-zero code on warnings (default: false)
  -h, --help             display help for command

Package.json Integration​

Add to your package.json scripts:

{
  "scripts": {
    "lint:eventcatalog": "eventcatalog-linter",
    "lint:eventcatalog:verbose": "eventcatalog-linter --verbose"
  }
}

What It Validates​

Frontmatter Schema Validation​

  • ✅ Required fields are present (id, name, version)
  • ✅ Field types are correct (strings, arrays, objects)
  • ✅ Semantic versions follow proper format (1.0.0, 2.1.3-beta)
  • ✅ Version patterns supported (latest, ^1.0.0, ~1.2.0, 0.0.x)
  • ✅ URLs are valid format
  • ✅ Email addresses are valid format
  • ✅ Enum values are from allowed lists
  • ✅ Nested object structures are correct

Reference Validation​

  • ✅ Services referenced in domains exist
  • ✅ Events/Commands/Queries referenced in services exist
  • ✅ Entities referenced in domains/services exist
  • ✅ Users/Teams referenced as owners exist
  • ✅ Flow steps reference existing services/messages
  • ✅ Entity properties reference existing entities
  • ✅ Version-specific references are valid

Example Output​

✅ Success Output​

$ eventcatalog-linter

✔ No problems found!

  42 files checked

❌ Error Output​

$ eventcatalog-linter

services/user-service/index.mdx
  ✖ error version: Invalid semantic version format [version] (@eventcatalog/schema-validation)
  ⚠ warning summary should be provided for better documentation [summary] (@eventcatalog/schema-validation)

✖ 2 problems

domains/sales/index.mdx
  ✖ error Referenced service "order-service" does not exist [services] (@eventcatalog/invalid-reference)

✖ 1 problem

flows/user-registration/index.mdx
  ✖ error Referenced service "notification-service" (version: 2.0.0) does not exist [steps[1].service] (@eventcatalog/invalid-reference)

✖ 1 problem

✖ 4 problems (3 errors, 1 warning)
  3 files checked

Version Pattern Support​

The linter supports flexible version patterns for resource references:

Exact Versions​

sends:
  - id: user-created
    version: 1.0.0 # Exact semantic version

Latest Version​

sends:
  - id: user-created
    version: latest # Always use the latest available version

Semver Ranges​

sends:
  - id: user-created
    version: ^1.0.0 # Compatible with 1.x.x (1.0.0, 1.2.3, but not 2.0.0)
  - id: user-updated
    version: ~1.2.0 # Compatible with 1.2.x (1.2.0, 1.2.5, but not 1.3.0)

X-Pattern Matching​

sends:
  - id: user-created
    version: 0.0.x # Matches 0.0.1, 0.0.5, 0.0.12, etc.
  - id: order-placed
    version: 1.x # Matches 1.0.0, 1.5.3, 1.99.0, etc.

CI/CD Integration​

GitHub Actions​

name: EventCatalog Lint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npx @eventcatalog/linter

GitLab CI​

eventcatalog-lint:
  stage: test
  image: node:18
  script:
    - npx @eventcatalog/linter

Error Codes​

The linter provides descriptive error codes to help identify and fix issues quickly:

Schema Validation Errors​

  • @eventcatalog/required-field - Required field is missing
  • @eventcatalog/invalid-type - Field has wrong data type
  • @eventcatalog/schema-validation - General schema validation error
  • @eventcatalog/schema - Schema-related validation error

Reference Validation Errors​

  • @eventcatalog/invalid-reference - Referenced resource doesn't exist

Parse Errors​

  • @eventcatalog/parse-error - YAML/frontmatter parsing error

Warnings Support​

The linter distinguishes between errors (critical issues) and warnings (suggestions for improvement):

  • Errors: Critical issues that must be fixed
  • Warnings: Suggestions for better documentation

Use --fail-on-warning to treat warnings as errors in CI/CD pipelines:

# Exit with error code if warnings are found
eventcatalog-linter --fail-on-warning

Common Validation Examples​

Valid Frontmatter Examples​

Service​

---
id: user-service
name: User Service
version: 2.1.0
summary: Manages user accounts and authentication
owners:
  - platform-team
  - john-doe
sends:
  - id: user-created
    version: 1.0.0
  - id: user-updated
receives:
  - id: create-user
  - id: update-user
entities:
  - id: user
repository:
  language: TypeScript
  url: https://github.com/company/user-service
---

Event​

---
id: user-created
name: User Created
version: 1.0.0
summary: Triggered when a new user account is created
owners:
  - platform-team
sidebar:
  badge: POST
  label: User Events
draft: false
deprecated: false
---

Common Validation Errors​

❌ Missing Required Fields​

---
# Missing 'id' field
name: User Service
version: 1.0.0
---

❌ Invalid Semantic Version​

---
id: user-service
name: User Service
version: v1.0 # Should be 1.0.0
---

❌ Invalid Reference​

---
id: sales-domain
name: Sales Domain
version: 1.0.0
services:
  - id: non-existent-service # Service doesn't exist
---

Best Practices​

  1. Run in CI/CD: Integrate the linter into your CI/CD pipeline to catch issues early
  2. Use --fail-on-warning: Consider treating warnings as errors in production environments
  3. Regular Validation: Run the linter regularly as part of your development workflow
  4. Fix Issues Promptly: Address validation errors immediately to maintain documentation quality
  5. Version Consistency: Use consistent version patterns across your EventCatalog resources

Issues?​

If you have any issues or feedback, please let us know by opening an issue on GitHub or joining our Discord server.