# ORAS migrating to OCI Reference types
**Status**: Work-in-progress
**Version**: draft
## Overview
The two PRs of working group proposal for reference types were merged recently and will be released in Image-spec v1.1 and distribution-spec v1.1.0. See below two PRs for reference types:
* Working Group Proposal for Reference Types by michaelb990 · [Pull Request #335 · opencontainers/distribution-spec](https://github.com/opencontainers/distribution-spec/pull/335)
* Working Group Proposal for Reference Types by lachie83 · [Pull Request #934 · opencontainers/image-spec](https://github.com/opencontainers/image-spec/pull/934)
>NOTES:
> distribution-spec v1.1.0-rc.1 was released, see [v1.1.0-rc1](https://github.com/opencontainers/distribution-spec/releases/tag/v1.1.0-rc1)
> image-spec v1.1.0-rc.2 was released, see [v1.1.0-rc.2](https://github.com/opencontainers/image-spec/releases/tag/v1.1.0-rc2)
>
This document describes the changes, manifest, and fallback use cases for ORAS-go library and ORAS CLI when migrating to OCI reference types.
>NOTES:
>EDIT (SteveLasker): Per the Distribution Spec: [Enabling the Referrers API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#enabling-the-referrers-api)
> 3. After the referrers API is enabled, Registries MUST include all newly pushed image and artifact manifests with a valid refers field in the referrers API response.
> This means a registry that supports the [`_referrers`](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers) api MUST support the OCI Artifact manifest
>Registries that support the referrer API also support OCI artifact manifest. Registries that support OCI artifact manifest may not support referrer API.
## Solution and Plan
`ORAS` will support only OCI artifact in the near future and fall back to use OCI Image manifest with a `subject` property if a registry doesn't support OCI artifact. There is no plan to support both ORAS artifact and OCI artifact in the same `ORAS` release. The last version of `ORAS-go` supporting ORAS artifact is `v2.0.0-rc.3`, and the last version of `ORAS CLI` supporting ORAS artifact is `0.15.x`.
Check below table for the timeline of releases supporting OCI artifact:
| Release | ETA Date | Related issue |
| --- | --- | --- |
| ORAS-go v2.0.0-rc.4 | End of Oct, 2022| [ORAS-go #271](https://github.com/oras-project/oras-go/issues/271) |
| ORAS CLI 0.16.0 | Nov 7, 2022 | [ORAS #406](https://github.com/oras-project/oras/issues/406) |
## ORAS-go supports reference types
Changes are required for the following use cases:
* Pushing Manifests with Subject
* Discovering Referrers
* Deleting Manifests
### Pushing Manifests with Subject
Follow the spec [Pushing Manifests with Subject](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pushing-manifests-with-subject)
### Discovering Referrers
Follow the spec [Listing Referrers](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers)
### Deleting Manifests
Follow the spec [Deleting Manifests](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#deleting-manifests)
## ORAS CLI supports reference types
### ORAS push command
A new flag is introduced with the name `--compatibility={none,min,max}`, so that users can change the default pushing behavior.
- With value set to `min` (default value), pushing OCI artifact manifests to a registry, if the response is `400 Bad Request`, fallback to pushing OCI image manifest.
- With value set to `none`, no fallback procedure is triggered for pushing OCI artifact manifests. Push fails if the response is `400 Bad Request`.
- With value set to `max`, OCI image manifests are pushed instead of OCI artifact manifests.
>NOTES: The flag names are tentative. Any suggestions are welcome.
Should follow below steps:
- PUT artifact manifest
- If 200, we are good.
- Else
- If can fallback (we don't know that the referrers API is enabled, and the error is 400 and MANIFEST_INVALID), PUT OCI image manifest.
- Else abort.
### ORAS pull command
No changes
### ORAS attach command
A new flag is introduced with the named `--compatibility={none,min,max}`, so that users can change the default pushing behavior.
- With value set to `min` (default value), OCI artifact manifest with `subject` field is attached, if the response is `400 Bad Request`, fallback to attaching OCI image manifest with `subject` field.
- With value set to `none`, no fallback procedure is triggered for attaching OCI artifact manifests. Attaching fails if the response is `400 Bad Request`.
- With value set to `max`, OCI image manifests are attached instead of OCI artifact manifests.
If the referrers API returns a 404, use the same logic as `ORAS-go` [Pushing Manifests with Subject](https://hackmd.io/@yizha1/ORAS_to_OCI_reference_type#Pushing-Manifests-with-Subject).
>NOTES: The flag names are tentative. Any suggestions are welcome.
Should follow below steps:
- oras: Resolve the subject manifest --> 200
- oras: PUT artifact manifest
- If it succeeds,
- oras-go: Check the referrers API is enabled or not.
- If it is enabled, done / return
- If it fails,
- oras: set referrers capability to false.
- oras: PUT image manifest
- oras-go: Update the index
### ORAS manifest fetch
No changes
### ORAS manifest Push
#### Pushing manifests with subject
If the referrers API returns a 404, use the same logic as `ORAS-go` [Pushing Manifests with Subject](https://hackmd.io/@yizha1/ORAS_to_OCI_reference_type#Pushing-Manifests-with-Subject).
When pushing an OCI artifact manifests with `subject` field，if the response is `400 Bad Request`, by default, fallback to pushing an OCI image manifest with `subject` field. Fallback procedure can be disabled using a new flag named `--strict`.
When user pushes an OCI Image manifest with `subject` field，by default, image index is updated, user can disable updating image index using the new flag `--strict`.
>NOTES: The flag names are tentative. Any suggestions are welcome
#### Pushing manifests without subject
No changes when pushing an OCI image manifest without `subject` field.
When pushing an OCI artifact manifests without a `subject` field，if the response is `400 Bad Request`, by default, fallback to pushing an OCI image manifest without a `subject` field. Fallback procedure can be disabled using a new flag named `--strict` (flag name is tentative).
>NOTES: The flag names are tentative. Any suggestions are welcome
### ORAS manifest Delete
By default, only supplied manifest is deleted.
Use a new flag named `-r, --recursive` to delete `referrer` manifests recursively. See below example, by using the flag `-r, --recursive`, when deleting `subject` manifest, manifest `A`, `B`, `C` are deleted, and image index are updated.
Use a new flag `--strict` to disable updating image index.
```mermaid
graph LR
A -- refers --> Subject
B -- refers --> Subject
C -- refers --> Subject
Index --> A
Index --> B
Index --> C
Tag --> Index
Tag -.- Subject
```
>NOTES: The flag names are tentative. Any suggestions are welcome
### ORAS blob
No changes
### ORAS tag
No changes
### ORAS repository
`referrers tag schema` may mess the results of `oras repository list`, so a new flag could be introduced to filter out `referrers tag schema` from the results.
### ORAS discover
The same logic as `ORAS-go` [discover referrers](https://hackmd.io/@yizha1/ORAS_to_OCI_reference_type#Discovering-referrers).
### ORAS copy from target A to target B (include extended copy)
>Notes: Registry is one type of target, there are others types of target, for example, OCI-layout.
`ORAS` doesn't perform manifest conversion, so copy succeeds only if both target A and target B support the type of manifest being copied.
| Target | B: Support OCI Artifact | B: Support OCI Image |
| --------------- | --------------- | ------------ |
| A: Copy OCI Artifact | Success | Failure |
| A: Copy OCI Image | Success | Success |
Sign in with Wallet
Connect another wallet