Merge pull request #1932 from stevvooe/manifest-urls-fix

spec/manifest: clarify relationship between urls and foreign layers

docs/spec/manifest-v2-2.md

@@ -31,8 +31,9 @@ the resources they reference:
 - `application/vnd.docker.distribution.manifest.v1+json`: schema1 (existing manifest format)
 - `application/vnd.docker.distribution.manifest.v2+json`: New image manifest format (schemaVersion = 2)
 - `application/vnd.docker.distribution.manifest.list.v2+json`: Manifest list, aka "fat manifest"
-- `application/vnd.docker.image.rootfs.diff.tar.gzip`: "Layer", as a gzipped tar
 - `application/vnd.docker.container.image.v1+json`: Container config JSON
+- `application/vnd.docker.image.rootfs.diff.tar.gzip`: "Layer", as a gzipped tar
+- `application/vnd.docker.image.rootfs.foreign.diff.tar.gzip`: "Layer", as a gzipped tar that should never be pushed
 
 ## Manifest List
 
@@ -203,6 +204,9 @@ image. It's the direct replacement for the schema-1 manifest.
 
         The MIME type of the referenced object. This should
         generally be `application/vnd.docker.image.rootfs.diff.tar.gzip`.
+        Layers of type
+        `application/vnd.docker.image.rootfs.foreign.diff.tar.gzip` may be
+        pulled from a remote location but they should never be pushed.
 
     - **`size`** *int*
 
@@ -218,11 +222,9 @@ image. It's the direct replacement for the schema-1 manifest.
 
     - **`urls`** *array*
 
-        For an ordinary layer, this is empty, and the layer contents can be
+        Provides a list of URLs from which the content may be fetched. Content
-        retrieved directly from the registry. For a layer with *`mediatype`* of
+        should be verified against the `digest` and `size`. This field is
-        `application/vnd.docker.image.rootfs.foreign.diff.tar.gzip`, this
+        optional and uncommon.
-        contains a non-empty list of URLs from which this object can be
-        downloaded.
 
 ## Example Image Manifest