Replace "notes" field with "errata", "directions", and "documentation"

opws · Nov 14, 2017 · c492cbc · c492cbc
1 parent bc91251
commit c492cbc
Show file tree

Hide file tree

Showing 6 changed files with 134 additions and 0 deletions.
diff --git a/draft/docs/descriptions.md b/draft/docs/descriptions.md
@@ -9,3 +9,17 @@ An English (or en_US) version of any note should be included along with the targ
 ## Description Lists
 
 In properties that use arrays of description objects, such as `password.value.must`, each item should be *as granular as possible*, so that each statement can be traslated separately, and new statements, or changes to existing statements, can be added or removed independently.
+
+## Places where description lists are used
+
+### "Must" and "Must Not" rules
+
+See [the documentation on rules](rules.md).
+
+### Errata
+
+Errata describes any instances where a site's rules or behavior are inconsistent, either with documented / stated rules, or with other parts of the site.
+
+### Directions
+
+Anything that can have a URL can have a list of directions explaining how to get to that thing after visiting the URL (or, absent a URL, how to approximate the action).
diff --git a/draft/docs/passwords.md b/draft/docs/passwords.md
@@ -113,3 +113,11 @@ Sites where tokens *do not expire* after use, meaning that they can then be *reu
 The URL for chaning the user's password is profiled as `password.change.url`, following the [documentation on URLs](urls.md).
 
 The form for chaning the user's password is profiled as `password.change.form`, following the [documentation on forms](forms.md).
+
+## Password errata
+
+Passwords may have descriptions for errata (as `password.errata`), following the [documentation on descriptions](descriptions.md).
+
+## Password documentation
+
+Profiles may have a list of URLs for pages documenting the rules around passwords (as `password.documentation`), following the [documentation on URLs](urls.md).
diff --git a/draft/docs/profiles.md b/draft/docs/profiles.md
@@ -18,6 +18,10 @@ A "username" is defined as any user-controlled string identifier for the account
 
 Rules for the format of usernames are documented with `username.value` and `username.contents`, following the [documentation on rules](rules.md).
 
+Profiles may have a list of URLs for pages documenting the rules around usernames (as `username.documentation`), following the [documentation on URLs](urls.md).
+
+Usernames may have descriptions for errata (as `username.errata`), following the [documentation on descriptions](descriptions.md).
+
 ### Username reminders
 
 Some sites have a facility, separate from requesting a password reset, for requesting a message containing the *username* attached to an email address. These facilities are documented under `username.reminder`.

diff --git a/draft/docs/urls.md b/draft/docs/urls.md
@@ -19,3 +19,7 @@ For pages that contain several sections, only one of which is pertinent to the l
 ## Variables
 
 When URLs include a variable (such as a username), the URL will be separated by spaces and plusses (for concatenation).
+
+## Directions
+
+Anything with a URL may also have described directions for what to do after visiting that URL (as a `.directions` list as a sibling of `.url`), following the [documentation on descriptions](descriptions.md).
diff --git a/draft/profiles.copld.yaml b/draft/profiles.copld.yaml
@@ -266,6 +266,9 @@ definitions:
       url:
         $ref: "#/definitions/urlish"
 
+      directions:
+        $ref: "#/definitions/desclist"
+
       form.:
 
         account:
@@ -477,6 +480,9 @@ properties:
 
         change.:
 
+          directions:
+            $ref: "#/definitions/desclist"
+
           form.:
 
             challenge:
@@ -622,11 +628,17 @@ properties:
         url:
           $ref: "#/definitions/urlish"
 
+        directions:
+          $ref: "#/definitions/desclist"
+
     change.:
 
       url:
         $ref: "#/definitions/urlish"
 
+      directions:
+        $ref: "#/definitions/desclist"
+
       before.:
 
         form.:
@@ -668,6 +680,15 @@ properties:
           - unchanged
           - logout
 
+    documentation:
+      type: array
+      minItems: 1
+      items:
+        $ref: "#/definitions/urlish"
+
+    errata:
+      $ref: "#/definitions/desclist"
+
   username.:
 
     value:
@@ -683,6 +704,9 @@ properties:
         url:
           $ref: "#/definitions/urlish"
 
+        directions:
+          $ref: "#/definitions/desclist"
+
         form.:
 
           account:
@@ -724,6 +748,9 @@ properties:
       url:
         $ref: "#/definitions/urlish"
 
+      directions:
+        $ref: "#/definitions/desclist"
+
       before.:
 
         form.:
