Proposal - Change artifact manifest artifactType field from SHOULD to MUST

[lachie83]

Initial Slack conversation started in the following thread from @shizhMSFT

Hi, while implementing image-spec v1.1.0-rc2, we find that the artifactType field is inconsistent in artifact.md and artifact.go. The artifactType field is marked as SHOULD in the markdown file while is NOT marked as omitempty in the go struct. Therefore, I am curious when we will have an empty value for the artifactType field. Where can I find an example for such a scenario?

Possible approaches for a fix:

1. Revise artifact.md and mark artifactType field as MUST.
2. Revise artifact.go and add omitempty tag to the artifactType field.

[lachie83]

cc @sudo-bmitch @imjasonh - Brandon created the following PR in support of option 2 - #967

[lachie83]

I would like to weigh in with my preference for option 1 - if you consider the value of that field is to filter and then pull ONLY the artifacts you want. If that field is not a MUST then I don’t think it adds any value as we’re going to double the work to implement filtering both server side and client side. Keeping this as a SHOULD will result in more API requests to the server in or to determine exactly what each artifact is unless we establish convention in some other form. I would ask us to reconsider making this a MUST.

Also without that being a MUST this is a valid artifact manifest

{
  “mediaType”: “application/vnd.oci.artifact.manifest.v1+json”
}

I’m trying to get my head around what value it adds. I would lean in on making this a MUST and we can consider dialing it back to a should if we think that valid manifest above is useful. It’s always easier to loosen specs in fields than to tighten them.

[sudo-bmitch]

Adding @sajayantony and @michaelb990 who may have been involved with this during the working group. When we thought about filtering, a missing artifactType would probably be treated the same as an empty string, which would only match an empty string.

The testing, scheme, and parts of the spec currently assume it can be empty, and this PR 963 includes that minimal example in the test cases. I don't think that minimal example is useful by itself, but it does give the most flexibility to future use cases where users pick which of the fields they want to include for their use cases.

[michaelb990]

This is fine with me. It's certainly easier to loosen it later if we can come up with a use case, but for now, it seems nicer to have it a MUST.

[sajayantony]

SGTM. I don't recollect there being any scenario where this field was omitted and yes, it's easier to relax this requirement later.

[sudo-bmitch]

Here's the original change where we were back and forth between optional, should, and required/must. We discussed it in the meeting, but didn't take notes on our reasoning. oci-playground#9

[sajayantony]

Wow @sudo-bmitch kudos for finding this one.
Also worth considering this - opencontainers/distribution-spec#357 (comment)

[sudo-bmitch]

Capturing our discussion from the meeting this week, we decided to leave artifactType as SHOULD. If someone creates an artifact without including artifactType, that won't be returned in referrers responses that filter on the artifactType.

Some of the decision factors included:

• Registries are unlikely to enforce RFC 6838.
• There are potential future uses of the artifact manifest that we can't predict, and this gives the manifest the most flexibility to support future use cases.
• There wasn't enough of a value add in forcing the use of the artifactType since anyone that didn't want to use the field could easily use the wrong value (impersonating another artifact type, or using a value that would never be useful to others)

Some of the reasons we wanted to make this required included:

• Adding UI's on top of artifacts could use the field to differentiate the artifact without further introspection.
• Artifacts could always be clearly identified in the referrers API response.

I'm closing this since we came to a conclusion. But if others remember different parts of the discussion, please add those for future reference.