Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Remove references to artifact manifest and artifact manfiest #407

Merged
merged 2 commits into from
May 4, 2023
Merged

Remove references to artifact manifest and artifact manfiest #407

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
529f2d1
Remove references to artifact manifest and artifact manfiest
brackendawson May 3, 2023
8e2a64e
Remove over-constrained references to manifests
brackendawson May 4, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,11 +69,11 @@ Several terms are used frequently in this document and warrant basic definitions
- **Image Index**: a manifest containing a list of manifests, defined under the OCI Image Spec <sup>[apdx-6](#appendix)</sup>.
- **Image Manifest**: a manifest containing a config descriptor and an indexed list of layers, commonly used for container images, defined under the OCI Image Spec <sup>[apdx-2](#appendix)</sup>.
- **Config**: a blob referenced in the image manifest which contains metadata. Config is defined under the OCI Image Spec <sup>[apdx-4](#appendix)</sup>.
- **Object**: one conceptual piece of content stored as blobs with an accompanying manifest. (This was previously described as an "artifact", and has been renamed to avoid confusion with the "artifact manifest".)
- **Object**: one conceptual piece of content stored as blobs with an accompanying manifest. (This was previously described as an "artifact", and has been renamed to avoid confusion with the "artifactType" of manifests which implement the [referrers API](#listing-referrers))
brackendawson marked this conversation as resolved.
Show resolved Hide resolved
- **Descriptor**: a reference that describes the type, metadata and content address of referenced content. Descriptors are defined under the OCI Image Spec <sup>[apdx-5](#appendix)</sup>.
- **Digest**: a unique identifier created from a cryptographic hash of a Blob's content. Digests are defined under the OCI Image Spec <sup>[apdx-3](#appendix)</sup>
- **Tag**: a custom, human-readable manifest identifier
- **Subject**: an association from one manifest to another, typically used to attach an artifact to an image. The subject field is included in the image and artifact manifests.
- **Subject**: an association from one manifest to another, typically used to attach an artifact to an image. The subject field is included in the image manifest.
brackendawson marked this conversation as resolved.
Show resolved Hide resolved
- **Referrers List**: a list of manifests with a subject relationship to a specified digest. The referrers list is generated with a [query to a registry](#listing-referrers).

## Notational Conventions
Expand Down Expand Up @@ -480,7 +480,7 @@ Client and registry implementations SHOULD expect to be able to support manifest

###### Pushing Manifests with Subject

When processing a request for an image or artifact manfiest with the `subject` field, a registry implementation that supports the [referrers API](#listing-referrers) MUST respond with the response header `OCI-Subject: <subject digest>` to indicate to the client that the registry processed the request's `subject`.
When processing a request for an image manifest with the `subject` field, a registry implementation that supports the [referrers API](#listing-referrers) MUST respond with the response header `OCI-Subject: <subject digest>` to indicate to the client that the registry processed the request's `subject`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When processing a request for an image manifest with the `subject` field, a registry implementation that supports the [referrers API](#listing-referrers) MUST respond with the response header `OCI-Subject: <subject digest>` to indicate to the client that the registry processed the request's `subject`.
When processing a request for a manifest with the `subject` field, a registry implementation that supports the [referrers API](#listing-referrers) MUST respond with the response header `OCI-Subject: <subject digest>` to indicate to the client that the registry processed the request's `subject`.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We haven't approved the subject field on the index manifest yet.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok.. either way is there benefit to restricting the MUST to image manifest... noting the section title is the broader Manifests

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wouldn't that require registries to parse manifests for a field that may not have been included in the image-spec?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

yes I believe so.. Though my generalization was more to reduce complexity in the wording here for when/if subject is added to index... I didn't contemplate that this push MUST was an implied but only for genuine oci.image.manifest.v1+json manifests with said subject field (implying as of v1.1.0).. hmm

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm with Brandon on this specific one, it would introduces another ambiguity. Also bordering on scope creep here, my aim was to not say "artifact manifest in the document", the previous version did explicitly list the manifests it applied to.


When pushing a manifest with the `subject` field and the [referrers API](#listing-referrers) returns a 404 or the `OCI-Subject` header was not set, the client MUST:

Expand Down Expand Up @@ -694,7 +694,7 @@ A client querying the [referrers API](#listing-referrers) and receiving a `404 N
For example, a manifest with the `subject` field digest set to `sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa` in the `registry.example.org/project` repository would have a descriptor in the referrers list at `registry.example.org/project:sha256-aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa`.

This tag should return an image index matching the expected response of the [referrers API](#listing-referrers).
Maintaining the content of this tag is the responsibility of clients pushing and deleting image and artifact manifests that contain a `subject` field.
Maintaining the content of this tag is the responsibility of clients pushing and deleting image manifests that contain a `subject` field.

*Note*: multiple clients could attempt to update the tag simultaneously resulting in race conditions and data loss.
Protection against race conditions is the responsibility of clients and end users, and can be resolved by using a registry that provides the [referrers API](#listing-referrers).
Expand All @@ -709,9 +709,9 @@ The following describes procedures for upgrading to a newer version of the spec
The referrers API here is described by [Listing Referrers](#listing-referrers) and [end-12a](#endpoints).
When registries add support for the referrers API, this API needs to account for manifests that were pushed before the API was available using the [Referrers Tag Schema](#referrers-tag-schema).

1. Registries MUST include preexisting image and artifact manifests that are listed in an image index tagged with the [referrers tag schema](#referrers-tag-schema) and have a valid `subject` field in the referrers API response.
1. Registries MAY include all preexisting image and artifact manifests with a `subject` field in the referrers API response.
1. After the referrers API is enabled, Registries MUST include all newly pushed image and artifact manifests with a valid `subject` field in the referrers API response.
1. Registries MUST include preexisting image manifests that are listed in an image index tagged with the [referrers tag schema](#referrers-tag-schema) and have a valid `subject` field in the referrers API response.
1. Registries MAY include all preexisting image manifests with a `subject` field in the referrers API response.
1. After the referrers API is enabled, Registries MUST include all newly pushed image manifests with a valid `subject` field in the referrers API response.

### API

Expand Down