Lack of normative statements and clear conformance criteria

[talltree]

I believe this specification represents is a brilliant technical solution to an extremely challenging topic that is fundamental to decentralized digital trust infrastructure. In short, I am "sold way past the close" on CESR 2.0.

However, after reviewing the spec from start to finish, I could not find the normative statements from which one could objectively determine conformance. I kept looking for the sections that would precisely define the CESR format requirements similar to the way RFC 7159 defines the JSON format requirements or RFC 8949 defines the CBOR format requirements. But I could not find them.

I left this same comment on the KERI specification. I understand that these specs do not use RFC 2119 keywords (which I strongly recommend as they are the most widely accepted for Internet specifications and have been used in all other ToIP specifications). But regardless of the language used, any specification of this kind—especially for an encoding format—needs clear, unambiguous, testable normative statements and conformance criteria that can be used to develop and verify a conformance test suite.

Also, before this spec can be finalized and approved as a Working Group Approved Deliverable, all internal notes, TODOs, issues, and other unfinished areas must be completed, i.e., the spec must really be "done" and ready for final publication.

[darrellodonnell]

There is a similar thread over on the KERI specification. I agree here and @dhh1128 has provided a good commentary that amplifies what your comment above is all about: https://github.com/trustoverip/tswg-keri-specification/issues/176#issue-2258975770

[SmithSamuelM]

@talltree at our last community mtg on Tuesday we discussed. The genesis of the problem is that ISO does not follow the IETF normative MUST MAY SHOULD indeed it forbids the all caps and uses shall instead of must. So one the first changes we made when bringing the specs into TOIP was to decapitaluze and change must to shall. However since then we have been informed that TOIP has now decided that it wants to enforce the IETF convention. So we added on Tuesday the task of converting back so that it becomes obvious what the normative phrases are. We will do this before handing over to TOIP for review. This is a result of us being the guinea pig for what TOIP specs want to look like. We will then have to reformat yet again to send them to ISO.

[darrellodonnell]

The LF/JDF process accounts for what I call the "ISO House Style" which is different, but translateable from IETF style. https://www.iso.org/ISO-house-style.html I imagine they do this to account for ISO's unique approach. I don't see that work as substantive - meaning a requirement can be re-cast from IETF-style to ISO-style with work.

I believe there is more work than just the ISO-to-IETF style changes though. There is a large amount of content that I can't figure out is normative or non-normative. On the KERI spec @dhh1128 raised similar concerns: https://github.com/trustoverip/tswg-keri-specification/issues/176#issue-2258975770

I think we could take a focused effort on a part of CESR to "show the way" as a group and then parcel out the work to make rapid progress.

[talltree]

Let me apologize for my delay since the ACDC Task Force notified the community that the KERI, ACDC, and CESR specs had been updated to use RFC 2119 keywords. A trip to the EU over the past six weeks made it very hard for me to find enough time for a second review.

I finally got that time on my return flight from Europe. I focused on the CESR spec as that is the dependency we have for the Trust Spanning Protocol.

First, I believe the use of RFC 2119 keywords in the revision does substantially improve the ability to determine conformance. Statistically, this is what I found:

• MUST appears 119 times; the vast majority of these (~100) are normative.
• SHOULD appears 8 times; none of these are normative.
• MAY appears 113 times; 12 of these are normative.

For the record, the overall format of the spec still remains quite different from the way RFC 7159 defines JSON format requirements or RFC 8949 defines CBOR format requirements. The CESR spec is substantially longer and does not organize normative requirements in a way that makes it easy for a developer to check for conformance.

That said, I have to provide the caveat that I am not a coder, nor an expert in encoding formats, so I can't really make any judgements about the technical correctness of the spec, only about the formatting.

In my review, I also noted the following:

1. There is at least one partial keyword capitalization (e.g., "MUSt") that should be fixed.
2. The same for one instance of "MAY not" that should be "MAY NOT".
3. There are still open issues and pending fixes noted.
4. There are only two normative references in section 7. It feels like, at a minimum, the JSON, CBOR, and MGPK specs should be referenced (since CESR can carry each of these).
5. The Forward section is still needed (I know there is a dependency on ToIP providing this).

All of these need to be addressed before the CESR spec would be ready for a final TSWG approval vote.

I hope this is helpful.

[darrellodonnell]

I am impressed with the quality of the new content. It brings more rigour to the specification.

The editing and new content here are valuable. The specification should undergo another Public Review. New definitions have been added, and many new clauses have been created. This is impressive work, which differs substantially from the version that went through the first public review.

[SmithSamuelM]

Numbers 1-4 below have all been fixed with pull https://github.com/trustoverip/tswg-cesr-specification/pull/102

On Jul 14, 2024, at 08:07, Drummond Reed @.***> wrote:

Let me apologize for my delay since the ACDC Task Force notified the community that the KERI, ACDC, and CESR specs had been updated to use RFC 2119 keywords. A trip to the EU over the past six weeks made it very hard for me to find enough time for a second review.

I finally got that time on my return flight from Europe. I focused on the CESR spec as that is the dependency we have for the Trust Spanning Protocol.

First, I believe the use of RFC 2119 keywords in the revision does substantially improve the ability to determine conformance. Statistically, this is what I found:

MUST appears 119 times; the vast majority of these (~100) are normative. SHOULD appears 8 times; none of these are normative. MAY appears 113 times; 12 of these are normative. For the record, the overall format of the spec still remains quite different from the way RFC 7159 https://datatracker.ietf.org/doc/html/rfc7159 defines JSON format requirements or RFC 8949 https://datatracker.ietf.org/doc/html/rfc8949 defines CBOR format requirements. The CESR spec is substantially longer and does not organize normative requirements in a way that makes it easy for a developer to check for conformance.

That said, I have to provide the caveat that I am not a coder, nor an expert in encoding formats, so I can't really make any judgements about the technical correctness of the spec, only about the formatting.

In my review, I also noted the following:

There is at least one partial keyword capitalization (e.g., "MUSt") that should be fixed. The same for one instance of "MAY not" that should be "MAY NOT". There are still open issues and pending fixes noted. There are only two normative references in section 7. It feels like, at a minimum, the JSON, CBOR, and MGPK specs should be referenced (since CESR can carry each of these). The Forward section is still needed (I know there is a dependency on ToIP providing this). All of these need to be addressed before the CESR spec would be ready for a final TSWG approval vote.

I hope this is helpful.

— Reply to this email directly, view it on GitHub https://github.com/trustoverip/tswg-cesr-specification/issues/95#issuecomment-2227361833, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAETEPKL7PMBJSW7BSKUT2DZMKA2HAVCNFSM6AAAAABGZOKY7KVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEMRXGM3DCOBTGM. You are receiving this because you commented.