Last Call Review of draft-ietf-asdf-sdf-18
review-ietf-asdf-sdf-18-artart-lc-alvestrand-2024-05-25-00

NOTE: This is a preliminary review, based on the first 32 or so pages of the
draft. I prioritized getting a review in reasonably close to deadline rather
than slogging through all of the 98 pages.

Chief reasons for saying "Not ready":

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.

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.

The document depends on informational references - JSO7 and JSO7V - referenced
multiple times in the text. These references refer to expired I-Ds. 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.

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 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".

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.