[resent after apparent mailman glitch] Hi Harald, thank you for this review. Let me try to address your main points. > This document is part of an overall system, including extensions, compilers, > data formats, protocol mappings, and more. No examples of those are linked to > in the document, so it's unclear if we have existence proof that an useful > system can be built, so it's not clear that it's fit for purpose, or why it's a > better fit than other mechanisms for the same purpose. One can argue that this > is out of scope for this particular document, but it would be a better > situation if we could point to such a description. We could have added an RFC 7942 implementation status section, but these are meant to be removed before publication. A good set of information has been collected at onedm.org. I don’t think there is a fully comprehensive survey of SDF activities outside of onedm.org and of the many presentations of activities at OneDM, asdf WG and earlier t2trg. So I’m not sure how we should act on this observation. > The document has not been prepared for publication. The phrase "earlier drafts" > occurs 4 times in section 4.7 - history of development may be interesting to > the WG, but does not belong in a finished document. SDF has been active for a long time before it was wrapped up in the asdf WG. We think it is useful to provide some of these clarifying hints, as a lot of earlier documents and expositions are still around that might be more confusing without these hints. > The document depends on informational references - JSO7 and JSO7V - referenced > multiple times in the text. These references refer to expired I-Ds. Indeed, SDF was inspired by the json-schema.org (JSO) work. The standardization status of that work is somewhat saddening, and there seems to be no way to have a clean reference to a version of that work that is actually relevant to what is being widely used in this context. > It may be > possible to argue that the formal syntax of JSO7 is pulled into the appendixes, > but for a reader to interpret such a sentence as "sdfChoice merges the > functions of two constructs found in [JSO7V]" or "This can be compared to the > processing of the $ref keyword in [JSO7]" without reading those drafts is > stretching the concept of "informative reference" very far. These are expositional references, informative in nature. Since general knowledge about the json-schema.org specifications is quite widely spread, we believe these references are useful. > Those two references point to draft-handrews-json-schema-01 (2018, replaced by > draft-bhutton-json-schema, 2022, expired), and > draft-handrews-json-schema-validation-01 (2018, replaced by > draft-bhutton-json-schema-validation, 2022, expired). At a minimum, the > references need to be updated to the latest versions Unfortunately, that would not be the right thing to do, as the inspiring nature of these documents actually came from the revisions referenced. > and checked that they are > still valid for that version; at best, these documents should be normative > dependencies and published ahead of this one; alternatively, all references > that imply needing to understand those documents should be stripped and the > descriptions made self-contained, citing JSO7 and JSO7V only as "work that > inspired this specification". We took care to ensure that JSO does not need to be referenced normatively. Appendix C [1] contains the SDF vocabulary that was inspired by JSO. Note that this only can ever be an “inspired by” relationship, as SDF is operating at the information/interaction level and JSO is a data model language. Independent from this, we are also describing the syntax of SDF itself in JSO: Appendix B [2] contains a JSO rendition of the SDF syntax defined in Appendix A [3]. One could say that Appendix B provides “batteries included” for the many potential users who have JSO tooling easily available to them. [1]: https://www.ietf.org/archive/id/draft-ietf-asdf-sdf-18.html#jso-inspired [2]: https://www.ietf.org/archive/id/draft-ietf-asdf-sdf-18.html#name-json-schemaorg-rendition-of [3]: https://www.ietf.org/archive/id/draft-ietf-asdf-sdf-18.html#name-formal-syntax-of-sdf > I noted several more issues in the first pages, such as ignoring > internationalization even for textual description fields, but I decided to send > this review without going into more details on other issues. More review is > needed before publication. It is important to keep in mind that SDF is intended as a hub format (“red star”) for the many ecosystem specific specification techniques, with the intention of providing translation mechanisms. Making that hub format fully internationalization-ware, when the ecosystems that this translates to and from aren’t, is likely to produce specifications that are somewhat detached from reality. SDF is designed to be extensible, so I would expect us to be able to retrofit such elements when they become more widely used. Maybe we can use the seeds of internationalization in the WoT (W3C Web of Things) ecosystem format to give us a head start, but in the end the support must work with a wide variety of ecosystem formats. (I note that the groundwork we did in [4] might be a good input to such an extension, as well.) [4]: https://www.rfc-editor.org/rfc/rfc9290.html#name-language-tagged-strings Grüße, Carsten -- last-call mailing list -- last-call@xxxxxxxx To unsubscribe send an email to last-call-leave@xxxxxxxx
