Clarify consistency in several places

Signed-off-by: Steve Lasker <[email protected]>

Author: SteveLasker

artifact-manifest.md

@@ -1,41 +1,42 @@
 # OCI Artifact Manifest
 
-The OCI artifact manifest generalizes the use cases of [OCI image manifest][oci-image-manifest-spec]. This addition of a 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` without changing the `subjectManifest`
+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.
 
 # Phased Implementations Through Experimental Releases
 
 To meet pressing timelines for delivering Secure Supply Chain artifacts in the fall of 2021, the spec will be split into two phases:
 
 ### Phase 1 - Reference Types
 
-Phase 1 is a time focused release, prioritizing a subset of capabilities needed to support reference types, enabling signing, sbom and image with on-demand loading type scenarios.
+Phase 1 is a time focused release, prioritizing a subset of capabilities needed to support reference types enabling signing and sbom scenarios.
 
-Reference types require two primary capabilities:
-- **Reference Discovery API**, where the consumer finds references by querying what artifacts are related to a target artifact.  
+Reference types require:
+- **Manifest reference**: a means to add content to a registry, referencing existing, unchanged, content.
+- **Reference Discovery API**, where the consumer finds referenced artifacts by querying what artifacts are related to a subject artifact.  
   For example, what signatures or SBoMs are related to the `net-monitor:v1` container image. See the [manifest-referrers api](./manifest-referrers-api.md) for details.
-- **Lifecycle management**, where a user can find and delete reference types, and a registry can garbage collect unreferenced content.  
+- **Lifecycle management**: as content is added to a registry, how is its lifecycle handled? Can a user can find and delete reference types, and how would a registry garbage collect unreferenced content.  
   As registries implement the [distribution-spec][oci-distribution-spec], content may be stored indefinitely. To assure registries MAY implement garbage collection, a manifest is used to identify the intent of the content. See [Lifecycle Management][lifecycle-management] for details. The spec doesn't dictate how an lifecycle management must be implemented, rather focuses on a set of consistent expectations for users to have when working across different implementations.
 
-To separate the reference type deliverables for the fall of 2021 from future work, a `application/vnd.oci.artifact.reftype.manifest.v1+json` is provided.
-For spec details on Phase 1, see [artifact-reftype-spec.md](./artifact-reftype-spec.md)
+To separate the reference type deliverables for the fall of 2021 from future work, a `application/vnd.oci.artifact.manifest.v1+json` is provided.
+For spec details on Phase 1, see [artifact-spec.md](./artifact-spec.md)
 
 ### Phase 2 - Artifact Versioning Support
 
-Phase 2 will enable the full range of scenarios outlined in [WIP generic object spec #37](https://github.com/opencontainers/artifacts/pull/37).
+Phase 2 will work to enable the full range of scenarios outlined in [WIP generic object spec #37](https://github.com/opencontainers/artifacts/pull/37).
 
-By splitting out Phase 1 Reference types from phase 2, focus is placed upon a subset of capabilities in a short time, while providing time to review and evolve to the larger scenarios.
+By splitting out **Phase 1** from **Phase 2**, focus is placed upon a subset of capabilities in a short time, while providing time to review and evolve the larger scenarios.
 
 The goal is to migrate phase 1 implementations to phase 2 (derivative of PR #37). It is not the intent to have dozens of manifest types. Phase 1 is a point in time release to meet pressing security requirements for supply chain artifacts, while building knowledge to feed into phase 2.
 
 ### Migrating from Phase 1 to Phase 2
 
-Registries that implement phase 1 will likely focus on implementing reverse indexes, supporting the referrers api and garbage collection to assure untagged reference types aren't automatically deleted. While the manifest format will change, the underlying capabilities for reverse indexes and lifecycle management will be maintained.
+Registries that implement phase 1 will likely focus on implementing reverse indexes, supporting the referrers api and lifecycle management to assure untagged reference types aren't automatically deleted. While the manifest format will change, the underlying capabilities for reverse indexes and lifecycle management will be maintained. 
 
 All `oci.artifact.*` based content will be named and versioned, enabling distribution instances and distribution clients to determine the content and how it may be processed.
 
 ## Reference Types
 
-There are a new set of scenarios requiring the ability to reference existing artifacts, including the ability to additively sign content or add a SBoM or image with on-demand loading. The addition of a [`subjectManifest`][subjectManifest] property supports linking artifacts through a reference from one artifact manifest to another artifact manifest. By storing these as separate, but linked artifacts, the existing OCI Image tool chain remains unchanged. Tooling that opts into understanding these reference types (eg. SBoM, Notary v2 signatures and Nydus image with on-demand loading) can find the referenced artifacts without changing the existing image tool chains.
+There are a new set of scenarios requiring the ability to reference existing artifacts, including the ability to additively sign content or add a SBoM. The addition of a [`subjectManifest`][subjectManifest] property supports linking artifacts through a reference from one artifact manifest to another artifact manifest. By storing these as separate, but linked artifacts, the existing OCI Image tool chain remains unchanged. Tooling that opts into understanding these reference types (eg. SBoM, Notary v2 signatures and Nydus image with on-demand loading) can find the referenced artifacts without changing the existing image tool chains.
 
 ### Example OCI Artifact Manifests
 
@@ -94,7 +95,7 @@ The `net-monitor:v1` image is persisted as an `oci.image.manifest`, with a uniqu
 
 ### Notary v2 Signatures and SBoM Persistance
 
-Following the [oci.artifact.reftype.manifest spec][oci-artifact-reftype-manifest-spec], reference type artifacts are pushed with an `manifest.artifactType`, and a `subjectManifest` for the artifact referenced.
+Following the [oci.artifact.manifest spec][oci-artifact-manifest-spec], reference type artifacts are pushed with an `manifest.artifactType`, and a `subjectManifest` for the artifact referenced.
 
 A signature, or an SBoM, would be persisted with the content persisted in the `[blobs]` collection, and a `subjectManifest` referencing the `net-monitor:v1` image (by digest).
 
@@ -108,7 +109,7 @@ A signature, or an SBoM, would be persisted with the content persisted in the `[
   ```json
   {
     "schemaVersion": 3,
-    "mediaType": "application/vnd.oci.artifact.reftype.manifest.v1+json",
+    "mediaType": "application/vnd.oci.artifact.manifest.v1+json",
     "artifactType": "cncf.notary.v2-rc1",
     "blobs": [
       {
@@ -138,7 +139,7 @@ The same `net-monitor:v1` image may have an associated SBoM. The SBoM content wo
   ```json
   {
     "schemaVersion": 3,
-    "mediaType": "application/vnd.oci.artifact.reftype.manifest.v1+json",
+    "mediaType": "application/vnd.oci.artifact.manifest.v1+json",
     "artifactType": "example.sbom.v0",
     "blobs": [
       {
@@ -168,7 +169,7 @@ The  `net-monitor:v1` SBoM will also be signed, providing yet another leaf node.
   ```json
   {
     "schemaVersion": 3,
-    "mediaType": "application/vnd.oci.artifact.reftype.manifest.v1+json",
+    "mediaType": "application/vnd.oci.artifact.manifest.v1+json",
     "artifactType": "cncf.notary.v2-rc1",
     "blobs": [
       {
@@ -178,7 +179,7 @@ The  `net-monitor:v1` SBoM will also be signed, providing yet another leaf node.
       }
     ],
     "subjectManifest": {
-      "mediaType": "application/vnd.oci.artifact.reftype.manifest.v1+json",
+      "mediaType": "application/vnd.oci.artifact.manifest.v1+json",
       "digest": "sha256:7a781a3930ea3ba1e54bc25c2bdc53edd0284c62ed651fe7b00369da519a3c1a",
       "size": 16724
     },
@@ -190,7 +191,7 @@ Once all artifacts are submitted, the registry would represent a graph of the `n
 
 ![net-monitor image with an sbom & signatures](media/net-monitor-graph.svg)
 
-The Notary v2 signature and SBoM reference the `net-monitor:v1` image through the `subjectManifest` property. The `net-monitor:v1` image is represented as an oci-image, and requires no changes to its manifest to support the enhancements. The directionality of the `subjectManifest` reference enables links to existing content, without changing the existing content.
+The Notary v2 signature and SBoM reference the `net-monitor:v1` image (as a digest) through the `subjectManifest` property. The `net-monitor:v1` image is represented as an oci-image, and requires no changes to its manifest to support the enhancements. The directionality of the `subjectManifest` reference enables links to existing content, without changing the existing content.
 
 ### Deletion and Ref Counting
 
@@ -214,7 +215,7 @@ In the above example, all the artifacts are displayed without relation to each o
 
 ![flat listing of OCI artifacts](media/repo-listing-attributed.svg)
 
-In the above example, the Notary v2 signature, an SBoM and a collection of attributes are displayed as associated with their target artifact. The references can be collapsed as the `oci.artifact.reftype.manifest` provides the reference information.
+In the above example, the Notary v2 signature, an SBoM and a collection of attributes are displayed as associated with their target artifact. The references can be collapsed as the `oci.artifact.manifest` provides the reference information.
 
 ![expanded listing of OCI artifacts](media/repo-listing-attributed-expanded.svg)
 
@@ -281,7 +282,7 @@ products.wabbit-networks.io/
 
 ![net-monitor image copy](media/net-monitor-copy.svg)
 
-As a reference, copying an image from a public registry to a private registry would involve `docker pull`, `docker tag` and `docker push`
+As an example, copying an image from a public registry to a private registry would involve `docker pull`, `docker tag` and `docker push`
 
 ```bash
 docker pull net-monitor:v1
@@ -299,7 +300,7 @@ Notary v2 signatures and a Notary v2 signed SBoM have been added to the `net-mon
 
 ### OCI-Registry CLI
 
-To copy the above image and the associated signatures, an `oci-reg` cli is used for illustrative purposes. The `oci-reg` cli is an example of tools that could be built by the community, as they would work within and across different OCI conformant registry implementations.
+To copy the above image and the associated signatures, an `oci-reg` cli is used for illustrative purposes. The `oci-reg` cli is an example of tools that _could_ be built by the community, as they would work within and across different OCI conformant registry implementations.
 
 The following command would copy the `net-monitor:v1` image from docker hub to the acme-rockets registry. The CLI _could_ be run within the source or target cloud eliminating the download/upload network hops.
 
@@ -325,7 +326,7 @@ oci-reg copy \
   --copy-references disabled
 ```
 
-As the referenced types are defined by the `manifest.referenceType`, copying specific content may be enabled:
+As the referenced types are defined by the `manifest.subjectManifest`, copying specific content may be enabled:
 
 **Example**: Filter the types of enhancements:
 
@@ -368,13 +369,13 @@ oci-reg delete registry.acme-rockets.io/net-monitor@sha256:b5b2b2c507a0944348e03
 
 ## Further reading
 
-- [oci.artifact.reftype.manifest spec](./artifact-reftype-spec.md) for more info on the manifest
+- [oci.artifact.manifest spec][oci-artifact-manifest-spec] for more info on the manifest
 - [Referrers API][referrers-api] for more information on listing references
 
 [lifecycle-management]:               ./artifact-reftype-spec.md#lifecycle-management
 [oci-image-manifest-spec]:            https://github.com/opencontainers/image-spec/blob/master/manifest.md
 [oci-artifacts]:                      https://github.com/opencontainers/artifacts
-[oci-artifact-reftype-manifest-spec]: ./artifact-reftype-spec.md
+[oci-artifact-manifest-spec]:         ./artifact-spec.md
 [oci-image-index]:                    https://github.com/opencontainers/image-spec/blob/master/image-index.md
 [oci-distribution-spec]:              https://github.com/opencontainers/distribution-spec
 [referrers-api]:                      ./manifest-referrers-api.md

artifact-manifest/net-monitor-image-nydus-ondemand-loading.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 3,
-  "mediaType": "application/vnd.oci.artifact.reftype.manifest.v1+json",
+  "mediaType": "application/vnd.oci.artifact.manifest.v1+json",
   "artifactType": "cncf.nydus.v1-rc1",
   "blobs": [
     {

artifact-manifest/net-monitor-image-sbom.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 3,
-  "mediaType": "application/vnd.oci.artifact.reftype.manifest.v1+json",
+  "mediaType": "application/vnd.oci.artifact.manifest.v1+json",
   "artifactType": "example.sbom.v0",
   "blobs": [
     {

artifact-manifest/net-monitor-image-signature.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 3,
-  "mediaType": "application/vnd.oci.artifact.reftype.manifest.v1+json",
+  "mediaType": "application/vnd.oci.artifact.manifest.v1+json",
   "artifactType": "cncf.notary.v2-rc1",
   "blobs": [
     {

artifact-reftype-spec.md renamed to artifact-spec.md

@@ -1,6 +1,5 @@
 # OCI Artifact Manifest Spec (Phase-1 Reference Types)
-
-The OCI artifact manifest generalizes the use of [OCI image manifest][oci-image-manifest-spec]. 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. 
+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.
 
@@ -17,7 +16,7 @@ The following are Phase 1 examples:
 
 ## OCI Artifact Manifest Properties
 
-For **Phase 1**, an artifact manifest provides a collection of blobs and a reference to a manifest of another artifact.
+For **Phase 1**, an artifact manifest provides an optional collection of blobs and a reference to the manifest of another artifact.
 
 - **`schemaVersion`** *int*
 
@@ -26,25 +25,24 @@ For **Phase 1**, an artifact manifest provides a collection of blobs and a refer
 
 - **`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-rc1+json`, where the version WILL change to reflect newer versions. `v1-rc1` indicates a stable release, and a step towards a completed `v1` spec. Artifact authors SHOULD support multiple `mediaType` versions to provide the best user experience for their artifact type.
+  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]. A `referenceType` is unique value, as registered with iana.org. See [registering unique types.][registering-iana]. The `referenceType` 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 `referenceType` to differentiate the type of artifact.
+  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*
 
-    A 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.
+    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*
 
-   A REQUIRED reference to an existing manifest. 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 distribution-spec MUST return a `400` response code when `subjectManifest` is not found, and not a manifest.
-   - Future versions of the `oci.artifact.manifest` MAY support artifacts without a `subjectManifest`.
+   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*