Clarify optional attributes (#165)

* Clarify that delegations are optional

Nowhere in the spec, we clarify that "delegations" is an optional field
in the targets metadata file.
This is a possible reason why (at the time of writing this commit) in
the TUF python reference implementation "delegations" is still a
required field.

Signed-off-by: Martin Vrachev <[email protected]>

* Make CONSISTENT_SNAPSHOT optional

From chapter 6.2.1 in the tuf specification (version 1.019)
"Finally, the root metadata should write the Boolean
"consistent_snapshot" attribute at the root level of its keys of
attributes. If consistent snapshots are not written by the repository,
then the attribute may either be left unspecified or be set
to the False value. Otherwise, it must be set to the True value."

The above implies that there could be repositories with root metadata
without CONSISTENT_SNAPSHOT.
Clarify that, but phrase it so it's clear this should be included
in new implementations.

For context:
https://theupdateframework.github.io/specification/latest/index.html#writing-consistent-snapshots

Signed-off-by: Martin Vrachev <[email protected]>

* Clarify "paths" and "path_hash_prefixes"

Clarify "paths" and "path_hash_prefixes" in delegations, because
currently, it's not properly defined which of these options can be used
to create a valid target file:
- BOTH paths and path_hash_prefixes
- ONLY ONE of paths and path_hash_prefixes
- NONE of paths and path_hash_prefixes

With this change, I aim to define clearly that a valid target file will
contain ONLY ONE of them or NONE of them.

Signed-off-by: Martin Vrachev <[email protected]>

* Update tuf-spec.md

Co-authored-by: Trishank Karthik Kuppusamy <[email protected]>

Co-authored-by: Joshua Lock <[email protected]>
Co-authored-by: Trishank Karthik Kuppusamy <[email protected]>
Co-authored-by: Marina Moore <[email protected]>

Author: 4 people

tuf-spec.md

@@ -16,7 +16,7 @@ Boilerplate: copyright no, conformance no
 Local Boilerplate: header yes
 Markup Shorthands: css no, markdown yes
 Metadata Include: This version off, Abstract off
-Text Macro: VERSION 1.0.23
+Text Macro: VERSION 1.0.24
 </pre>
 
 Note: We strive to make the specification easy to implement, so if you come
@@ -692,9 +692,11 @@ The "signed" portion of <a>root.json</a> is as follows:
 
   : <dfn>CONSISTENT_SNAPSHOT</dfn>
   ::
-    A boolean indicating whether the repository supports
-    consistent snapshots.  Section [[#consistent-snapshots]] goes into more
-    detail on the consequences of enabling this setting on a repository.
+    An OPTIONAL boolean indicating whether the repository supports
+    consistent snapshots. This field is OPTIONAL for backwards compatibility with
+    old metadata. New implementations SHOULD include it. Section
+    [[#consistent-snapshots]] goes into more detail on the consequences of
+    enabling this setting on a repository.
 
   : <dfn for="role">VERSION</dfn>
   ::
@@ -980,7 +982,8 @@ as is described for the <a>root.json</a> file.
     <a>TARGETPATH</a>.  The application may use this information to guide
     download decisions.
 
-<dfn>DELEGATIONS</dfn> is an object whose format is the following:
+<dfn>DELEGATIONS</dfn> is an OPTIONAL object and if defined it has the following
+format:
 
 <pre highlight="json">
 {
@@ -1024,9 +1027,8 @@ as is described for the <a>root.json</a> file.
     package that are not made by the delegated party or its descendants to be
     ignored.
 
-In order to discuss target paths, a role MUST specify only one of the
-<a>"path_hash_prefixes"</a> or <a for="delegation-role">"paths"</a> attributes,
-each of which we discuss next.
+The <a>"path_hash_prefixes"</a> and <a for="delegation-role">"paths"</a>
+attributes are OPTIONAL, if used, exactly one of them should be set.
 
   : <dfn>"path_hash_prefixes"</dfn>
   ::