> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/aicr/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/aicr/_mcp/server.

# Deprecations

Every active AICR deprecation, the replacement, and the release that removes it.
An entry stays on this page until the removal ships, then moves to
[Removed](#removed) for one further release so an operator upgrading across
several versions can still find out what happened.

The policy behind this page — what counts as a breaking change on each surface,
and the notice a removal owes — is in
[`RELEASE.md`](https://github.com/NVIDIA/aicr/blob/main/RELEASE.md#deprecation-policy).

## How you will find out

You do not have to read this page to be warned. Every deprecation is announced
on the affected surface through that surface's own channel — which is not always
a runtime warning, because the most useful moment to be told differs by surface:

| Surface | What you see | When |
|---|---|---|
| CLI | A warning on stderr naming the replacement and the removal release | At run time |
| REST | A `Deprecation` header ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745.html)) with the deprecation date, a `Sunset` header ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html)) with the removal date, a `Link` with `rel="deprecation"`, and `deprecated: true` on the operation in the OpenAPI spec | On every response |
| Go SDK | A `// Deprecated:` godoc marker, which `staticcheck` reports as `SA1019` | At **build** time |
| Bundles and artifacts | A loader warning naming the file and the release that stops reading it | When the artifact is read |

The Go SDK is deliberately build-time rather than run-time: the compiler and
your linter can tell you before you ship, which beats a log line from
production.

That announcement is the contract. If something was removed without one, that is
a bug worth [filing](https://github.com/NVIDIA/aicr/issues/new/choose).

## Active

### Alpha artifact `apiVersion` values

**Surface:** bundle and artifact schemas ·
**Deprecated in:** v0.22 · **Removed in:** v0.23

Every artifact AICR generates carried an alpha `apiVersion` — `aicr.run/v1alpha2`
for most kinds, `aicr.run/v1alpha3` for profile-bearing recipes. Those values are
being replaced by maturity-appropriate targets, per
[ADR-022](https://github.com/NVIDIA/aicr/blob/main/docs/design/022-artifact-maturity-and-deprecation.md).

| Kind | Retiring | Replacement |
|---|---|---|
| `Snapshot`, default `RecipeResult`, `RecipeCriteria`, `BundleProvenance` | `aicr.run/v1alpha2` | `aicr.run/v1` |
| `AICRConfig`, catalog `RecipeMetadata`, `RecipeMixin`, `ComponentRegistry` | `aicr.run/v1alpha2` | `aicr.run/v1beta1` |
| Profile-bearing `RecipeMetadata` and `RecipeResult` | `aicr.run/v1alpha3` | `aicr.run/v1beta2` |

**What to do.** Generated artifacts — snapshots, resolved recipes, bundle
provenance — are recaptured or regenerated by re-running the command that
produced them. Files you authored — `AICRConfig`, and any external
`RecipeMetadata`, `RecipeMixin`, or `ComponentRegistry` in a `--data` catalog —
are edited by hand. AICR has no conversion layer and does not rewrite your
catalog.

**The window is v0.22 only.** v0.21 and v0.22 read both the alpha and the target
values; v0.23 reads only the target. An archived artifact whose source cannot be
recaptured stays readable only with a retained v0.21 or v0.22 binary. See
[catalog and binary compatibility](/aicr/integrator-guide/data-extension#catalog-and-binary-compatibility)
for the release-by-release table.

### Empty `apiVersion` on artifacts

**Surface:** bundle and artifact schemas ·
**Deprecated in:** v0.22 ·
**Removed in:** v0.23 for `RecipeResult` inputs; **already removed in v0.21**
for `RecipeMetadata` overlays

Artifacts predating the `apiVersion` field load today with the field absent or
empty. That tolerance retires alongside the alpha values — except for
`RecipeMetadata`, which lost it a release early and without a warning window;
see below.

One narrowing landed earlier than the rest: as of v0.21, a `RecipeMetadata`
overlay passed directly (`aicr bundle -r overlay.yaml`,
`aicr validate -r overlay.yaml`) must carry an `apiVersion`, because the catalog
scanner already required one and the two paths disagreed on the same bytes
([#2421](https://github.com/NVIDIA/aicr/issues/2421)). Hydrated `RecipeResult`
inputs keep the tolerance until v0.23.

**What to do.** Add an `apiVersion` header to any artifact you author or retain.
Use the target value from the table above, not the alpha one — v0.21 onward
accepts both, and only the target survives v0.23.

## Removed

Nothing has completed a removal cycle yet. The first entries land in v0.23.