Which fields are your consumers actually using?

EventCatalog 3.24.0 adds a new optional capability: field-level usage tracking. You can now document which specific fields each consuming service depends on, and see that information surfaced directly on the message page.

Going one level deeper

EventCatalog already tells you which services consume a message (example below).

See demo

Field Usage lets you go a level further. When consumers declare which fields they use, the message page gains a dedicated Field Usage view showing every schema property alongside the services that depend on it.

Field usage page - See which fields your consumer uses

Field usage is optional, and for those teams that want to document how their consumers are using the messages they consume. You can track all the fields, just key fields or no fields, it's up to you.

How to declare field usage

Add a fields array to any entry in the receives pointer of a service or domain:

In this example we declare that the NotificationService consumes a message called PaymentProcessed and they fields it consumes (or are important to it) are the orderId, amount currency and customerEmail.

services/NotificationService/index.mdx

---
id: NotificationService
name: Notification Service
receives:
  - id: PaymentProcessed
    version: 1.0.0
    fields:
      - orderId
      - amount
      - currency
      - customerEmail
---

Once at least one service has declared fields for a message, a Field Usage link appears in that message's sidebar under "API & Contracts."

What the Field Usage page shows

The page renders a table of every schema property with four columns: field name, type, description, and which consumers depend on it. Field metadata is extracted automatically from the message's schema. JSON Schema, Avro, and Protobuf are all supported.

A "Consumed only" filter lets you hide fields that no service has declared, so you can focus on the populated parts of the table.

If a consumer declares a field name that does not exist in the schema, a "Fields not found in schema" warning section flags it. This catches typos and declarations that have drifted out of sync with the actual schema.

A quick example

Say three services consume PaymentProcessed and their declarations look like this:

Field	NotificationService	AnalyticsService	FraudDetectionService
orderId	yes	yes	yes
amount	yes	yes	yes
currency	yes		yes
customerEmail	yes
processorRef			yes
metadata		yes

That table is generated automatically from the fields declarations in each service's frontmatter.

SDK support

If you manage catalog content programmatically, the EventCatalog SDK accepts field declarations in addEventToService:

import { addEventToService } from '@eventcatalog/sdk';

await addEventToService('ShippingService', 'receives', {
  id: 'PaymentProcessed',
  version: '1.0.0',
  fields: ['orderId', 'amount', 'currency'],
});

Getting started

Upgrade to EventCatalog Core 3.24.0. Add a fields array to a receives entry in any service frontmatter. The Field Usage page appears automatically.

Existing catalogs are unaffected. The fields array is optional, and nothing changes for services that don't use it.

Summary

Field Usage adds a new depth of documentation for teams that want it. EventCatalog already shows who consumes a message. Now it can also show what they consume.

We're also exploring ways to automate this, for example, using AI to analyze consumer code and automatically update field-level dependencies in your catalog. If that's something you'd find useful, we'd love to hear from you on Discord.

Read the full Field Usage documentation for details. Questions and feedback are welcome on Discord or GitHub.