From fbd901422f939bb4613d79f930c6614d26058520 Mon Sep 17 00:00:00 2001
From: Vladimir Diaz <vladimir.v.diaz@gmail.com>
Date: Thu, 25 Aug 2016 07:02:00 -0400
Subject: [PATCH] Update tuf-spec.txt

Address issue #364.  The specification includes examples of metadata with version numbers listed, but the description of snapshot.json does not.  The `custom` field is listed only in targets metadata.
---
 docs/tuf-spec.txt | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/docs/tuf-spec.txt b/docs/tuf-spec.txt
index faa07f5a..9efd1928 100644
--- a/docs/tuf-spec.txt
+++ b/docs/tuf-spec.txt
@@ -381,8 +381,9 @@ Version 1.0 (Draft)
 
     /snapshot.json
 
-         Signed by the snapshot role's keys.  Lists hashes and sizes of all
-         metadata files other than timestamp.json.
+         Signed by the snapshot role's keys.  Lists the version numbers of all
+         metadata files other than timestamp.json.  For the root role, the
+         hash(es), size, and version number are listed.
 
     /targets.json
 
@@ -391,9 +392,10 @@ Version 1.0 (Draft)
 
     /timestamp.json
 
-         Signed by the timestamp role's keys.  Lists hashes and size of the
-         snapshot file.  This is the first and potentially only file that needs
-         to be downloaded when clients poll for the existence of updates.
+         Signed by the timestamp role's keys.  Lists hash(es), size, and version
+         number of the snapshot file.  This is the first and potentially only
+         file that needs to be downloaded when clients poll for the existence
+         of updates.
 
     /mirrors.json (optional)
 
@@ -630,9 +632,10 @@ Version 1.0 (Draft)
 
 4.4. File formats: snapshot.json
 
-   The snapshot.json file is signed by the snapshot role.  It lists hashes and
-   sizes of all metadata on the repository, excluding timestamp.json and
-   mirrors.json.
+   The snapshot.json file is signed by the snapshot role.  It lists the version
+   numbers of all metadata on the repository, excluding timestamp.json and
+   mirrors.json.  For the root role, the hash(es), size, and version number
+   are listed.
 
    The format of snapshot.json is as follows:
 
@@ -647,16 +650,18 @@ Version 1.0 (Draft)
      { METAPATH : {
            "length" : LENGTH,
            "hashes" : HASHES,
-           ("custom" : { ... }) }
+           "version" : VERSION }
        , ...
      }
 
    METAPATH is the the metadata file's path on the repository relative to the
    metadata base URL.
    
-   The HASHES and LENGTH are the hashes and length of the file.  LENGTH is an
-   integer.  HASHES is a dictionary that specifies one or more hashes, including
-   the cryptographic hash function.  For example: { "sha256": HASH, ... }
+   The HASHES and LENGTH are the hashes and length of the file, both of which
+   are only specified for the root file.  VERSION is listed for the root file
+   and all other roles available on the repository.  LENGTH is an integer.
+   HASHES is a dictionary that specifies one or more hashes, including the
+   cryptographic hash function.  For example: { "sha256": HASH, ... }.
 
    A signed snapshot.json example file: