need more normative statements, and need them earlier

[dhh1128]

If I were to draw a heat-map of where there are normative requirements in this spec, I think (and "think" is an important word here; it should be "know") I would see them scattered all over, but occurring more toward the end. The first statement that I could find that sounded normative at all (excluding a few definitions) was in section 6.8: "All Cryptographic primitives in KERI must be expressed using the CESR (Compact Event Streaming Representation) protocol." This use, and subsequent ones that are intended to have normative effect, are not capitalized. As another example, I guess that this sentence is intended to be normative, but IMO it is not unambiguously so: "The public key is derived from the private key or seed using a one-way derivation that must have a minimum cryptographic strength of approximately 128 bits." My judgment is that the vast majority of uses of the word "must" are not intended to be normative. I also saw multiples uses of "may" that were just casual. I didn't notice usage of normative "MAY" and "SHOULD", though perhaps I just missed stuff. Generally, I think the doc exhibits this characteristic because it offers a lot of critique of the status quo, and a lot of theory and rationale, before detailing the concrete decisions that embody KERI's solution to a given problem.

If I did the same exercise with the HTTP spec (RFC 2616), I think I might see a pretty different heat map. There are some defs and overview paragraphs. Then sections 3-9 define the core of the protocol, all by about the 1/3 mark or a bit earlier. Then there's long explanation about the details and rationale.

Of course, a spec does not have to use the conventions of RFC 2119 to convey normative requirements. Nor does it have to put all its normative statements in a particular place. However, my larger point is that it is very challenging to distill the normative requirements from all the other content in the document.

I realize that rewriting a document this complex is a major undertaking. A concrete suggestion that might be far less ambitious, but that would help a lot, would be to have a Compliance section right after Terminology. The section might say something like this:

In order to comply with this spec, an implementation:

* MUST use cryptographic primitives that guarantee at least 128 bits of security.
* MUST serialize its messages (data structures) with CESR version X.
* MUST interact via the message types defined in section 7.
* MUST generate identifiers according to the rules defined in section 8.
* MAY use witnesses and watchers, as defined in section 9.
etc.
etc.

Such a section might be a page or less of text, but it would draw together a bunch of disparate threads in a useful way.

I would be happy to write such a distillation, and submit it as a PR, if there's consensus that it would be useful. But perhaps this is too large of a change to consider at this stage in the spec's lifecycle.

[talltree]

I strongly agree with @dhh1128's points. As the spec reads right now, it appears nearly impossible to determine conformance. I also agree that adding clear conformance keyword language (I personally strongly recommend using IETF RFC 2119 keywords—that is the standard normative language used in all other ToIP deliverables so far) would go a long ways towards that goal.

I fully understand that, as @dhh1128 points out, given the size of the spec, it will likely be a significant amount of work to add those normative statements and conformance requirements. But it seems necessary in order to meet the fundamental purpose of a technical specification: to be able to objectively test that there multiple conformant implementations.

[darrellodonnell]

I think this is a required change. I have been staring at the CESR spec as it is closer to my past experience (ancient) in encoding.

I propose that the work be done in the CESR side first, though, for a few reasons:

• It is smaller
• CESR is more limited in cross-specification references
• CESR has fewer dependencies
• CESR is a dependency for TSP
• CESR is a focused domain, so establishing the pattern of normative, non-normative, and conformance requirements should be easier, and more folks should be able to contribute (i.e. not drawing from just the KERI community).

We should stick with the RFC2119 (MUST, MUST NOT, … - capitalized). I understand these specifications may end up at an SDO that doesn't use that, but we do. ISO has a different style, but LF/JDF has a known process for translating between styles. For ToIP to support both styles simultaneously is confusing.

I'd be happy to with @dhh1128 on this to get things going.

[SmithSamuelM]

@darrellodonnell @talltree I just want to remind both of you that when we started this process we discussed RFC2119 versus ISO standards and decided on ISO. Its only after we were in public review that ToIP decided on RFC2119 as a requirement. So we will comply but please remember this is an after that fact requirement. I get that we are the guinea pigs. The original draft specs that we ported from WebofTrust followed RFC2119 because there were IETF facing at that time. But on the advice of our ISO facilitator we changed to ISO format. Now we are changing back.

I am tasked with converting the CESR spec to use RFC2119. I will take care to emphasize the normative language. Appreciate any feedback once I do the first pass.