simplify decision tree for artifacts

[sajayantony]

As per the OCI call today this is makes the artifact decision much more simpler and we just have to set the artifact type for OCI artifacts.

Thanks to @dasiths

graph TD
    HasBlob{Artifact has at least<br>one file or blob?}
    HasConfigData{Artifact has additional<br> metadata config blob?}
    
    Artifact_NoBlobs[Specify <b>artifactType</b>,<br>set config and layers<br>to empty descriptors.]
    Artifact_NoConfig[Specify  <b>artifactType</b>, include<br>artifact in layers, set<br>config to empty descriptor.]
    Artifact_WithConfig[Specify  <b>artifactType</b>,<br> specify config blob and mediaType,<br> include artifact in layers.]

    HasBlob -- No --> Artifact_NoBlobs
    HasBlob -- Yes --> HasConfigData
    HasConfigData -- Yes --> Artifact_WithConfig
    HasConfigData -- No --> Artifact_NoConfig

Loading

[sajayantony]

@Wwwsylvia @qweeah - please review since this would be required for the oras CLI.

[qweeah]

graph TD
    HasBlob{Artifact has at least<br>one file or blob?}
    Artifact_NoBlobs[Specify <b>artifactType</b>,<br>set config and layers<br>to empty descriptors.]
    HasBlob -- No --> Artifact_NoBlobs

Loading

Looks like this subtree is not enforced by oras CLI, user can still customize config blob when no file provided in oras push.

@sajayantony To align oras's behavior with this subtree, do we need to ban --config if no file specified in below scenario?

$ oras push localhost:5000/oras-test:push --config config
Uploading empty artifact
Pushed [registry] localhost:5000/oras-test:push
Digest: sha256:7875ad508b4d3882e7a5ce0e994c82a1ee175bf067261079e6d9bf6f25c20232
$ oras manifest fetch localhost:5000/oras-test:push | jq
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "config": {
    "mediaType": "application/vnd.unknown.config.v1+json",
    "digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "size": 0
  },
  "layers": [
    {
      "mediaType": "application/vnd.oci.empty.v1+json",
      "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
      "size": 2,
      "data": "e30="
    }
  ],
  "annotations": {
    "org.opencontainers.image.created": "2023-08-11T01:15:52Z"
  }
}

[sajayantony]

Let continue the oras CLI discussion in oras-project/oras#1062 @qweeah. Would like folks to review if doc PR update is ok. /cc @shizhMSFT

[Wwwsylvia]

I feel that the mix of "blob", "file", "artifact" could confuse users.
Proposing wordings like below for consistency and readability.

graph TD
    HasBlob{Artifact has at least one file?}
    HasConfigData{Artifact has additional metadata config blob?}
    
    Artifact_NoBlobs[Specify <b>artifactType</b>,<br>set config and layers<br>to empty descriptors.]
    Artifact_NoConfig[Specify  <b>artifactType</b>, set<br>config to empty descriptor, include files in layers.]
    Artifact_WithConfig[Specify  <b>artifactType</b>,<br> specify config blob and mediaType,<br> include files in layers.]

    HasBlob -- No --> Artifact_NoBlobs
    HasBlob -- Yes --> HasConfigData
    HasConfigData -- Yes --> Artifact_WithConfig
    HasConfigData -- No --> Artifact_NoConfig

Loading

graph TD
-   HasBlob{Artifact has at least<br>one file or blob?}
+   HasBlob{Artifact has at least one file?}
    HasConfigData{Artifact has additional<br> metadata config blob?}
    
    Artifact_NoBlobs[Specify <b>artifactType</b>,<br>set config and layers<br>to empty descriptors.]
-   Artifact_NoConfig[Specify  <b>artifactType</b>, include<br>artifact in layers, set<br>config to empty descriptor.]
+   Artifact_NoConfig[Specify  <b>artifactType</b>, set<br>config to empty descriptor, include files in layers.]
-   Artifact_WithConfig[Specify  <b>artifactType</b>,<br> specify config blob and mediaType,<br> include artifact in layers.]
+   Artifact_WithConfig[Specify  <b>artifactType</b>,<br> specify config blob and mediaType,<br> include files in layers.]

    HasBlob -- No --> Artifact_NoBlobs
    HasBlob -- Yes --> HasConfigData
    HasConfigData -- Yes --> Artifact_WithConfig
    HasConfigData -- No --> Artifact_NoConfig

[shizhMSFT]

Based on the graph in PR content, this PR proposes that the artifactType field should always be set for OCI artifact. If so, this should be included in the artifact guideline of the image-spec.

[dasiths]

Based on the graph in PR content, this PR proposes that the artifactType field should always be set for OCI artifact. If so, this should be included in the artifact guideline of the image-spec.

I think that was the consensus for forward looking guidance in opencontainers/image-spec#1101

Encourage new artifact authors to use the artifactType field while also mentioning how the config.mediaType is supported due to legacy.

[dasiths]

I feel that the mix of "blob", "file", "artifact" could confuse users.

What if we say "file or blob" everywhere we refer to a layer? That will be consistent with opencontainers/image-spec#1101.

[sudo-bmitch]

Based on the graph in PR content, this PR proposes that the artifactType field should always be set for OCI artifact. If so, this should be included in the artifact guideline of the image-spec.

@shizhMSFT see opencontainers/image-spec#1101

[sajayantony]

PTAL @shizhMSFT @FeynmanZhou

[shizhMSFT]

LGTM

[shizhMSFT]

LGTM