[Asdf] shepherd comments on draft-ietf-asdf-sdf-16.txt

[Michael Richardson <[e-mail]>]

I think that all my comments are editorial.

1) I think we need some text in the Introduction explaining "SDF 1.0" and
"SDF 1.1".

I suggest: "During the development of SDF, version numbers were included, but
           with the publication of this base SDF and the associated extension process,
           they are no longer relevant. "

2) I found the terminology rather abruptly started talking about JSON and
   maps and the like, and since I've intentionally not read much for six
   months, I had no basis on which to understand this.  I think the
   Introduction might need to diagram how SDF is encoded before we can start
   talking about Quality, etc.

For instance:
      (Note that JSON maps are often called JSON objects due to JSON's
      JavaScript heritage; in this document, the term Object, short for
      sdfObject, is specifically reserved for the above grouping, even
      if the type name "object" is imported from a data definition
      language with the other semantics.)

seems really out of place in the Terminology.
Maybe alphabetical terminology is wrong, and top-down would be better.

3) Figure 2 has the sdf* in some arrangement, but I am not sure if there is some
logic to it.  I guess the double line at the bottom is a UML thing?
Ah. The SVG version is significantly different, having arrows and the like.
I think that the ASCII version may be sufficiently content-free as to be omitted.

I guess that Quality Names and Prefixes could be a single letter, including
could be just "$" or "a".  (Because "*" pattern is 0 or more, right?)

"Base SDF does not address internationalization of given names."
okay. And we don't permit UTF-8 either.  Should we permit UTF-8, but then
restrict use to ASCII, so that tools will know to expect UTF-8?

Table 2, defaultNamespace, the definition does not make it clear that the
namespace is identified by the key in the namspace map.  I understood it
would just repeat the URI.  The example makes it clearer that it's the key.

The text:
   As the
   defaultNamespace is set by giving a namespace short name, its
   presence requires a namespace map that contains a mapping for that
   namespace short name.

clears some of this up, but only after the example.  And the word "namespace
short name" is not clearly connected that it's the key in the map, although
one puzzles through and concludes that.

If no namespace map is given (and thus no defaultnamespace), then I guess the
namespace block can be omitted?  When would this occur?  Until the example,
in section 4.4, I didn't notice that "defaultNamespace" wasn't actually in
the namespace block :-)  {of course, it's right there in Figure 1}

4) section 4.1:

   Global names look exactly like https:// URIs with attached fragment
   identifiers.

   There is no intention to require that these URIs can be dereferenced.

I feel that some maybe IESG will get upset about this.
Well, maybe just ART ADs, and they will get first kick at the can anyway.

}4.7.1.  sdfType
}
}   SDF defines a number of basic types beyond those provided by JSON or
}   JSO.  These types are identified by the sdfType quality, which is a
}   text string from a set of type names defined by the "sdfType values"
}   sub-registry in the "SDF Parameters" registry (Section 7.3.2).  The
}   sdfType name is composed of lower case ASCII letters, digits, and -
}   (ASCII hyphen/minus) characters, starting with a lower case ASCII
}   letter (i.e., using a pattern of "[a-z][-a-z0-9]*"), typically
}   employing KebabCase for names constructed out of multiple words
}   [KebabCase].

If we are going to use KebabCase, then the pattern needs to include upper
case letters, right?

Funny that this JSON intensive document has to resort to RFC8949 for POSIX
time :-)

}4.7.2.  sdfChoice
}
}   Data can be a choice of named alternatives, called sdfChoice.  Each
}   alternative is identified by a name (string, key in the outer JSON
}   map used to represent the overall choice) and a set of dataqualities
}   (each in an inner JSON map, the value used to represent the
}   individual alternative in the outer JSON map).  Dataqualities that

I think that the () are pretty important bits of information, and I would
rework this so that they get their own sentences.

"this specification" under enum... does that refer to SDF 1.0, or to JSO?.

5) 7.1. [e-mail] will cause an AD nit.

6) Security Considerations... .Specifics: TBD. Oops.  We need to say more *or
   less*

7) I did not check if the CDDL is correct.

8) I think that we'll need some covering text to explain how we are using
JSO, and yet not really depending upon it.  Is our "version" of JSO7 unique?
My impression is that we are using a subset of it, but then we add stuff like
"const".... I'm worried we'll get into proceedural snags here (again).  It's not
our intention to standardize JSO within the IETF, and yet... those appendixes
are there looking like they want to be normative.
Can I implement without reading JSO?





















--
Michael Richardson <[e-mail]>   . o O ( IPv6 IøT consulting )
           Sandelman Software Works Inc, Ottawa and Worldwide