EventCatalog Linter
The EventCatalog Linter is a command-line tool that checks your catalog for the mistakes EventCatalog itself would otherwise ignore or only surface at build time: a service that sends an event that doesn't exist, a typo like owner: instead of owners:, a schemaPath that points at nothing, or a file saved in a folder EventCatalog never reads.
Run it locally while you write documentation, or in CI so every pull request is checked.
npx @eventcatalog/linter
services/order-service/index.mdx
6:1 ✖ error Unknown property "owner". Did you mean "owners"? [owner] (schema/unknown-field)
9:5 ✖ error Referenced event/command/query "OrderCreatd" does not exist. Did you mean "OrderCreated"? [sends[0]] (refs/resource-exists)
14:1 ⚠ warning Resource should have a markdown description (body content) beyond just frontmatter [description] (best-practices/description-required)
✖ 3 problems (2 errors, 1 warning) in 1 file
178 files checked
What it checks
| Area | Examples |
|---|---|
| Frontmatter schemas | Required fields, field types, version formats, unknown or misspelled keys |
| References | Owners, messages, services, domains, channels, containers, flow steps and entity relationships point at resources (and versions) that exist |
| Files | schemaPath, schemas[], specifications, data product contracts and public/ icons resolve to real files |
| Catalog structure | Duplicate ids, markdown files in places EventCatalog won't load |
| Documentation quality | Summaries, owners, body content and message schemas are present |
| Versioning | References to deprecated resources |
Every finding comes with a line:column position, the rule that produced it, and — where the linter can work it out — a suggestion for the fix.
Where to go next
- Set up the linter — a guided walk-through from the first run to a CI check. Start here if you haven't used the linter before.
- How-to guides — recipes for specific jobs: configure rules, run in CI, allow custom frontmatter, reference resources from other catalogs, fix common problems.
- Reference — every CLI option, the configuration file, all rules with their messages and options, version formats and the files the linter scans.
What's new
@eventcatalog/linter@1.1.17The latest release focuses on catching the mistakes people actually make and pointing at exactly where they are:
- Line and column numbers on every finding, so terminals and editors can jump straight to the problem.
- Unknown frontmatter keys are flagged with "did you mean" suggestions (
schema/unknown-field). EventCatalog fails the build on these; the linter now catches them first. - Misplaced files —
events/OrderCreated.mdxinstead ofevents/OrderCreated/index.mdx,event/instead ofevents/, users saved as folders — are reported with the intended location (structure/unrecognised-file). - Broken file references —
schemaPath, specifications, contracts and icons that don't exist (refs/file-exists). - Clearer reference errors: "this resource doesn't exist — did you mean
OrderCreated?" is now distinct from "this resource exists, but not at version2.1.0— available:2.0.0,1.0.0". - Version formats match EventCatalog:
1,1.2,v1andV2are accepted everywhere EventCatalog accepts them. eventcatalog-linter --initscaffolds a fully commented config;--quiet,--max-warningsand--no-colorwere added; progress output stays out of CI logs; the summary reports how many files were actually checked.
Read the rules reference for the full list, or the original announcement for the background.
Supported resources
The linter understands every resource type EventCatalog does: domains and subdomains, systems, services, events, commands, queries, channels, flows, entities, agents, containers, data products, diagrams, ADRs, users and teams — including versioned copies under versioned/ and content pulled in through federation. See Supported resources for the exact folders and file names it scans.
Issues?
If you have any issues or feedback, please open an issue on GitHub or join our Discord server.