github.com/demonoid81/moby@v0.0.0-20200517203328-62dd8e17c460/image/spec/v1.2.md (about)

     1  # Docker Image Specification v1.2.0
     2  
     3  An *Image* is an ordered collection of root filesystem changes and the
     4  corresponding execution parameters for use within a container runtime. This
     5  specification outlines the format of these filesystem changes and corresponding
     6  parameters and describes how to create and use them for use with a container
     7  runtime and execution tool.
     8  
     9  This version of the image specification was adopted starting in Docker 1.12.
    10  
    11  ## Terminology
    12  
    13  This specification uses the following terms:
    14  
    15  <dl>
    16      <dt>
    17          Layer
    18      </dt>
    19      <dd>
    20          Images are composed of <i>layers</i>. Each layer is a set of filesystem
    21          changes. Layers do not have configuration metadata such as environment
    22          variables or default arguments - these are properties of the image as a
    23          whole rather than any particular layer.
    24      </dd>
    25      <dt>
    26          Image JSON
    27      </dt>
    28      <dd>
    29          Each image has an associated JSON structure which describes some
    30          basic information about the image such as date created, author, and the
    31          ID of its parent image as well as execution/runtime configuration like
    32          its entry point, default arguments, CPU/memory shares, networking, and
    33          volumes. The JSON structure also references a cryptographic hash of
    34          each layer used by the image, and provides history information for
    35          those layers. This JSON is considered to be immutable, because changing
    36          it would change the computed ImageID. Changing it means creating a new
    37          derived image, instead of changing the existing image.
    38      </dd>
    39      <dt>
    40          Image Filesystem Changeset
    41      </dt>
    42      <dd>
    43          Each layer has an archive of the files which have been added, changed,
    44          or deleted relative to its parent layer. Using a layer-based or union
    45          filesystem such as AUFS, or by computing the diff from filesystem
    46          snapshots, the filesystem changeset can be used to present a series of
    47          image layers as if they were one cohesive filesystem.
    48      </dd>
    49      <dt>
    50          Layer DiffID
    51      </dt>
    52      <dd>
    53          Layers are referenced by cryptographic hashes of their serialized
    54          representation. This is a SHA256 digest over the tar archive used to
    55          transport the layer, represented as a hexadecimal encoding of 256 bits, e.g.,
    56          <code>sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9</code>.
    57          Layers must be packed and unpacked reproducibly to avoid changing the
    58          layer ID, for example by using tar-split to save the tar headers. Note
    59          that the digest used as the layer ID is taken over an uncompressed
    60          version of the tar.
    61      </dd>
    62      <dt>
    63          Layer ChainID
    64      </dt>
    65      <dd>
    66          For convenience, it is sometimes useful to refer to a stack of layers
    67          with a single identifier. This is called a <code>ChainID</code>. For a
    68          single layer (or the layer at the bottom of a stack), the
    69          <code>ChainID</code> is equal to the layer's <code>DiffID</code>.
    70          Otherwise the <code>ChainID</code> is given by the formula:
    71          <code>ChainID(layerN) = SHA256hex(ChainID(layerN-1) + " " + DiffID(layerN))</code>.
    72      </dd>
    73      <dt>
    74          ImageID <a name="id_desc"></a>
    75      </dt>
    76      <dd>
    77          Each image's ID is given by the SHA256 hash of its configuration JSON. It is 
    78          represented as a hexadecimal encoding of 256 bits, e.g.,
    79          <code>sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9</code>.
    80          Since the configuration JSON that gets hashed references hashes of each
    81          layer in the image, this formulation of the ImageID makes images
    82          content-addressable.
    83      </dd>
    84      <dt>
    85          Tag
    86      </dt>
    87      <dd>
    88          A tag serves to map a descriptive, user-given name to any single image
    89          ID. Tag values are limited to the set of characters
    90          <code>[a-zA-Z0-9_.-]</code>, except they may not start with a <code>.</code>
    91          or <code>-</code> character. Tags are limited to 128 characters.
    92      </dd>
    93      <dt>
    94          Repository
    95      </dt>
    96      <dd>
    97          A collection of tags grouped under a common prefix (the name component
    98          before <code>:</code>). For example, in an image tagged with the name
    99          <code>my-app:3.1.4</code>, <code>my-app</code> is the <i>Repository</i>
   100          component of the name. A repository name is made up of slash-separated
   101          name components, optionally prefixed by a DNS hostname. The hostname
   102          must comply with standard DNS rules, but may not contain
   103          <code>_</code> characters. If a hostname is present, it may optionally
   104          be followed by a port number in the format <code>:8080</code>.
   105          Name components may contain lowercase characters, digits, and
   106          separators. A separator is defined as a period, one or two underscores,
   107          or one or more dashes. A name component may not start or end with
   108          a separator.
   109      </dd>
   110  </dl>
   111  
   112  ## Image JSON Description
   113  
   114  Here is an example image JSON file:
   115  
   116  ```
   117  {  
   118      "created": "2015-10-31T22:22:56.015925234Z",
   119      "author": "Alyssa P. Hacker &ltalyspdev@example.com&gt",
   120      "architecture": "amd64",
   121      "os": "linux",
   122      "config": {
   123          "User": "alice",
   124          "Memory": 2048,
   125          "MemorySwap": 4096,
   126          "CpuShares": 8,
   127          "ExposedPorts": {  
   128              "8080/tcp": {}
   129          },
   130          "Env": [  
   131              "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
   132              "FOO=docker_is_a_really",
   133              "BAR=great_tool_you_know"
   134          ],
   135          "Entrypoint": [
   136              "/bin/my-app-binary"
   137          ],
   138          "Cmd": [
   139              "--foreground",
   140              "--config",
   141              "/etc/my-app.d/default.cfg"
   142          ],
   143          "Volumes": {
   144              "/var/job-result-data": {},
   145              "/var/log/my-app-logs": {},
   146          },
   147          "WorkingDir": "/home/alice",
   148      },
   149      "rootfs": {
   150        "diff_ids": [
   151          "sha256:c6f988f4874bb0add23a778f753c65efe992244e148a1d2ec2a8b664fb66bbd1",
   152          "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
   153        ],
   154        "type": "layers"
   155      },
   156      "history": [
   157        {
   158          "created": "2015-10-31T22:22:54.690851953Z",
   159          "created_by": "/bin/sh -c #(nop) ADD file:a3bc1e842b69636f9df5256c49c5374fb4eef1e281fe3f282c65fb853ee171c5 in /"
   160        },
   161        {
   162          "created": "2015-10-31T22:22:55.613815829Z",
   163          "created_by": "/bin/sh -c #(nop) CMD [\"sh\"]",
   164          "empty_layer": true
   165        }
   166      ]
   167  }
   168  ```
   169  
   170  Note that image JSON files produced by Docker don't contain formatting
   171  whitespace. It has been added to this example for clarity.
   172  
   173  ### Image JSON Field Descriptions
   174  
   175  <dl>
   176      <dt>
   177          created <code>string</code>
   178      </dt>
   179      <dd>
   180          ISO-8601 formatted combined date and time at which the image was
   181          created.
   182      </dd>
   183      <dt>
   184          author <code>string</code>
   185      </dt>
   186      <dd>
   187          Gives the name and/or email address of the person or entity which
   188          created and is responsible for maintaining the image.
   189      </dd>
   190      <dt>
   191          architecture <code>string</code>
   192      </dt>
   193      <dd>
   194          The CPU architecture which the binaries in this image are built to run
   195          on. Possible values include:
   196          <ul>
   197              <li>386</li>
   198              <li>amd64</li>
   199              <li>arm</li>
   200          </ul>
   201          More values may be supported in the future and any of these may or may
   202          not be supported by a given container runtime implementation.
   203      </dd>
   204      <dt>
   205          os <code>string</code>
   206      </dt>
   207      <dd>
   208          The name of the operating system which the image is built to run on.
   209          Possible values include:
   210          <ul>
   211              <li>darwin</li>
   212              <li>freebsd</li>
   213              <li>linux</li>
   214          </ul>
   215          More values may be supported in the future and any of these may or may
   216          not be supported by a given container runtime implementation.
   217      </dd>
   218      <dt>
   219          config <code>struct</code>
   220      </dt>
   221      <dd>
   222          The execution parameters which should be used as a base when running a
   223          container using the image. This field can be <code>null</code>, in
   224          which case any execution parameters should be specified at creation of
   225          the container.
   226          <h4>Container RunConfig Field Descriptions</h4>
   227          <dl>
   228              <dt>
   229                  User <code>string</code>
   230              </dt>
   231              <dd>
   232                  <p>The username or UID which the process in the container should
   233                  run as. This acts as a default value to use when the value is
   234                  not specified when creating a container.</p>
   235                  <p>All of the following are valid:</p>
   236                  <ul>
   237                      <li><code>user</code></li>
   238                      <li><code>uid</code></li>
   239                      <li><code>user:group</code></li>
   240                      <li><code>uid:gid</code></li>
   241                      <li><code>uid:group</code></li>
   242                      <li><code>user:gid</code></li>
   243                  </ul>
   244                  <p>If <code>group</code>/<code>gid</code> is not specified, the
   245                  default group and supplementary groups of the given
   246                  <code>user</code>/<code>uid</code> in <code>/etc/passwd</code>
   247                  from the container are applied.</p>
   248              </dd>
   249              <dt>
   250                  Memory <code>integer</code>
   251              </dt>
   252              <dd>
   253                  Memory limit (in bytes). This acts as a default value to use
   254                  when the value is not specified when creating a container.
   255              </dd>
   256              <dt>
   257                  MemorySwap <code>integer</code>
   258              </dt>
   259              <dd>
   260                  Total memory usage (memory + swap); set to <code>-1</code> to
   261                  disable swap. This acts as a default value to use when the
   262                  value is not specified when creating a container.
   263              </dd>
   264              <dt>
   265                  CpuShares <code>integer</code>
   266              </dt>
   267              <dd>
   268                  CPU shares (relative weight vs. other containers). This acts as
   269                  a default value to use when the value is not specified when
   270                  creating a container.
   271              </dd>
   272              <dt>
   273                  ExposedPorts <code>struct</code>
   274              </dt>
   275              <dd>
   276                  A set of ports to expose from a container running this image.
   277                  This JSON structure value is unusual because it is a direct
   278                  JSON serialization of the Go type
   279                  <code>map[string]struct{}</code> and is represented in JSON as
   280                  an object mapping its keys to an empty object. Here is an
   281                  example:
   282  <pre>{
   283      "8080": {},
   284      "53/udp": {},
   285      "2356/tcp": {}
   286  }</pre>
   287                  Its keys can be in the format of:
   288                  <ul>
   289                      <li>
   290                          <code>"port/tcp"</code>
   291                      </li>
   292                      <li>
   293                          <code>"port/udp"</code>
   294                      </li>
   295                      <li>
   296                          <code>"port"</code>
   297                      </li>
   298                  </ul>
   299                  with the default protocol being <code>"tcp"</code> if not
   300                  specified. These values act as defaults and are merged with
   301                  any specified when creating a container.
   302              </dd>
   303              <dt>
   304                  Env <code>array of strings</code>
   305              </dt>
   306              <dd>
   307                  Entries are in the format of <code>VARNAME="var value"</code>.
   308                  These values act as defaults and are merged with any specified
   309                  when creating a container.
   310              </dd>
   311              <dt>
   312                  Entrypoint <code>array of strings</code>
   313              </dt>
   314              <dd>
   315                  A list of arguments to use as the command to execute when the
   316                  container starts. This value acts as a  default and is replaced
   317                  by an entrypoint specified when creating a container.
   318              </dd>
   319              <dt>
   320                  Cmd <code>array of strings</code>
   321              </dt>
   322              <dd>
   323                  Default arguments to the entry point of the container. These
   324                  values act as defaults and are replaced with any specified when
   325                  creating a container. If an <code>Entrypoint</code> value is
   326                  not specified, then the first entry of the <code>Cmd</code>
   327                  array should be interpreted as the executable to run.
   328              </dd>
   329              <dt>
   330                  Healthcheck <code>struct</code>
   331              </dt>
   332              <dd>
   333                  A test to perform to determine whether the container is healthy.
   334                  Here is an example:
   335  <pre>{
   336    "Test": [
   337        "CMD-SHELL",
   338        "/usr/bin/check-health localhost"
   339    ],
   340    "Interval": 30000000000,
   341    "Timeout": 10000000000,
   342    "Retries": 3
   343  }</pre>
   344                  The object has the following fields.
   345                  <dl>
   346                      <dt>
   347                          Test <code>array of strings</code>
   348                      </dt>
   349                      <dd>
   350                          The test to perform to check that the container is healthy.
   351                          The options are:
   352                          <ul>
   353                              <li><code>[]</code> : inherit healthcheck from base image</li>
   354                              <li><code>["NONE"]</code> : disable healthcheck</li>
   355                              <li><code>["CMD", arg1, arg2, ...]</code> : exec arguments directly</li>
   356                              <li><code>["CMD-SHELL", command]</code> : run command with system's default shell</li>
   357                          </ul>
   358                          The test command should exit with a status of 0 if the container is healthy,
   359                          or with 1 if it is unhealthy.
   360                      </dd>
   361                      <dt>
   362                          Interval <code>integer</code>
   363                      </dt>
   364                      <dd>
   365                          Number of nanoseconds to wait between probe attempts.
   366                      </dd>
   367                      <dt>
   368                          Timeout <code>integer</code>
   369                      </dt>
   370                      <dd>
   371                          Number of nanoseconds to wait before considering the check to have hung.
   372                      </dd>
   373                      <dt>
   374                          Retries <code>integer</code>
   375                      <dt>
   376                      <dd>
   377                          The number of consecutive failures needed to consider a container as unhealthy.
   378                      </dd>
   379                  </dl>
   380                  In each case, the field can be omitted to indicate that the
   381                  value should be inherited from the base layer. These values act
   382                  as defaults and are merged with any specified when creating a
   383                  container.
   384              </dd>
   385              <dt>
   386                  Volumes <code>struct</code>
   387              </dt>
   388              <dd>
   389                  A set of directories which should be created as data volumes in
   390                  a container running this image. This JSON structure value is
   391                  unusual because it is a direct JSON serialization of the Go
   392                  type <code>map[string]struct{}</code> and is represented in
   393                  JSON as an object mapping its keys to an empty object. Here is
   394                  an example:
   395  <pre>{
   396      "/var/my-app-data/": {},
   397      "/etc/some-config.d/": {},
   398  }</pre>
   399              </dd>
   400              <dt>
   401                  WorkingDir <code>string</code>
   402              </dt>
   403              <dd>
   404                  Sets the current working directory of the entry point process
   405                  in the container. This value acts as a default and is replaced
   406                  by a working directory specified when creating a container.
   407              </dd>
   408          </dl>
   409      </dd>
   410      <dt>
   411          rootfs <code>struct</code>
   412      </dt>
   413      <dd>
   414          The rootfs key references the layer content addresses used by the
   415          image. This makes the image config hash depend on the filesystem hash.
   416          rootfs has two subkeys:
   417          <ul>
   418            <li>
   419              <code>type</code> is usually set to <code>layers</code>.
   420            </li>
   421            <li>
   422              <code>diff_ids</code> is an array of layer content hashes (<code>DiffIDs</code>), in order from bottom-most to top-most.
   423            </li>
   424          </ul>
   425          Here is an example rootfs section:
   426  <pre>"rootfs": {
   427    "diff_ids": [
   428      "sha256:c6f988f4874bb0add23a778f753c65efe992244e148a1d2ec2a8b664fb66bbd1",
   429      "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
   430      "sha256:13f53e08df5a220ab6d13c58b2bf83a59cbdc2e04d0a3f041ddf4b0ba4112d49"
   431    ],
   432    "type": "layers"
   433  }</pre>
   434      </dd>
   435      <dt>
   436          history <code>struct</code>
   437      </dt>
   438      <dd>
   439          <code>history</code> is an array of objects describing the history of
   440          each layer. The array is ordered from bottom-most layer to top-most
   441          layer. The object has the following fields.
   442          <ul>
   443            <li>
   444              <code>created</code>: Creation time, expressed as a ISO-8601 formatted
   445              combined date and time
   446            </li>
   447            <li>
   448              <code>author</code>: The author of the build point
   449            </li>
   450            <li>
   451              <code>created_by</code>: The command which created the layer
   452            </li>
   453            <li>
   454              <code>comment</code>: A custom message set when creating the layer
   455            </li>
   456            <li>
   457              <code>empty_layer</code>: This field is used to mark if the history
   458              item created a filesystem diff. It is set to true if this history
   459              item doesn't correspond to an actual layer in the rootfs section
   460              (for example, a command like ENV which results in no change to the
   461              filesystem).
   462            </li>
   463          </ul>
   464          Here is an example history section:
   465  <pre>"history": [
   466    {
   467      "created": "2015-10-31T22:22:54.690851953Z",
   468      "created_by": "/bin/sh -c #(nop) ADD file:a3bc1e842b69636f9df5256c49c5374fb4eef1e281fe3f282c65fb853ee171c5 in /"
   469    },
   470    {
   471      "created": "2015-10-31T22:22:55.613815829Z",
   472      "created_by": "/bin/sh -c #(nop) CMD [\"sh\"]",
   473      "empty_layer": true
   474    }
   475  ]</pre>
   476      </dd>
   477  </dl>
   478  
   479  Any extra fields in the Image JSON struct are considered implementation
   480  specific and should be ignored by any implementations which are unable to
   481  interpret them.
   482  
   483  ## Creating an Image Filesystem Changeset
   484  
   485  An example of creating an Image Filesystem Changeset follows.
   486  
   487  An image root filesystem is first created as an empty directory. Here is the
   488  initial empty directory structure for the a changeset using the
   489  randomly-generated directory name `c3167915dc9d` ([actual layer DiffIDs are
   490  generated based on the content](#id_desc)).
   491  
   492  ```
   493  c3167915dc9d/
   494  ```
   495  
   496  Files and directories are then created:
   497  
   498  ```
   499  c3167915dc9d/
   500      etc/
   501          my-app-config
   502      bin/
   503          my-app-binary
   504          my-app-tools
   505  ```
   506  
   507  The `c3167915dc9d` directory is then committed as a plain Tar archive with
   508  entries for the following files:
   509  
   510  ```
   511  etc/my-app-config
   512  bin/my-app-binary
   513  bin/my-app-tools
   514  ```
   515  
   516  To make changes to the filesystem of this container image, create a new
   517  directory, such as `f60c56784b83`, and initialize it with a snapshot of the
   518  parent image's root filesystem, so that the directory is identical to that
   519  of `c3167915dc9d`. NOTE: a copy-on-write or union filesystem can make this very
   520  efficient:
   521  
   522  ```
   523  f60c56784b83/
   524      etc/
   525          my-app-config
   526      bin/
   527          my-app-binary
   528          my-app-tools
   529  ```
   530  
   531  This example change is going add a configuration directory at `/etc/my-app.d`
   532  which contains a default config file. There's also a change to the
   533  `my-app-tools` binary to handle the config layout change. The `f60c56784b83`
   534  directory then looks like this:
   535  
   536  ```
   537  f60c56784b83/
   538      etc/
   539          my-app.d/
   540              default.cfg
   541      bin/
   542          my-app-binary
   543          my-app-tools
   544  ```
   545  
   546  This reflects the removal of `/etc/my-app-config` and creation of a file and
   547  directory at `/etc/my-app.d/default.cfg`. `/bin/my-app-tools` has also been
   548  replaced with an updated version. Before committing this directory to a
   549  changeset, because it has a parent image, it is first compared with the
   550  directory tree of the parent snapshot, `f60c56784b83`, looking for files and
   551  directories that have been added, modified, or removed. The following changeset
   552  is found:
   553  
   554  ```
   555  Added:      /etc/my-app.d/default.cfg
   556  Modified:   /bin/my-app-tools
   557  Deleted:    /etc/my-app-config
   558  ```
   559  
   560  A Tar Archive is then created which contains *only* this changeset: The added
   561  and modified files and directories in their entirety, and for each deleted item
   562  an entry for an empty file at the same location but with the basename of the
   563  deleted file or directory prefixed with `.wh.`. The filenames prefixed with
   564  `.wh.` are known as "whiteout" files. NOTE: For this reason, it is not possible
   565  to create an image root filesystem which contains a file or directory with a
   566  name beginning with `.wh.`. The resulting Tar archive for `f60c56784b83` has
   567  the following entries:
   568  
   569  ```
   570  /etc/my-app.d/default.cfg
   571  /bin/my-app-tools
   572  /etc/.wh.my-app-config
   573  ```
   574  
   575  Any given image is likely to be composed of several of these Image Filesystem
   576  Changeset tar archives.
   577  
   578  ## Combined Image JSON + Filesystem Changeset Format
   579  
   580  There is also a format for a single archive which contains complete information
   581  about an image, including:
   582  
   583   - repository names/tags
   584   - image configuration JSON file
   585   - all tar archives of each layer filesystem changesets
   586  
   587  For example, here's what the full archive of `library/busybox` is (displayed in
   588  `tree` format):
   589  
   590  ```
   591  .
   592  ├── 47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb.json
   593  ├── 5f29f704785248ddb9d06b90a11b5ea36c534865e9035e4022bb2e71d4ecbb9a
   594  │   ├── VERSION
   595  │   ├── json
   596  │   └── layer.tar
   597  ├── a65da33792c5187473faa80fa3e1b975acba06712852d1dea860692ccddf3198
   598  │   ├── VERSION
   599  │   ├── json
   600  │   └── layer.tar
   601  ├── manifest.json
   602  └── repositories
   603  ```
   604  
   605  There is a directory for each layer in the image. Each directory is named with
   606  a 64 character hex name that is deterministically generated from the layer
   607  information. These names are not necessarily layer DiffIDs or ChainIDs. Each of
   608  these directories contains 3 files:
   609  
   610   * `VERSION` - The schema version of the `json` file
   611   * `json` - The legacy JSON metadata for an image layer. In this version of
   612      the image specification, layers don't have JSON metadata, but in
   613      [version 1](v1.md), they did. A file is created for each layer in the
   614      v1 format for backward compatibility.
   615   * `layer.tar` - The Tar archive of the filesystem changeset for an image
   616     layer.
   617  
   618  Note that this directory layout is only important for backward compatibility.
   619  Current implementations use the paths specified in `manifest.json`.
   620  
   621  The content of the `VERSION` files is simply the semantic version of the JSON
   622  metadata schema:
   623  
   624  ```
   625  1.0
   626  ```
   627  
   628  The `repositories` file is another JSON file which describes names/tags:
   629  
   630  ```
   631  {  
   632      "busybox":{  
   633          "latest":"5f29f704785248ddb9d06b90a11b5ea36c534865e9035e4022bb2e71d4ecbb9a"
   634      }
   635  }
   636  ```
   637  
   638  Every key in this object is the name of a repository, and maps to a collection
   639  of tag suffixes. Each tag maps to the ID of the image represented by that tag.
   640  This file is only used for backwards compatibility. Current implementations use
   641  the `manifest.json` file instead.
   642  
   643  The `manifest.json` file provides the image JSON for the top-level image, and
   644  optionally for parent images that this image was derived from. It consists of
   645  an array of metadata entries:
   646  
   647  ```
   648  [
   649    {
   650      "Config": "47bcc53f74dc94b1920f0b34f6036096526296767650f223433fe65c35f149eb.json",
   651      "RepoTags": ["busybox:latest"],
   652      "Layers": [
   653        "a65da33792c5187473faa80fa3e1b975acba06712852d1dea860692ccddf3198/layer.tar",
   654        "5f29f704785248ddb9d06b90a11b5ea36c534865e9035e4022bb2e71d4ecbb9a/layer.tar"
   655      ]
   656    }
   657  ]
   658  ```
   659  
   660  There is an entry in the array for each image.
   661  
   662  The `Config` field references another file in the tar which includes the image
   663  JSON for this image.
   664  
   665  The `RepoTags` field lists references pointing to this image.
   666  
   667  The `Layers` field points to the filesystem changeset tars.
   668  
   669  An optional `Parent` field references the imageID of the parent image. This
   670  parent must be part of the same `manifest.json` file.
   671  
   672  This file shouldn't be confused with the distribution manifest, used to push
   673  and pull images.
   674  
   675  Generally, implementations that support this version of the spec will use
   676  the `manifest.json` file if available, and older implementations will use the
   677  legacy `*/json` files and `repositories`.