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

Clarify the registry must accept a missing subject phrasing #505

Merged
merged 1 commit into from
Jan 27, 2024
Merged

Clarify the registry must accept a missing subject phrasing #505

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 1 addition & 1 deletion spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,7 +209,7 @@ If the blob or manifest is not found in the registry, the response code MUST be
Pushing an object typically works in the opposite order as a pull: the blobs making up the object are uploaded first, and the manifest last.
A useful diagram is provided [here](https://github.com/google/go-containerregistry/tree/d7f8d06c87ed209507dd5f2d723267fe35b38a9f/pkg/v1/remote#anatomy-of-an-image-upload).

A registry MUST accept an otherwise valid manifest with a `subject` field that references a manifest that does not exist, allowing clients to push a manifest and referrers to that manifest in either order.
A registry MUST initially accept an otherwise valid manifest with a `subject` field that references a manifest that does not exist in the repository, allowing clients to push a manifest and referrers to that manifest in either order.
Copy link
Contributor

Choose a reason for hiding this comment

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

Also add the language?

The subject relationship is a weak association, pls see image spec, etc?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@rchincha how should that be phrased here?

Copy link
Member

Choose a reason for hiding this comment

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

@rchincha would you be opposed to leaving that off for a subsequent patch or minor version, as we look to clarify more language over time?

I think it'd be fine to add it, depending on wording, but it might stand out and lead to more questions when comparing the two specs. Just devil's advocate, I think it'd be fine either way.

Copy link
Member

@mikebrow mikebrow Jan 27, 2024 •
edited

Choose a reason for hiding this comment

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

weak / strong are certainly common vernacular but would raise more questions.. also probably not the right place to define subject descriptor reference..

Copy link
Member

Choose a reason for hiding this comment

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

see above subject definition:
- **Subject**: an association from one manifest to another, typically used to attach an artifact to an image.

maybe in another PR and change ^ to is an association, aka. a weak reference, from one manifest to another, typically used to attach an artifact to an image.

but that implies we should use strong for content descriptors... yada yada

Copy link
Member

@mikebrow mikebrow Jan 27, 2024 •
edited

Choose a reason for hiding this comment

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

I see the ^ definition changed over in the image spec.. ::

- **`subject`** *[descriptor](descriptor.md)*
     This OPTIONAL property specifies a [descriptor](descriptor.md) of another manifest.
     This value defines a weak association to a separate [Merkle Directed Acyclic Graph (DAG)][dag] structure, and is used by the [`referrers` API][referrers-api] to include this manifest in the list of responses for the subject digest.

Copy link
Member

Choose a reason for hiding this comment

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

given the new definition in image.. I think we can just link to that definition and/or normalize in distribution's definition by saying a weak association in the definition we have here...

A registry MAY reject a manifest uploaded to the manifest endpoint with descriptors in other fields that reference a manifest or blob that does not exist in the registry.
When a manifest is rejected for this reason, it MUST result in one or more `MANIFEST_BLOB_UNKNOWN` errors <sup>[code-1](#error-codes)</sup>.

Expand Down