# Version formats and matching

Copy as Markdown[View as Markdown](/docs/development/developer-tools/eventcatalog-linter/reference/versions.md)

***

The linter accepts exactly the version formats EventCatalog accepts, and matches references the same way EventCatalog does when it builds pages and visualisations.

## Resource versions[​](#resource-versions "Direct link to Resource versions")

The `version` field on a resource (`version: 1.0.0`) may be:

| Format           | Examples                               | Notes                                                                                |
| ---------------- | -------------------------------------- | ------------------------------------------------------------------------------------ |
| Semantic version | `1.0.0`, `2.1.3-beta`, `1.0.0+build.5` | Compared as semver                                                                   |
| Number-like      | `1`, `1.2`, `v1`, `V2.1`               | Coerced to semver for comparison (`v1` ≡ `1.0.0`, `1.2` ≡ `1.2.0`)                   |
| `latest`         | `latest`                               | Accepted, but a resource without a comparable version can't satisfy range references |

Values that are none of these — `one`, `1.0.0.0`, `version-1` — are reported by [`schema/valid-semver`](/docs/development/developer-tools/eventcatalog-linter/reference/rules.md#schemavalid-semver).

note

YAML parses `version: 1` as a number, and EventCatalog's schema requires a string. Quote number-like versions: `version: "1"`.

## Version references[​](#version-references "Direct link to Version references")

Wherever frontmatter points at another resource, a `version` may be given:

```
sends:
  - id: OrderCreated            # no version → latest
  - id: OrderCreated
    version: latest             # explicit latest
  - id: OrderCreated
    version: 2.1.0              # exact
  - id: OrderCreated
    version: v2                 # number-like, same as 2.0.0
  - id: OrderCreated
    version: ^2.0.0             # semver range
  - id: OrderCreated
    version: 2.x                # x-range
```

| Reference                                                   | Matches                                                                       |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------- |
| *(omitted)* or `latest`                                     | Any version of the resource — the newest is used                              |
| Exact (`2.1.0`, `V2`)                                       | A version that is the same after coercion (`V2` matches `2`, `v2.0`, `2.0.0`) |
| Semver range (`^2.0.0`, `~2.1.0`, `>=1.5`, `1.0.0 - 2.0.0`) | Any version satisfying the range. `V` is normalised to `v` first              |
| X-range (`2.x`, `0.0.x`)                                    | Any version with that prefix                                                  |

A reference value that is none of these is reported by [`refs/valid-version-range`](/docs/development/developer-tools/eventcatalog-linter/reference/rules.md#refsvalid-version-range) as invalid.

## How matching is decided[​](#how-matching-is-decided "Direct link to How matching is decided")

For a reference with an id and version:

1. Is there any resource of an accepted type with that id? If not → [`refs/resource-exists`](/docs/development/developer-tools/eventcatalog-linter/reference/rules.md#refsresource-exists), regardless of the version.
2. Is the version omitted or `latest`? → match.
3. Does any existing version equal the reference exactly, or after coercion? → match.
4. Does any existing version satisfy the reference as a semver range or x-range? → match.
5. Otherwise → [`refs/valid-version-range`](/docs/development/developer-tools/eventcatalog-linter/reference/rules.md#refsvalid-version-range), listing the existing versions newest first.

A resource with no `version` in its frontmatter is indexed as `latest`. It matches references without a version, but not range references (`^1.0.0`), because `latest` has no numeric value to compare.

## External dependencies[​](#external-dependencies "Direct link to External dependencies")

Resources declared in `eventcatalog.config.js` `dependencies` take part in matching too. A dependency without a `version` matches any reference to its id; with a `version`, the rules above apply.

## Ordering[​](#ordering "Direct link to Ordering")

When the linter lists "available versions" it sorts newest first using semver comparison, so `V3` sorts above `2` above `v1`. If any version can't be compared numerically, the list falls back to reverse alphabetical order — the same rule EventCatalog uses to pick the latest version of a resource.

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

* [Versioning resources](/docs/development/guides/versioning-resources.md)
* [Reference external catalogs](/docs/development/developer-tools/eventcatalog-linter/how-to/reference-external-catalogs.md)