another pass at core Normative separation from informative

Signed-off-by: 2byrds <[email protected]>

spec/core.md

@@ -7,7 +7,8 @@
 1. Per the DID specification, this string MUST be lower case.
 1. The remainder of the DID, after the prefix, is the case-sensitive [[ref: method-specific identifier]]
 ([[ref: MSI]]) described [below](#method-specific-identifier).
-* > Note: when pronounced aloud, “webs” SHOULD become two syllables: the word “web” and the letter “s” (which stands for “secure”). Separating the final letter this way emphasizes that the method offers a security upgrade surpassing the one HTTPS gives to HTTP.
+
+> Note: when pronounced aloud, “webs” SHOULD become two syllables: the word “web” and the letter “s” (which stands for “secure”). Separating the final letter this way emphasizes that the method offers a security upgrade surpassing the one HTTPS gives to HTTP.
 
 ### Method-Specific Identifier
 
@@ -41,33 +42,26 @@ component of the path.
     ; ALPHA, DIGIT are standard ABNF primitives for alphabetic and numeric characters
     ```
 
-1. The formal rules describing valid [[ref: host]] syntax are described in
-[RFC1035], [RFC1123], and [RFC2181].
+1. The formal rules describing valid [[ref: host]] syntax are described in [RFC1035], [RFC1123], and [RFC2181].
 1. A port MAY be included and the colon MUST be percent encoded, like `%3a`, to prevent a conflict with paths.
 1. Directories and subdirectories MAY optionally be included, delimited by colons rather than slashes.
 
 1. The KERI AID is a unique identifier and MUST be derived from the inception event of a KERI identifier.
+
 > The inception event is the first item in the identifier's [[ref: KEL]]. The algorithm used to generate the AID depends on the type of AID. If the AID is transferable (supports key rotation) then the AID is generated by taking a cryptographic digest of the inception event of the KEL of the AID. If the AID is non-transferable (does not support key rotation) the AID is generated by taking a cryptographic digest of the first (and only) public key of the identifier. See the [[ref: KERI Fundamentals]] section for more details.
 
 > After the [[ref: host]] and optional path in a `did:webs` is a final path component, a colon and the AID. To be compatible with `did:web`, the AID is "just a path", the final (and perhaps only) path element. The presence of the required AID as a path element means that a `did:webs` always has a path,and so the "no path" version of a `did:web` that implicitly uses the `.well-known` folder is not supported by `did:webs`. Any `did:webs` can be expressed as a `did:web` but the inverse is not true--a `did:webs` MUST include an AID.
 
 ### Target System(s)
-
-> This method introduces an important nuance about the target system. In many DID methods, the target system equals a [[ref: verifiable data registry]] — besides publishing data, its security attributes make that data trustworthy. In this DID method, the target system's role is more limited. It is expected to serve data about the DID, and to follow acknowledged cybersecurity best practices to preserve good hygiene.
-mechanisms — the integrity checks built into the DID value, and the workings of
-
-> The authenticity of data is guaranteed by the DID value itself, in conjunction with a digitally signed data structure called a [[ref: KERI event stream]], which includes for a given AID its [[ref: key event log]] ([[ref:KEL]]) and [[ref: transaction event log]] ([[ref: TEL]]). These trustthe [[ref: KERI event stream]] — are defined by [[ref: KERI]].
-
-1. As with `did:web`, this method reads data from whatever web server is referenced when the [[ref: host]] portion of one of its DID is resolved.
-1. In fact, a `did:webs` can be resolved to a [[ref: DID document]] using a simple text transformation to an HTTPS URL in the same way as a `did:web`.
-1. By design, a `did:web` and `did:webs` with the same [[ref: method-specific identifier]] will return the same
+1. As with `did:web`, `did:webs` MUST read data from whatever web server is referenced when the [[ref: host]] portion of one of its DID is resolved.
+1. A `did:webs` DID MUST resolve to a [[ref: DID document]] using a simple text transformation to an HTTPS URL in the same way as a `did:web` DID.
+1. A `did:web` DID and `did:webs` DID with the same [[ref: method-specific identifier]] will return the same
 DID document, except for minor differences in the `id`, `controller`, and `alsoKnownAs` top-level properties that pertain to the identifiers themselves.
 1. As with `did:web`, the location of the [[ref: DID document]] MUST be determined by transforming the DID to an HTTPS URL as follows:
     1. Replace `did:webs` with `https://`
     1. Replace the "`:`"s in the method-specific identifier with path separators, "'/'"s
     1. Convert the optional port percent encoding ("`%3A`"`) to a colon if present.
     1. Append "`/did.json`" to the resulting string.
-
 1. A GET on that URL MUST return the DID document.
 1. The location of the [[ref: KERI event stream]] is determined by transforming the previous URL as follows:
     1. Replace the trailing "`/did.json`" with "`/keri.cesr`".
@@ -96,6 +90,8 @@ URLs, based on the examples from the [[ref: did:web Specification]], but with th
 
 
 ### AID controlled identifiers
+This section is non-normative.
+
 
 > Since an AID is a unique cryptographic identifier that is inseparably bound to the [[ref: KERI event stream]] it is associated with, any AIDs and any `did:webs` DIDs that have the same AID component have the same controller(s). [[ref: AID controlled identifiers]] may vary in how quickly they reflect the current identity information, DID document and [[ref: KERI event stream]]. Notably, as defined in section [Identifiers in a `did:webs` DID document](#identifiers-in-a-didwebs-did-document), the `id` property in the DID document will differ based on the web location of the DID document. As well, different versions of the DID document and [[ref: KERI event stream]] may reside in different locations depending on the replication capabilities of the controlling entity. If the [[ref: KERI event streams]] differ for `did:webs` DIDs with the same AID, the smaller [[ref: KERI event stream]] MUST be a prefix of the larger [[ref: KERI event stream]] (e.g., the only difference in the [[ref: KERI event streams]] being the extra events in one of the [[ref: KERI event streams]], not yet reflected in the other). If the [[ref: KERI event streams]] diverge from one other (e.g., one is not a subset of the other), both the [[ref: KERI event streams]] and the DIDs MUST be considered invalid.
 
@@ -106,16 +102,16 @@ URLs, based on the examples from the [[ref: did:web Specification]], but with th
 ### Handling Web Redirection
 
 1. A `did:webs` MAY be a "stable" (long-lasting) identifier that can be put into documents such as verifiable credentials, to be useful for a very long time -- generations.
-1. When a `did:webs` is updated for another location, its AID SHALL not change.
-    1. The same [[ref: KERI event stream]] is used to verify the DID document, with the only change being the designated aliases list reflecting the new location identifier.
+1. When a `did:webs` is updated for another location:
+    1. Its AID MUST not change.
+    1. The same [[ref: KERI event stream]] MUST be used to verify the DID document, with the only change being the designated aliases list reflecting the new location identifier.
     1. If a resolver can find a newly named DID that uses the same AID, and the [[ref: KERI event stream]] verifies the DID, then they have resolved the DID. 
 
-The following are the capabilities in `did:webs` to help in the face of resolution uncertainty.
-
-1. The `did:webs` DID is bound to other [[ref: designated aliases]] DID(s) that are anchored to the [[ref: KERI event stream]].
+The following reslution paths that `did:webs` identfiers SHALL leverage to help in the face of resolution uncertainty:
+1. The `did:webs` DID SHALL provide other [[ref: designated aliases]] DID(s) that are anchored to the [[ref: KERI event stream]].
 1. When a `did:webs` is permanently moved to some other location the resolver MAY redirect to any other `equivalentId` [[ref: designated aliases]].
-    1. The `id` in the DID document is set to the new location.
-    1. An `equivalentId` entry of the old location SHALL remain for historical purposes and anchored to the [[ref: KERI event stream]] using [[ref: designated aliases]]. See section [Use of `equivalentId`](#use-of-equivalentid) for more details.
+    1. The `id` in the DID document MUST be set to the new location.
+    1. An `equivalentId` entry of the old location SHOULD remain for historical purposes and anchored to the [[ref: KERI event stream]] using [[ref: designated aliases]]. See section [Use of `equivalentId`](#use-of-equivalentid) for more details.
     1. If possible, the controller of the DID MAY use web redirects to allow resolution of the old location of the DID to the new location.
 
 > The web is not a very stable place, and documents are moved around and copied frequently. When two or more companies merge, often the web presence of some of the merged entities "disappears". It may not be possible to retain a permanent `did:webs` web location.
@@ -149,7 +145,7 @@ Creating a `did:webs` DID involves the following steps:
 
 #### Read (Resolve)
 
-Resolving a `did:webs` DID involves the following steps:
+Resolving a `did:webs` DID must follow these steps:
 1. Convert the `did:webs` DID back to HTTPS URLs as described in section [Target System(s)](#target-systems).
 1. Execute HTTP GET requests on both the URL for the DID document (ending in `/did.json`) and the URL for the [[ref: KERI event stream]] (ending in `/keri.cesr`).
 1. Process the [[ref: KERI event stream]] using [KERI Rules] to verify it, then derive the `did:webs` [[ref: DID document]] by processing the [[ref: KERI event stream]] according to section [DID Document from KERI Events](#did-document-from-keri-events).
@@ -168,5 +164,5 @@ the [[ref: KERI event stream]].
 #### Deactivate
 
 1. To deactivate a `did:webs` DID, A controller SHOULD execute a KERI event that has the effect of rotating the key(s) to null and continue to publish the DID document and [[ref: KERI event stream]].
-    1. Once the deactivation events have been applied, derive the DID document from the [[ref: KERI event stream]] and republish both documents (did.json and keri.cesr) to the web server, overwriting the existing files.
+    1. Once the deactivation events have been applied, the controller should regenerate the DID document from the [[ref: KERI event stream]] and republish both documents (did.json and keri.cesr) to the web server, overwriting the existing files.
     1. A controller SHOULD NOT remove the DID folder and files from the web server on which it has been published. This is considered to be a bad approach, as those resolving the DID will not be able to determine if the web service is offline or the DID has been deactivated.