PEP 825: define consistency requirements more explicitly

peps/pep-0825.rst

@@ -207,11 +207,8 @@ The version numbers starting with zero are reserved for drafts and MUST
 NOT be used in production. Once the proposal is complete, the latest
 draft will be promoted to version ``1.0.0``.
 
-The top-level keys are described in the subsequent sections.
-
-Except where noted otherwise, variant metadata is project-scoped. It is
-copied into individual variant wheels, but it MUST be consistent across
-different variant wheels created for a particular project version.
+The top-level keys, as well as their scope and consistency requirements,
+are described in the subsequent sections.
 
 
 Schema
@@ -244,6 +241,12 @@ The following key is REQUIRED:
   wheels for a given package version, ordered in decreasing priority.
   This list MUST contain all namespaces used in variant properties.
 
+Default priorities are defined at the project scope. Different wheels
+SHOULD use the same value. However, appending additional namespaces is
+permitted. The metadata is considered consistent if the longer list
+starts with the elements of the shorter list, in order. In this case,
+combining the metadata MUST result in the longer list being used.
+
 
 Variants
 ''''''''
@@ -258,6 +261,10 @@ level keys are namespaces, the third level are feature names, and the
 third level values are sets of feature values, converted to lists,
 sorted lexically.
 
+For the metadata to be consistent, the same keys MUST always correspond
+to the same values. When combining metadata, the resulting ``variants``
+dictionary MUST be an union of all the input dictionaries.
+
 
 Example
 '''''''
@@ -319,10 +326,7 @@ the ``variants`` object is index-scope and it MUST list all variants
 available on the package index for the package version in question. The
 tools MUST ensure that the variant metadata across multiple variant
 wheels of the same package version and the index-level metadata file is
-consistent. They MAY require that keys other than ``variants`` have
-exactly the same values, or they may carefully merge their values,
-provided that no conflicting information is introduced, and the result
-is the same irrespective of the order in which the wheels are processed.
+consistent, as defined in sections corresponding to the specific keys.
 
 This file SHOULD NOT be considered immutable and MAY be updated in a
 backward compatible way at any point (e.g. when adding a new variant).
@@ -797,8 +801,8 @@ source provides compatible variant wheels, those variants can be
 selected ahead of non-variant wheels, as generally variant wheels are
 preferred over non-variant wheels. If multiple sources provide
 compatible variants, their metadata can be combined unambiguously only
-when the metadata is consistent as specified in the `index-level
-metadata`_ section.
+when the metadata is consistent as specified in the sections
+corresponding to the individual metadata keys.
 
 When metadata cannot be combined unambiguously, there is no uniquely
 correct global ordering. Valid tool-specific choices include: