Versioning policy

Ava's API versioning and change-control commitment to developers.

This is Ava's commitment to developers integrating with the Ava EMR FHIR R4 API: how the API is versioned, what kinds of changes we make, how you find out about them, and how long you have to adapt.

What you can rely on

Pinned standards. FHIR R4 (4.0.1) with SMART App Launch and SMART Backend Services 2.2. Fourteen resources advertise validated CA Core+ profiles; Media is supported as ordinary FHIR R4. Terminology releases (SNOMED CT CA, PHCVS) and UCUM units are pinned to explicit versions and only move deliberately, with conformance re-validated before a new version is advertised.
A machine-readable contract. The CapabilityStatement at {fhir_base_url}/metadata and the SMART discovery document at {issuer}/.well-known/smart-configuration are generated from the same internal registry that enforces authorization. If something is advertised there, it is implemented and tested; if it is not advertised, do not depend on it.
Version in the URL. The FHIR major version is part of the base path (/fhir/r4/…). A future FHIR version would be mounted side by side under its own path. The meaning of an existing path never changes in place.

Non-breaking changes

These ship continuously, announced in the changelog, and require no action:

New resource types, interactions, search parameters, or scopes.
New optional elements or extensions in returned resources — write clients defensively and ignore elements you do not recognize.
Newly advertised profiles, once they pass automated validation.
Stricter rejection of requests that were already invalid under the documented contract.

Breaking changes

Removing or renaming anything that has shipped, or changing the type, meaning, cardinality, or terminology binding of a published element, is a breaking change. When one is unavoidable:

A deprecation notice is published in the changelog and emailed to the registered owner of every application whose granted scopes touch the affected surface.
Affected endpoints serve standard Deprecation and Sunset HTTP headers for the entire window, so you can detect impact programmatically.
You get a minimum of 6 months between notice and removal, and 12 months when the shape or meaning of returned data changes.
Before removal we check for remaining traffic and contact any active integrations directly.

Sandbox first

Every API change reaches the synthetic sandbox before production — at least one release cycle earlier — so you can validate your integration against upcoming behavior before your users see it.

Staying informed

Watch the changelog.
Keep your application's contact information current; deprecation notices go to the registered owner.
Re-read the CapabilityStatement and SMART discovery document periodically — they are always the authoritative description of the current API surface.

Questions about an announced change or a migration path: contact the Ava integration team through your organization's portal workspace.