Versioning

The public contract is the URL path and the JSON shape of the catalog. The version is part of the path. An incompatible change never reaches a client that did not ask for it.

VersionsCopy Anchor Link

apiVersion in the document repeats the path version. schemaVersion tracks the server metadata contract, which can change on its own schedule.

Compatible changesCopy Anchor Link

These do not create a new version:

• adding a field to the catalog or to a server entry;
• adding a new media kind;
• adding a value to a closed list, such as a game type or a Minecraft version;
• adding an optional field to a server's metadata;
• changing the content of an existing entry, such as its description or addresses.

Clients must ignore unknown fields and tolerate unknown values in closed lists. The top level of the catalog accepts additional properties for this reason.

Breaking changesCopy Anchor Link

These create a new version, /v2/:

• removing or renaming a field;
• changing a field's type or meaning;
• changing the URL pattern of media files;
• changing how version is computed, or the lookup order for addresses.

Changing the meaning of a field without changing the version is never acceptable. A client built against the old meaning would misread data silently.

DeprecationCopy Anchor Link

When a new version is available, the old one is announced as deprecated here and in the release notes, with a removal date at least six months away. Clients have that period to migrate. After the date, the old path is removed.