OCI Artifact Manifest for reference types

Signed-off-by: Steve Lasker <stevenlasker@hotmail.com>

MAINTAINERS

@@ -2,4 +2,4 @@
 + Derek McGowan <derek.mcgowan@docker.com> (@dmcgowan)
 + Mike Brown <brownwm@us.ibm.com> (@mikebrow)
 + Stephen Day <stevvooe@gmail.com> (@stevvooe)
-+ Joey Schorr <jschorr@petricorp.io> (@josephschorr)
++ Joey Schorr <jschorr@redhat.com> (@josephschorr)

README.md

@@ -1,66 +1,17 @@
-# OCI Artifacts
+# OCI Artifacts (Experimental) with OCI Artifact Reference Support
 
-## Artifact Guidance Documents
+This is an experimental branch of oci artifacts, validating the [oci.artifact.manifest spec][oci-artifact-manifest-spec] support of reference types. Reference types are required to meet the [Notary v2 Requirements][nv2-requirements] for not changing the target digest or tag, and the [Notary v2 Scenarios][nv2-scenarios] for content movement within and across registry implementations. Reference types enable a wider range of scenarios, including secure supply chain artifacts that may be represented as a graph as they move across environments.
 
-1. [Artifact Author Guidance](./artifact-authors.md)
+![](media/net-monitor-graph.svg)
 
-## Supporting Documents
+## Table of Contents:
 
-- [Term Definitions](./definitions-terms.md)
+- [OCI Artifact Manifest Overview][oci-artifact-manifest]
+- [OCI Artifact Reference Type Manifest Spec](./artifact-reftype-spec.md)
+- [ORAS experimental support for oci.artifact.manifest references][oras-artifacts] to `push`, `discover`, `pull` referenced artifact types.
 
