# Compatibility ## 1. What is stable The API is versioned by its capabilities. Within a capability URN — `https://ns.ordner.fyi/svc/jmap/files` and `https://ns.ordner.fyi/svc/jmap/photos` — **nothing changes without notice**: every method, argument, property, condition, comparator, facet, error type and limit this guide names keeps its meaning. A change that would break an application is made under a new capability URN. FileNode follows draft-ietf-jmap-filenode, revision 14, under the draft's capability `urn:ietf:params:jmap:filenode`. ## 2. What may change, and how an application stays compatible Additions keep the capability: - new methods, new optional arguments, new filter conditions and comparators, new built-in facets, new members in an answer, new capabilities and new members of a capability's value; - new SetError and method error types, for new kinds of refusal; - higher limits. The core limits are read from the session; an install may set them lower than this guide's numbers, never below what RFC 8620 requires. So an application: - ignores members it does not know, in every answer; - treats an error type it does not know as the HTTP or JMAP class it comes in (a SetError as "not written", a method error as "the method failed"); - reads limits from the session, and the method limits of this guide as the most a call may hold; - names in `using` only the capabilities it uses; - never parses ids, blob ids or states. ## 3. What an application must not rely on - The order of a list the API does not sort: `FileVector/query` sorts by id, `/changes` lists in no promised order, a query without `sort` in no promised order. - The form of ids, blob ids, states, tokens and the `source` id beyond what [Concepts](concepts.md) §3 says. - An access token's contents: it is opaque to the application. - The examples' exact descriptions (`description` of an error is for people); branch on `type`. ## 4. How this guide is kept true Every example is a file the install's tests send to the server and compare with its answer, and every type's [JSON Schema](schema/) is generated from the constants the server checks with; a change that alters either fails the tests before it ships. What this guide says is what the server does.