What to do: 'start' creates a new cache and returns its id; 'end' releases the cache identified by the X-Cache-Id header; 'check' reports whether the cache identified by the X-Cache-Id header is still valid, returns statistics about it, and - because checking is itself use - resets its idle timer, so a client can use 'check' to keep a cache it still needs from timing out.

Optional resources (CodeSystem, ValueSet, ConceptMap) to front-load into the cache when mode=start, so they are immediately in scope for subsequent calls that carry the cache-id. Resources may also be added incrementally on later $validate-code / $expand calls (unless the cache is sealed).

Used with mode=start: whether the cache is sealed. A sealed cache (the default) contains only the resources front-loaded in this call and does not grow; an unsealed cache (sealed=false) additionally accumulates resources it sees on subsequent calls, and is what makes incremental population and batch front-loading possible. If omitted, the server's default applies (which SHOULD be true); a client that requires a particular behaviour should set this explicitly and check the sealed value returned in the response.

The server-issued cache identifier, returned by mode=start. The client sends this value as the X-Cache-Id HTTP header on subsequent requests that should use the cache. Absent if no cache was created.

Whether the cache is sealed. A mode=start response always includes it, so the client does not have to assume a default - it states authoritatively whether the cache is fixed at what was front-loaded (sealed=true) or will grow as further resources are seen (sealed=false). A mode=check response includes it for a cache that is still valid, so a client can confirm what it is actually working with. The minimum cardinality is 0 because it is not returned by mode=end, nor by a mode=check that reports valid=false; it is nonetheless mandatory in a mode=start response.

Returned by mode=check: whether the cache named in the X-Cache-Id header is still held by this server. Mandatory in a mode=check response (the minimum cardinality is 0 only because the parameter is not returned by the other modes). Note that a mode=check that finds nothing is still a successful operation - it returns HTTP 200 with valid=false, not an error - so that a client can distinguish a server that reports the cache is gone from a server it could not reach at all. The two call for opposite responses: the first means start a new cache, the second means retry.

Returned by mode=check for a valid cache: how many resources the cache currently holds. Informational - useful for confirming that incremental population of an unsealed cache is working as the client expects.

Returned by mode=check for a valid cache: how many seconds it had been since the cache was last used, measured before this check reset the timer. A client can compare this against the timeout to see how close it came to losing the cache, and adjust how often it checks.

Returned by mode=check for a valid cache, where the server is willing to say: how many seconds a cache may go unused before this server releases it. This lets a client size its checking interval to the server it is actually talking to, rather than guessing at a value it has no other way to discover. A server that has no idle timeout, or does not wish to state one, omits this - a client that gets no value should choose a conservative interval of its own.

Returned by mode=check when valid=false: an OperationOutcome explaining why the cache is not available, with an issue carrying the code cache-id-unknown from http://hl7.org/fhir/tools/CodeSystem/tx-issue-type - the same coded issue a request that used the cache-id would have failed with. Servers SHOULD make the diagnostics say which fate the cache met (never issued by this server, released by the client, or timed out after a period of not being used), since those point at quite different problems.