Summary

Catch issues early and maintain high-quality documentation with the new EventCatalog Linter

I'm excited to announce the release of the EventCatalog Linter, a comprehensive validation tool that helps you maintain high-quality, consistent documentation for your architecture.

The EventCatalog Linter validates your frontmatter schemas and resource references, catching issues early in your development process—before they impact your team or reach production.

What is the EventCatalog Linter?

The EventCatalog Linter is a comprehensive validation tool designed specifically for EventCatalog projects. It performs two critical types of validation:

1. Documentation Validation - Ensures your frontmatter follows the correct structure and data types
2. Reference Validation - Verifies that all resource references actually exist in your catalog

Think of it as a quality gate for your documentation, similar to how ESLint works for JavaScript code.

What it validates:

• ✅ 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)
• ✅ Referenced services, events, domains, and entities exist
• ✅ Version-specific references are valid
• ✅ Email addresses are properly formatted
• ✅ Owners (users/teams) exist in your catalog

Why you need the EventCatalog Linter

As your EventCatalog grows, maintaining consistency and accuracy becomes increasingly challenging. Without proper validation:

• Broken references can lead to 404 errors and poor user experience
• Invalid frontmatter can cause build failures or display issues
• Inconsistent documentation reduces trust in your architecture documentation
• Manual reviews are time-consuming and error-prone

The EventCatalog Linter solves these problems by automating validation and providing immediate feedback.

Key Features

🎯 Configurable Rules

Create a .eventcatalogrc.js file to customize validation rules for your team's workflow:

// .eventcatalogrc.js
module.exports = {
  rules: {
    // Schema validation rules
    'schema/required-fields': 'error',
    'schema/valid-semver': 'error',
    'schema/valid-email': 'warn',
    
    // Reference validation rules
    'refs/owner-exists': 'error',
    'refs/valid-version-range': 'error',
    
    // Best practice rules
    'best-practices/summary-required': 'warn',
    'best-practices/owner-required': 'error',
  },
  
  // Ignore certain paths
  ignorePatterns: ['**/archived/**', '**/drafts/**'],
  
  // Override rules for specific file patterns
  overrides: [
    {
      files: ['**/experimental/**'],
      rules: {
        'best-practices/owner-required': 'off'
      }
    }
  ]
};

📦 Flexible Version Support

The linter supports various version patterns for resource references:

# Exact versions
version: 1.0.0

# Latest version
version: latest

# Semver ranges
version: ^1.0.0  # Compatible with 1.x.x
version: ~1.2.0  # Compatible with 1.2.x

# X-pattern matching
version: 0.0.x   # Matches 0.0.1, 0.0.5, etc.

🎨 Clear Error Reporting

The linter provides ESLint-inspired output with descriptive rule names:

$ npx @eventcatalog/linter

services/user-service/index.mdx
  ✖ error version: Invalid semantic version format [version] (schema/valid-semver)
  ⚠ warning Summary is required for better documentation [summary] (best-practices/summary-required)

✖ 2 problems

domains/sales/index.mdx
  ✖ error Referenced service "order-service" does not exist [services] (refs/resource-exists)

✖ 1 problem

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

Getting Started

Getting started with the EventCatalog Linter is simple:

1. Run the Linter

Start linting your EventCatalog immediately with npx:

npx @eventcatalog/linter

2. Configure Rules (Optional)

Create a .eventcatalogrc.js file to customize validation:

module.exports = {
  rules: {
    'best-practices/summary-required': 'warn',
    'refs/owner-exists': 'error'
  },
  ignorePatterns: ['**/drafts/**']
};

3. Integrate with CI/CD

Add to your CI/CD pipeline for automated validation:

# 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 --fail-on-warning

Available Rules

The linter includes 10 configurable rules across three categories:

Rule Name	Description	Default
Schema Validation
schema/required-fields	Validates required fields are present	error
schema/valid-type	Validates field types are correct	error
schema/valid-semver	Validates semantic version format	error
schema/valid-email	Validates email address format	error
Reference Validation
refs/owner-exists	Ensures referenced owners exist	error
refs/valid-version-range	Validates version references	error
refs/resource-exists	Ensures referenced resources exist	Always enabled
Best Practices
best-practices/summary-required	Requires summary for documentation	error
best-practices/owner-required	Requires at least one owner	error

Team Workflow Examples

Development Team Configuration

// Relaxed rules for development
module.exports = {
  rules: {
    'best-practices/summary-required': 'warn',
    'best-practices/owner-required': 'warn',
    'refs/owner-exists': 'warn',
  },
  ignorePatterns: ['**/drafts/**', '**/experimental/**']
};

Production Configuration

// Strict rules for production
module.exports = {
  rules: {
    'schema/required-fields': 'error',
    'refs/owner-exists': 'error',
    'best-practices/summary-required': 'error',
    'best-practices/owner-required': 'error',
  }
};

What's Next?

The EventCatalog Linter is the first step in our vision to provide comprehensive quality tools for architecture documentation.

Future releases will include:

• Additional validation rules based on community feedback
• Integration with popular CI/CD platforms
• Custom rule development capabilities
• Performance optimizations for large catalogs

Summary

The EventCatalog Linter brings quality assurance to your architecture documentation. By catching issues early and maintaining consistency, it helps your team build trust in your documentation and reduces time spent on manual reviews.

Key benefits:

• 🔍 Early detection - Catch issues before they reach production
• ⚙️ Configurable - Customize rules for your team's workflow
• 🚀 Fast - Efficiently scan large catalogs
• 🎯 Comprehensive - Validates all EventCatalog resource types
• 🔧 CI/CD ready - Easy integration with existing pipelines

To get started, simply run:

npx @eventcatalog/linter

You can find the complete documentation on our website.

FAQ

Q: Does the linter work with all EventCatalog versions?

A: The linter is designed to work with EventCatalog v2.x and later. It validates all current resource types including domains, services, events, commands, queries, flows, entities, users, and teams.

Q: Can I customize the validation rules?

A: Yes! Create a .eventcatalogrc.js file to configure rule severity levels, ignore patterns, and file-specific overrides. Each rule can be set to error, warn, or off.

Q: How do I integrate with my CI/CD pipeline?

A: Add npx @eventcatalog/linter to your CI/CD scripts. Use the --fail-on-warning flag to treat warnings as errors in production environments.

Q: What if I have draft or experimental content?

A: Use ignore patterns in your configuration to skip validation for specific paths like **/drafts/** or **/experimental/**.

If you have any questions, feature ideas, or would like to discuss the EventCatalog Linter with your team, join our Discord community.