search

trustoverip / tswg-cesr-specification

Composable Event Streaming Representation (CESR) Specification
https://trustoverip.github.io/tswg-cesr-specification/
Other
3 stars 8 forks source link

Lack of normative statements and clear conformance criteria #95

Open talltree opened 2 months ago

talltree commented 2 months ago

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 commented 2 months ago

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 commented 2 months ago

@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 commented 2 months ago

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.