# Federation configuration reference

Copy as Markdown[View as Markdown](/docs/federation/reference/configuration.md)

***

`EventCatalog Enterprise Feature`

Configure Federation under the `federation` key in the central catalog's `eventcatalog.config.js`.

eventcatalog.config.js

```
export default {
  federation: {
    rules: {
      'federation/missing-resource': 'error',
    },
    sources: [
      {
        id: 'acme/payments',
        source: 'github:acme/payments-catalog',
        path: 'catalog',
        ref: 'main',
      },
    ],
  },
};
```

## `federation`[​](#federation "Direct link to federation")

| Field     | Type                                            | Required | Description                                                                                          |
| --------- | ----------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `sources` | `FederationSourceConfig[]`                      | Yes      | Catalogs included in the organization view. Use an empty array to remove previous Federation output. |
| `rules`   | `Record<FederationRuleId, FederationRuleLevel>` | No       | Overrides diagnostic levels. Unconfigured rules keep their defaults.                                 |

## Sources[​](#sources "Direct link to Sources")

Each entry in `federation.sources` selects one EventCatalog project.

| Field    | Type     | Required | Default | Description                                                                                        |
| -------- | -------- | -------- | ------- | -------------------------------------------------------------------------------------------------- |
| `id`     | `string` | Yes      |         | Stable source identity used by indexes, ownership, generated paths, diagnostics, and the lockfile. |
| `source` | `string` | Yes      |         | Source locator. Supported protocols are `github:` and `file:`.                                     |
| `path`   | `string` | No       | `.`     | Catalog directory within the selected repository or filesystem source.                             |
| `ref`    | `string` | No       | `main`  | GitHub branch, tag, or commit. Not supported by filesystem sources.                                |

### Source IDs[​](#source-ids "Direct link to Source IDs")

Every source requires a non-empty `id`, and the same ID cannot be configured more than once.

Use stable organization-oriented IDs:

```
{
  id: 'acme/payments',
  source: 'github:acme/payments-catalog',
}
```

Changing the repository or directory does not require changing the ID. Keeping it stable preserves understandable provenance and generated paths.

If a GitHub source publishes `catalog.index.json`, its `source` value must exactly match the configured `id`.

### GitHub locator[​](#github-locator "Direct link to GitHub locator")

Syntax:

```
github:<owner>/<repository>
```

Example at the repository root:

```
{
  id: 'acme/payments',
  source: 'github:acme/payments-catalog',
}
```

Example in a monorepo:

```
{
  id: 'acme/payments',
  source: 'github:acme/architecture-catalogs',
  path: 'catalogs/payments',
  ref: 'production',
}
```

GitHub authentication is read from `EVENTCATALOG_GITHUB_TOKEN`, then `GITHUB_TOKEN` as a fallback.

### Filesystem locator[​](#filesystem-locator "Direct link to Filesystem locator")

Syntax:

```
file:<path-from-central-catalog>
```

Example:

```
{
  id: 'acme/payments',
  source: 'file:../payments-catalog',
}
```

Example with a catalog inside the selected source root:

```
{
  id: 'acme/payments',
  source: 'file:../architecture-catalogs',
  path: 'payments',
}
```

Filesystem sources reject `ref`. Paths must remain within the selected source root, including after symbolic links are resolved.

## Rules[​](#rules "Direct link to Rules")

Every rule accepts:

```
'off' | 'warn' | 'error'
```

| Rule ID                            | Default |
| ---------------------------------- | ------- |
| `federation/duplicate-source`      | `error` |
| `federation/type-collision`        | `error` |
| `federation/pointer-type-mismatch` | `error` |
| `federation/facet-disagreement`    | `error` |
| `federation/asset-collision`       | `warn`  |
| `federation/missing-resource`      | `warn`  |
| `federation/unresolved-version`    | `warn`  |

Example:

eventcatalog.config.js

```
export default {
  federation: {
    rules: {
      'federation/duplicate-source': 'error',
      'federation/missing-resource': 'error',
      'federation/asset-collision': 'off',
    },
    sources: [/* ... */],
  },
};
```

Unknown rule IDs and values other than `off`, `warn`, or `error` cause a configuration error.

See the [diagnostic rule reference](/docs/federation/reference/diagnostic-rules.md) for triggers and output attributes.

## Complete conditional source example[​](#complete-conditional-source-example "Direct link to Complete conditional source example")

This example uses local sibling catalogs during development and GitHub in shared environments:

eventcatalog.config.js

```
const source =
  process.env.EVENTCATALOG_FEDERATION_LOCAL === 'true'
    ? 'file:..'
    : 'github:acme/architecture-catalogs';

export default {
  federation: {
    rules: {
      'federation/unresolved-version': 'error',
    },
    sources: [
      {
        id: 'acme/orders',
        source,
        path: 'orders',
      },
      {
        id: 'acme/payments',
        source,
        path: 'payments',
      },
    ],
  },
};
```