Generic Distribution Content Manifests

A proposal for generic content manifests that can be used for
any type of application that can be represented as a JSON config
and a collection of blobs of data, or may be composed of other
such applications.

Docker-DCO-1.1-Signed-off-by: Josh Hawn <josh.hawn@docker.com> (github: jlhawn)

doc/spec/manifest.md

@@ -0,0 +1,220 @@
+# Distribution Content Manifests
+
+A Content Manifest is a simple JSON file which contains general fields that
+are typical to any package management system. The goal is for these manifests
+to describe an application and its dependencies in a content-addressable and
+verifiable way.
+
+## Field Descriptions
+
+- **`schemaVersion`** *int*
+
+    Specifies the schema version of the manifest as an integer. This document 
+    describes version `1` only.
+
+- **`repository`** *string*
+
+    Specifies the full name of the repository to which this manifest belongs.
+
+    > TODO: Is this field necessary?
+
+- **`createdAt`** *string*
+
+    ISO-8601 formatted combined date and time at which the manifest was
+    created.
+
+- **`maintainers`** *array*
+
+    An array of objects representing persons or organizations which are
+    designated as mainainers of the described content. Fields are:
+
+    - **`name`** *string*
+
+        The name of a maintaining person or organization.
+
+    - **`email`** *string*
+
+        The email address of a maintainer.
+
+    - **`url`** *string*
+
+        A URL to a maintainer's website, blog, etc.
+
+- **`description`** *string*
+
+    A brief description of the content or application.
+
+- **`keywords`** *array*
+
+    An array of strings which should be considered keywords that may be used
+    by a separate search system to index content.
+
+- **`website`** *string*
+
+    A URL to a related website or project page for the application.
+
+- **`licenses`** *array*
+
+    An array of strings which identify any software licenses which apply
+    to the application. Values should be a [SPDX License Identifier](https://spdx.org/licenses/).
+
+- **`Dependencies`** *array*
+
+    An array of objects which describe content which this application depends
+    on. Those may be generic blobs of data or other content manifests and
+    their dependencies as described by their media type. Fields are:
+
+    - **`mediaType`** *string*
+
+        The MIME type of the dependency object.
+
+    - **`size`** *int*
+
+        The size in bytes of the dependency object.
+
+    - **`repository`** *string*
+
+        The name of the repository from which to fetch the object.
+
+    - **`digest`** *string*
+
+        The base64url-encoded SHA384 digest of the object.
+
+    Any media type may be in the `mediaType` field as the application may
+    use any type of content. If the `mediaType` is
+    `application/vnd.docker.distribution.content.manifest.v1+json` then the
+    dependency is another content manifest as described by this document. The
+    dependencies from that manifest should also be considered dependencies of
+    this application.
+
+    If the `repository` field is empty or omitted, then the object should be
+    considered to be in the same repository as this manifest.
+
+- **`application`** *object*
+
+    Fields are:
+
+    - **`mediaType`** *string*
+
+        The MIME type of the JSON object in the `data` field.
+
+    - **`data`** *object*
+
+        Abstract application data in any schema, as described by the
+        `mediaType` field.
+
+    Application data may be *any* JSON object, allowing this manifest format,
+    along with the generic dependenncies list, to support any type of 
+    application that can be represented as a JSON config and a collection of
+    content-addressable blobs of data.
+
+- **`metadata`** *object*
+
+    Metadata may be *any* JSON object, allowing content creators to annotate
+    their application manifest with any additional labels beyond those already
+    defined by this manifest format. 
+
+
+
+
+
+
+### Example Manifest
+
+```json
+{
+    "schemaVersion": 1,
+    "repository": "example.com/foo/bar",
+    "createdAt": "2015-02-06T17:01:15.897825411-08:00",
+    "maintainers": [
+        {
+            "name": "Phillip Edward Nuñez",
+            "email": "pnunez@example.com",
+            "url": "https://example.com/pnunez/"
+        }
+    ],
+    "description": "Application to Simulate Turbo Encabulators",
+    "keywords": [
+        "foo",
+        "bar",
+        "baz"
+    ],
+    "website": "https://foo.bar.baz.example.com",
+    "licenses": [
+        "Apache-2.0"
+    ],
+    "dependencies": [
+        {
+            "mediaType": "application/vnd.docker.distribution.content.manifest.v1+json",
+            "size": 1024,
+            "repository": "isv.example.com/base/system",
+            "digest": "yKuiDWRdxLyLw5u9w7aEJ4doaLyBKJOAnMPjlmMcm-j7_CIP2zviko5jNGC5pofU"
+        },
+        {
+            "mediaType": "application/vnd.docker.container.image.layer+x-gtar",
+            "size": 32654,
+            "digest": "kvV7qZ3R_8havXJKqEjYIxFd7jBtjlKheOwvF8vzg9AMCvBtCi2D-l5_u-h_0fBx"
+        },
+        {
+            "mediaType": "application/vnd.docker.container.image.layer+x-gtar",
+            "size": 16724,
+            "digest": "5zhS4u9AtGZ7QSsgeEqbVnCk5s9nfwk_gM1Ex6Uxwh2sKIeRJ4LaW0rg55Tx4X-Y"
+        },
+        {
+            "mediaType": "application/vnd.docker.container.image.layer+x-gtar",
+            "size": 73109,
+            "digest": "JokAl_qdptC92RjpJN86q9Hdkis8EBger5IRfr7eYyrPAI-278PF2lTDeBIXXY2H"
+        },
+        {
+            "mediaType": "application/vnd.docker.distribution.content.manifest.v1+json",
+            "size": 3072,
+            "repository": "example.com/foo/secrets",
+            "digest": "ssr2tbWKFiqVPf7ABjaVsB53_UEr-q4MVnThRAGp9itsW9ggKdo1bTdTNj9VHzH9"
+        }
+    ],
+    "application": {
+        "mediaType": "application/vnd.docker.container.image.params.v1+json",
+        "data": {
+            "user": "alice",
+            "group": "staff",
+            "cpuShares": 8,
+            "memory": 2048,
+            "memorySwap": 4096,
+            "workingDirectory": "/home/alice",
+            "ports": [
+                {
+                    "port": 8080,
+                    "protocol": "tcp"
+                }
+            ],
+            "volumes": [
+                "/var/job-result-data",
+                "/var/log/my-app-logs"
+            ],
+            "entrypoint": [
+                "/bin/my-app-binary"
+            ],
+            "command": [
+                "--foreground",
+                "--config",
+                "/etc/my-app.d/default.cfg"
+            ],
+            "environment": {
+                "DEBUG": "True",
+                "PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+                "RETRO": "False"
+            }
+        }
+    },
+    "metadata": {
+        "buildSteps": [
+            "FROM isv.example.com/base/system@yKuiDWRdxLyLw5u9w7aEJ4doaLyBKJOAnMPjlmMcm-j7_CIP2zviko5jNGC5pofU",
+            "MAINTAINER Phillip Edward Nuñez \u003cpnunez@example.com\u003e (https://example.com/pnunez/)",
+            "ADD some/of/my/codebase /tmp/build",
+            "RUN make my-app"
+        ],
+        "context": "https://git.example.com/foo/bar.git#55272c5a9e3d16b5f4ce28ee5dd881983e3c868f",
+        "version": "3.1.4-a159+265"
+    }
+}
+```