@@ -751,6 +778,15 @@ properties:
           password:
             $ref: "#/definitions/formfield"
 
+    documentation:
+      type: array
+      minItems: 1
+      items:
+        $ref: "#/definitions/urlish"
+
+    errata:
+      $ref: "#/definitions/desclist"
+
   legal.:
 
     documents:
@@ -768,11 +804,17 @@ properties:
           url:
             $ref: "#/definitions/urlish"
 
+          directions:
+            $ref: "#/definitions/desclist"
+
   registration.:
 
     url:
       $ref: "#/definitions/urlish"
 
+    directions:
+      $ref: "#/definitions/desclist"
+
     form.:
 
       firstname:
@@ -823,6 +865,9 @@ properties:
     url:
       $ref: "#/definitions/urlish"
 
+    directions:
+      $ref: "#/definitions/desclist"
+
     form.:
 
       account:
@@ -861,13 +906,19 @@ properties:
       url:
         $ref: "#/definitions/urlish"
 
+      directions:
+        $ref: "#/definitions/desclist"
+
   report.:
 
     breach.:
 
       url:
         $ref: "#/definitions/urlish"
 
+      directions:
+        $ref: "#/definitions/desclist"
+
   challenge.:
 
     answers.:

diff --git a/draft/profiles.json b/draft/profiles.json
@@ -301,6 +301,9 @@
         "url": {
           "$ref": "#/definitions/urlish"
         },
+        "directions": {
+          "$ref": "#/definitions/desclist"
+        },
         "form": {
           "type": "object",
           "properties": {
@@ -586,6 +589,9 @@
                 "change": {
                   "type": "object",
                   "properties": {
+                    "directions": {
+                      "$ref": "#/definitions/desclist"
+                    },
                     "form": {
                       "type": "object",
                       "properties": {
@@ -799,6 +805,9 @@
               "properties": {
                 "url": {
                   "$ref": "#/definitions/urlish"
+                },
+                "directions": {
+                  "$ref": "#/definitions/desclist"
                 }
               },
               "minimumProperties": 1
@@ -812,6 +821,9 @@
             "url": {
               "$ref": "#/definitions/urlish"
             },
+            "directions": {
+              "$ref": "#/definitions/desclist"
+            },
             "before": {
               "type": "object",
               "properties": {
@@ -885,6 +897,16 @@
             }
           },
           "minimumProperties": 1
+        },
+        "documentation": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/urlish"
+          }
+        },
+        "errata": {
+          "$ref": "#/definitions/desclist"
         }
       },
       "minimumProperties": 1
@@ -907,6 +929,9 @@
                 "url": {
                   "$ref": "#/definitions/urlish"
                 },
+                "directions": {
+                  "$ref": "#/definitions/desclist"
+                },
                 "form": {
                   "type": "object",
                   "properties": {
@@ -969,6 +994,9 @@
             "url": {
               "$ref": "#/definitions/urlish"
             },
+            "directions": {
+              "$ref": "#/definitions/desclist"
+            },
             "before": {
               "type": "object",
               "properties": {
@@ -1022,6 +1050,16 @@
             }
           },
           "minimumProperties": 1
+        },
+        "documentation": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/urlish"
+          }
+        },
+        "errata": {
+          "$ref": "#/definitions/desclist"
         }
       },
       "minimumProperties": 1
@@ -1045,6 +1083,9 @@
               },
               "url": {
                 "$ref": "#/definitions/urlish"
+              },
+              "directions": {
+                "$ref": "#/definitions/desclist"
               }
             }
           }
@@ -1058,6 +1099,9 @@
         "url": {
           "$ref": "#/definitions/urlish"
         },
+        "directions": {
+          "$ref": "#/definitions/desclist"
+        },
         "form": {
           "type": "object",
           "properties": {
@@ -1125,6 +1169,9 @@
         "url": {
           "$ref": "#/definitions/urlish"
         },
+        "directions": {
+          "$ref": "#/definitions/desclist"
+        },
         "form": {
           "type": "object",
           "properties": {
@@ -1185,6 +1232,9 @@
           "properties": {
             "url": {
               "$ref": "#/definitions/urlish"
+            },
+            "directions": {
+              "$ref": "#/definitions/desclist"
             }
           },
           "minimumProperties": 1
@@ -1200,6 +1250,9 @@
           "properties": {
             "url": {
               "$ref": "#/definitions/urlish"
+            },
+            "directions": {
+              "$ref": "#/definitions/desclist"
             }
           },
           "minimumProperties": 1