# Ownership and cross-catalog references

Copy as Markdown[View as Markdown](/docs/federation/explanation/ownership-and-references.md)

***

`EventCatalog Enterprise Feature`

Federation separates **owning a resource** from **referring to a resource**.

A catalog owns a resource when it contains the resource documentation. Other catalogs can use normal EventCatalog relationship pointers to refer to that ID without copying its definition.

## One resource, one owner[​](#one-resource-one-owner "Direct link to One resource, one owner")

Resource IDs are organization-wide in a federated view.

If Payments owns `payment-captured`, another catalog should not create a second `payment-captured` event as a placeholder. It should point to the owner's ID.

The same owner should document every version of an ID. Splitting version `1.0.0` and version `2.0.0` across catalogs is still multiple ownership.

## Relationships stay in normal frontmatter[​](#relationships-stay-in-normal-frontmatter "Direct link to Relationships stay in normal frontmatter")

Teams keep authoring `sends`, `receives`, domain membership, flow steps, and other EventCatalog relationships as they do in a standalone catalog.

For example, an Orders service can receive an event owned by Payments:

```
---
id: order-service
name: Order Service
version: 1.0.0
receives:
  - id: payment-captured
    version: 1.0.0
---
```

The Orders catalog does not need a local event file for `payment-captured`. When both catalogs participate in the central view, Federation connects the relationship to the Payments resource.

## Central resources participate too[​](#central-resources-participate-too "Direct link to Central resources participate too")

The central catalog can own local resources. Those resources are included when Federation validates ownership and resolves relationships from remote catalogs.

This allows organization-wide flows and architecture decisions to refer to team-owned services and messages without copying them into the central repository.

## How versions resolve[​](#how-versions-resolve "Direct link to How versions resolve")

Relationship pointers can select:

| Pointer                         | Resolution                                     |
| ------------------------------- | ---------------------------------------------- |
| No version                      | Highest available version                      |
| `latest`                        | Highest available version                      |
| Exact version such as `1.2.0`   | That version only                              |
| Semantic range such as `^1.2.0` | Highest available version satisfying the range |

If the ID exists but the requested version cannot be selected, Federation reports `federation/unresolved-version` with the requested and available versions.

## Missing resource and unresolved version are different[​](#missing-resource-and-unresolved-version-are-different "Direct link to Missing resource and unresolved version are different")

* **Missing resource** means no participating catalog documents the target ID.
* **Unresolved version** means an owner exists, but it does not publish a matching version.

Both are warnings by default so organizations can onboard catalogs gradually. They can be promoted to errors with [Federation rules](/docs/federation/how-to/configure-validation-rules.md).

## Ambiguous ownership blocks by default[​](#ambiguous-ownership-blocks-by-default "Direct link to Ambiguous ownership blocks by default")

Federation reports structural errors when:

* Several catalogs own the same resource ID
* The same ID is documented as different resource types
* A relationship expects one resource type but finds another
* Catalogs provide contradictory facets for one resource

These problems have no unambiguous organization-wide interpretation, so their rules default to `error`.

## Ownership conventions to agree on[​](#ownership-conventions-to-agree-on "Direct link to Ownership conventions to agree on")

Before onboarding many catalogs, agree that:

* Every resource ID has one owning catalog
* The owner keeps all versions of the resource
* Consumers point to the owner rather than creating placeholders
* Shared teams and users have one source of truth
* Central documentation uses unique IDs for resources it owns
* Teams coordinate any intentionally shared asset or component paths

## Related guides[​](#related-guides "Direct link to Related guides")

* [Configure validation rules](/docs/federation/how-to/configure-validation-rules.md)
* [Diagnostic rule reference](/docs/federation/reference/diagnostic-rules.md)
* [Troubleshooting ownership problems](/docs/federation/reference/troubleshooting.md#ownership-and-type-errors)