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

[Carsten Bormann <[e-mail]>]

Hih Michael,

thank you for your comments.


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

All references to SDF development draft version numbers were removed in 0becec2, which was part of PR #130, which was incorporated to -16.  Is this comment part of an earlier review?

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

The terminology isn’t alphabetical (but it is not exactly top-down either — the intent was to have a good sequence for reading).

JSON considerations enter the document on two avenues:

1) An SDF document is a JSON text.
2) some of the modeling constructs (“qualities”) are inspired by JSON-schema.org, which describes JSON.

Maybe we should pull forward SDF Document and SDF Model.

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

Interesting.  (I hadn’t looked at the plaintext version for a while.)
These diagrams are generated by plantuml, and maybe there has been a version update that needs some tweaks...

> 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?)

Yes.

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

(SDF’s strings, in interchange, are represented as UTF-8.
Given names are strings, but then limited to ASCII digits, ASCII letters, and $.  So I think we already have what you are suggesting?)

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

Yes, this can be cleaned up a bit.

> 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}

Also ripe for some clean-up.

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

That’s why we have draft-bormann-t2trg-deref-id :-)
But seriously, considerations for dereferenceable identifiers are collected in that document, and here we shouldn’t second-guess this.

> }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?

Names in KebabCase are written like kebab-case, which doesn’t require upper case letters.

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

It doesn’t have to — this is just a document that can be referenced and already does all the right things.

(JSON does not have a time/datetime type.)

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

Thanks.

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

the SDF specification (actually even in 1.1, but we are not getting specific about pre-base SDF versions any more).

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

Well, this was recommended earlier…
But we are used to rewriting IANA considerations.

> 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?

The appendices are normative.  JSO is just mentioned as the inspiration...

Grüße, Carsten