Update Proposal C with feedback and requirements

- Do not allow Node manifests to contain objects that link to
  other Node manifests.
- Add how proposal solves requirements at the bottom.

Signed-off-by: nisha <[email protected]>

Author: nishakm

docs/proposals/PROPOSAL_C.md

@@ -4,7 +4,7 @@ Create a Node manifest.
 
 ## Description
 
-The proposal introduces a "Node" manifest used to organize container images with related artifacts or to group container images together into a higher order artifact. It is based on the typical "Node" data structure used for creating linked lists.
+The proposal introduces a "Node" manifest used to organize container images with related artifacts or to group container images together into a higher order artifact. It is based on the typical "Node" data structure.
 
 A detailed description of this proposal can be found [here](https://docs.google.com/document/d/1KYJaCm5Z-BJ7hVOI_lDh4vEvrmyEAMwUp2nJBELstGw/edit).
 
@@ -28,7 +28,7 @@ The JSON Schema for a "node" manifest looks like this:
   "mediaType": "application/vnd.oci.node.v1+json",
   "description": "This is a generic node object",
   "objects": [
-    ... list of blob descriptors...
+    ... list of blob descriptors ...
   ],
   "reference": {
     ... one blob descriptor
@@ -37,6 +37,10 @@ The JSON Schema for a "node" manifest looks like this:
   }
 }
 ```
+Restrictions on this manifest schema to prevent loops and reduce load on server side processing:
+
+- "objects" CANNOT contain descriptors to another Node manifest.
+- "reference" has a cardinality of 0..1 i.e. it can either contain 0 or 1 descriptor.
 
 This is an example of using the node manifest to refer multiple ice cream ingredients to a specific ice cream:
 
@@ -97,7 +101,7 @@ This is an example of multiple ice creams grouped together to make one ice cream
 }
 ```
 
-_NOTE_:The Node manifest looks very similar to the [index](https://github.com/opencontainers/image-spec/blob/main/image-index.md). It may be possible to modify the index manifest to incorporate these features.
+_NOTE_:The Node manifest looks very similar to the [index](https://github.com/opencontainers/image-spec/blob/main/image-index.md). Further experiments need to be done in order to assert that the index schema can accept OCI descriptors as well as image manifests.
 
 This is an example of using a Node manifest to describe a single ingredient:
 
@@ -117,67 +121,9 @@ This is an example of using a Node manifest to describe a single ingredient:
 }
 ```
 
-This is an example of creating a tree structure with the node manifest:
-
-Existing ice creams:
-
-```jsonc
-{
-  "schemaVersion": 3,
-  "mediaType": "application/vnd.oci.node.v1+json",
-  "description": "Vanilla Ice Cream - created two months ago",
-  "objects": [
-    {
-      "mediaType": "icecream/vnd.glenandlarry.vanilla.v2.0.1+batch",
-      "size": 12,
-      "digest": "sha256:4a77111a"
-    }
-  ]
-  "reference": {}
-}
-
-{
-  "schemaVersion": 3,
-  "mediaType": "application/vnd.oci.node.v1+json",
-  "description": "Chocolate Ice Cream - created one month ago",
-  "objects": [
-    {
-      "mediaType": "icecream/vnd.glenandlarry.chocolate.v0.0.2+batch",
-      "size": 10,
-      "digest": "sha256:c0c01a7e"
-    }
-  ]
-  "reference": {}
-}
-```
-
-New ice cream:
-
-```jsonc
-{
-  "schemaVersion": 3,
-  "mediaType": "application/vnd.oci.node.v1+json",
-  "description": "Vanilla Chocolate Swirl - created two days ago",
-  "objects": [
-    {
-      "mediaType": "application/vnd.oci.node.v1+json",
-      "size": 15,
-      "digest": "sha256:b1ab1ab1a"
-    },
-    {
-      "mediaType": "application/vnd.oci.node.v1+json",
-      "size": 12,
-      "digest": "sha256:cabba9ebeef"
-    }
-  ]
-  "reference": {}
-}
-
-```
-
 ### Registry HTTP API
 
-No modifications to the existing API are needed. The proposal includes the following new APIs
+No modifications to the existing API are needed. The proposal includes the following new APIs:
 
 #### References to a tag or digest
 
@@ -321,3 +267,38 @@ Gives response:
   "Chocolate Sprinkles Ice Cream"  
 }
 ```
+
+## Requirements
+
+### Filtering
+
+- Query for artifact: use `GET /v3/<name>/manifests/<reference>`.
+- Query for referrers to an artifact: use `GET /v3/<name>/referrers/<reference>`.
+- Query for referrers of a given type to an artifact: use `GET /v3/<name>/referrers/<reference>`, then use clinet to filter based on `description`. This is to allow artifact producers to include specific keywords rather than relying on IANA artifact types.
+- Query for referrers to an artifact with certain annotations: Not supported.
+- Query for the most up-to-date artifacts: If Node manifests are used to combine artifacts of a certain type, and a client follows a pattern where the most up-to-date artifact is appended to the beginning of the list, then the most up-to-date artifact is the one at the beginning of the list. However, there isn't any strong protection against not following these rules. Clients will have to rely on some indicator in the description that points to the "latest" artifact.
+- Tag reduction: Node manifests pointing to a list of artifacts removes the requirement to tag the artifacts themselves if needed.
+
+### Backwards Compatibility
+
+- Impact on existing runtimes: Existing manifests such as container or index manifests are not affected.
+- Moving artifacts to and from old and new registries: Registries that do not support node manifests require the client to create tags for each of the embedded artifacts before pushing them. All the information in description and reference will be lost. Registries that support node manifests have no effect on artifacts that require tagging.
+- Pull artifacts by tag: Node manifests will not affect tags on other artifacts.
+- Impact on existing artifacts: Node manifests should not modify existing artifacts nor create duplicates of the same artifact, as is the case with existing registries.
+- Checking registry for references support: use `GET /v3/`. Catalog listing is not prescribed in this proposal.
+- Server side mount: If a large blob is pushed to the registry and then referenced by a Node manifest, a server side mount should be possible.
+- Image Layout: unaffected.
+
+### Content Management
+
+- Storing groups of artifacts with a reference to another artifact: Node manifests support this.
+- Deleting referencing artifacts: use `GET /v3/<name>/referrers/<reference>` to get a list of referring artifacts and then delete all or specific ones.
+- Push artifacts that reference a non existent artifact: This is should be possible if registries don't perform a check that the digest exists.
+- Move selected referrers to other registries: The client is responsible for selection of the artifacts and pushing to the target registries, including checks if the registry supports node manifests.
+- Artifact lifecycle management: Node manifests allow for lifecycle policies to be applied to the list of objects.
+- Immutable tags: Not supported in this proposal. However, collections of different types of artifacts may be referenced by a long lived tag.
+- Updating an existing artifact: use `GET /v3/<name>/manifests/<reference>` to fetch a node manifest, then update the objects list with a new artifact. OR, use the existing APIs.
+- Avoiding race conditions when pushing to the same endpoint: Not addressed by this proposal.
+- Requires/Provides relationships: Use the description to indicate the reference is a "requires" or "provides" relationship.
+- Supplier information: Node manifests can include attestation, signature, and SBOM artifacts, which can be li,ked using references.
+- Timestamp and retention policies: Server side policies on node manifest size or length of the objects list can be enforced. Timestamp data may be embedded in the description. A registry provider would then have to require that every node manifest have timestamp data in the description which it can read.