-## Project Introduction and Scope
-
-Container registries, implementing the [distribution-spec][distribution-spec], provide reliable, highly scalable, secured storage services for container images. Customers either use a cloud provider implementation, vendor implementations, or instance the open source implementation of [distribution][distribution]. They configure security and networking to assure the images in the registry are locked down and accessible by the resources required. Cloud providers and vendors often provide additional values atop their registry implementations from security to productivity features.
-
-Applications and services typically require additional artifacts to deploy and manage, including [helm](https://helm.sh) for deployment and [Open Policy Agent (OPA)](https://github.com/open-policy-agent/opa/issues/1413) for policy enforcement.
-
-Utilizing the [manifest][image-manifest] and [index][image-index] definitions, new artifacts, such as the [Singularity project][singularity], can be stored and served using the [distribution-spec][distribution-spec].
-
-This repository provides a reference for artifact authors and registry implementors for supporting new artifact types with the existing implementations of distribution.
-More particularly this repository has been tasked by the [OCI TOB](https://github.com/opencontainers/tob/blob/master/proposals/artifacts.md) to serve 3 primary goals:
-
-1. **artifact authors** - [guidance for authoring new artifact types.][artifact-authors] Including a clearing house for well known artifact types.
-1. **registry operators and vendors** - guidance for how operators and vendors can support new artifact types, including how they can opt-in or out of well known artifact types. Registry operators that already implement `media-type` filtering will not have to change. The artifact repo will provide context on how new `media-type`s can be used, and how `media-type`s can be associated with a type of artifact.
-1. **clearing house for well known artifacts** - artifact authors can submit their artifact definitions, providing registry operators a list by which they can easily support.
-
-By providing an OCI artifact definition, the community can continue to innovate, focusing on new artifact types without having to build yet another storage solution (YASS).
-
-## Project Governance and License
-
-- [Artifact Authors- How To][artifact-authors]
-- [The Apache License, Version 2.0](LICENSE)
-- [Maintainers](MAINTAINERS)
-- [Maintainer guidelines](MAINTAINERS_GUIDE.md)
-- [Contributor guidelines](CONTRIBUTING.md)
-- [Project governance](GOVERNANCE.md)
-- [Release procedures](RELEASES.md)
-
-## Code of Conduct
-
-This project incorporates (by reference) the OCI [Code of Conduct][code-of-conduct].
-
-## Governance and Releases
-
-This project incorporates the Governance and Releases processes from the OCI project template: https://github.com/opencontainers/project-template.
-
-## Project Communications
-
-This project would continue to use existing channels in use by the [OCI developer community for communication](https://github.com/opencontainers/org#communications)
-
-### Versioning / Roadmap
-
-Artifacts will reference specific [distribution][distribution-spec], [index][image-index] and [manifest][image-manifest] versions in its examples, identifying any dependencies required.
-
-## Frequently Asked Questions (FAQ)
-
-**Q: Does this change the OCI Charter or Scope Table?**
-
-A: No.  Artifacts are a prescriptive means of storing [index][image-index] and [manifest][image-manifest] within [distribution][distribution-spec] implementations.
-
-[artifact-authors]:     ./artifact-authors.md
-[code-of-conduct]:      https://github.com/opencontainers/org/blob/master/CODE_OF_CONDUCT.md
-[distribution]:         https://github.com/docker/distribution
-[distribution-spec]:    https://github.com/opencontainers/distribution-spec/
-[image-index]:          https://github.com/opencontainers/image-spec/blob/master/image-index.md
-[image-manifest]:       https://github.com/opencontainers/image-spec/blob/master/manifest.md
-[singularity]:          https://github.com/sylabs/singularity
+[oci-artifact-manifest]:      ./artifact-manifest.md
+[oci-artifact-manifest-spec]: ./artifact-reftype-spec.md
+[nv2-requirements]:           https://github.com/notaryproject/notaryproject/blob/main/requirements.md
+[nv2-scenarios]:              https://github.com/notaryproject/notaryproject/blob/main/scenarios.md
+[oras-artifacts]:             https://github.com/deislabs/oras/blob/prototype-2/docs/artifact-manifest.md

artifact-authors.md

@@ -53,7 +53,7 @@ The manifest `config.mediaType` is the equivalent of a file extension, enabling
 |Icon|Artifact|`config.mediaType`|
 |-|-|-|
 |<img src="https://github.com/opencontainers/artwork/blob/master/oci/icon/color/oci-icon-color.png?raw=true" width=30x>|[OCI Image][image-spec]|`application/vnd.oci.image.config.v1+json`|
-|<img src="https://github.com/helm/helm-www/blob/main/themes/helm/static/img/apple-touch-icon.png?raw=true" width=30x>|[Helm Chart](https://helm.sh)|`application/vnd.cncf.helm.chart.config.v1+json`|
+|<img src="https://github.com/helm/helm-www/blob/master/themes/helm/static/img/apple-touch-icon.png?raw=true" width=30x>|[Helm Chart](https://helm.sh)|`application/vnd.cncf.helm.chart.config.v1+json`|
 |<img src="https://github.com/sylabs/singularity/blob/master/docs/logos/singularity_v3.png?raw=true" width=30x>|[Singularity][singularity], by [Sylabs][sylabs]|`application/vnd.sylabs.sif.config.v1+json`|
 
 ## Defining a Unique Artifact Type

artifact-manifest-spec.md

@@ -0,0 +1,76 @@
+# OCI Artifact Manifest Spec (Phase-1 Reference Types)
+The OCI artifact manifest generalizes the use cases of [OCI image manifest][oci-image-manifest-spec] by removing constraints defined on the image-manifest such as a required `config` object and required & ordinal `layers`. It then adds a `subjectManifest` property supporting reference types. The addition of a new manifest does not change, nor impact the `image.manifest`. It provides a means to define a wide range of artifacts, including a chain of related artifacts enabling SBoMs, on-demand loading, signatures and metadata that can be related to an `image.manifest` or `image.index`. By defining a new manifest, registries and clients opt-into new capabilities, without breaking existing registry and client behavior or setting expectations for scenarios to function when the client and/or registry doesn't yet implement the new capabilities.
+
+To enable a fall 2021 focus on supply chain security,  **Phase 1** will narrowly focus on Reference Type support, giving time for further generalization with less time constraints.
+
+For usage and scenarios, see [artifact-manifest.md](./artifact-manifest.md)
+
+## Example OCI Artifact Manifests
+
+The following are Phase 1 examples:
+
+- [`net-monitor:v1` oci container image](./artifact-manifest/net-monitor-oci-image.json)
+- [`net-monitor:v1` notary v2 signature](./artifact-manifest/net-monitor-image-signature.json)
+- [`net-monitor:v1` sample sbom](./artifact-manifest/net-monitor-image-sbom.json)
+- [`net-monitor:v1` nydus image with on-demand loading](./artifact-manifest/net-monitor-image-nydus-ondemand-loading.json)
+
+## OCI Artifact Manifest Properties
+
+For **Phase 1**, an artifact manifest provides an optional collection of blobs and a reference to the manifest of another artifact.
+
+- **`schemaVersion`** *int*
+
+  This REQUIRED property specifies the artifact manifest schema version.
+  For this version of the specification, this MUST be `3`. The value of this field WILL change as the manifest schema evolves. Minor version changes to the `oci.artifact.manifest` spec MUST be additive, while major version changes MAY be breaking. Artifact clients MUST implement version checking to allow for future, yet unknown changes. Artifact clients MUST ignore additive properties to minor versions. Artifact clients MAY support major changes, with no guarantee major changes MAY impose breaking changing behaviors. Artifact authors MAY support new and older schemaVersions to provide the best user experience.
+
+- **`mediaType`** *string*
+
+  This field contains the `mediaType` of this document, differentiating from [image-manifest][oci-image-manifest-spec] and [oci-image-index]. The mediaType for this manifest type MUST be `application/vnd.oci.artifact.manifest.v1+json`, where the version WILL change to reflect newer versions. Artifact authors SHOULD support multiple `mediaType` versions to provide the best user experience for their artifact type.
+
+- **`artifactType`** *string*
+
+  Phase 1 of the OCI Artifact spec will support reference types to existing [OCI Artifacts][oci-artifacts]. The REQUIRED `artifactType` is unique value, as registered with iana.org. See [registering unique types.][registering-iana]. The `artifactType` is equivalent to OCI Artifacts that used the `manifest.config.mediaType` to differentiate the type of artifact. Artifact authors that implement `oci.artifact.manifest` use `artifactType` to differentiate the type of artifact. example:(`example.sbom` from `cncf.notary`).
+
+- **`blobs`** *array of objects*
+
+    An OPTIONAL collection of 0 or more blobs. The blobs array is analogous to [oci.image.manifest layers][oci-image-manifest-spec-layers], however unlike [image-manifest][oci-image-manifest-spec], the ordering of blobs is specific to the artifact type. Some artifacts may choose an overlay of files, while other artifact types may store indepdent collections of files.
+
+    - Each item in the array MUST be a [descriptor][descriptor], and MUST NOT refer to another `manifest` providing dependency closure.
+    - The max number of blobs is not defined, but MAY be limited by [distribution-spec][oci-distribution-spec] implementations.
+    - An encountered `descriptor.mediaType` that is unknown to the implementation MUST be ignored.
+
+- **`subjectManifest`** *descriptor*
+
+   An OPTIONAL reference to any existing manifest within the repository. When specified, the artifact is said to be dependent upon the referenced `subjectManifest`.
+   - The item MUST be a [descriptor][descriptor] representing a manifest. Descriptors to blobs are not supported. The registry MUST return a `400` response code when `subjectManifest` is not found in the same repository, and not a manifest.
+
+- **`annotations`** *string-string map*
+
+    This OPTIONAL property contains arbitrary metadata for the image manifest.
+    This OPTIONAL property MUST use the [annotation rules](annotations.md#rules).
+
+    See [Pre-Defined Annotation Keys][annotations]
+
+## Push Validation
+
+Following the [distribution-spec push api](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#push), all `blobs` *and* the `subjectManifest` descriptors SHOULD exist when pushed to a distribution instance.
+
+## Lifecycle Management
+
+For Phase 1, artifact types will be limited to reference types. A reference type is an artifact that doesn't have a lifecycle unto itself. A container image is said to have an independent lifecycle. A reference type, such as an SBoM or signature have a lifecycle tied to the `subjectManifest`. When the `subjectManifest` is deleted or marked for garbage collection, the defined artifact is subject to deletion as well. A distribution instance SHOULD delete, (refCount -1) the artifact when the `subjectManifest` is deleted.
+
+### Tagged `referenceTypes`
+
+As signatures and SBoMs are not considered independent artifact types, they SHOULD NOT have a tag, simplifying the lifecycle management. As the `subjectManifest` is marked for deletion (refCount=0), the `referenctType` is also marked for deletion (refCount -1). However, these artifacts MAY have tags as future versions of the artifact manifest MAY support independent types. 
+
+[oci-artifacts]:                   https://github.com/opencontainers/artifacts
+[oci-config]:                      https://github.com/opencontainers/image-spec/blob/master/config.md
+[oci-image-manifest-spec]:         https://github.com/opencontainers/image-spec/blob/master/manifest.md
+[oci-image-manifest-spec-layers]:  https://github.com/opencontainers/image-spec/blob/master/manifest.md#image-manifest-property-descriptions
+[oci-image-index]:                 https://github.com/opencontainers/image-spec/blob/master/image-index.md
+[oci-distribution-spec]:           https://github.com/opencontainers/distribution-spec
+[media-type]:                      https://github.com/opencontainers/image-spec/blob/master/media-types.md
+[artifact-type]:                   https://github.com/opencontainers/artifacts/blob/master/artifact-authors.md#defining-a-unique-artifact-type
+[registering-iana]:                ./artifact-authors.md#registering-unique-types-with-iana
+[descriptor]:                      https://github.com/opencontainers/image-spec/blob/master/descriptor.md
+[annotations]:                     https://github.com/opencontainers/image-spec/blob/master/annotations.md