Subject: [Jcardcal] Ted Lemon's No Objection on draft-ietf-jcardcal-jcard-05: (with COMMENT)

From: "Ted Lemon" <[email-masked]>
Date: Wed, 17 Jul 2013 19:31:44 -0700

Ted Lemon has entered the following ballot position for
draft-ietf-jcardcal-jcard-05: No Objection

When responding, please keep the subject line intact and reply to all
email addresses included in the To and CC lines. (Feel free to cut this
introductory paragraph, however.)

Please refer to http://www.ietf.org/iesg/statement/discuss-criteria.html
for more information about IESG DISCUSS and COMMENT positions.

----------------------------------------------------------------------
COMMENT:
----------------------------------------------------------------------

Abstract is a bit weak.  How about:
OLD:
   This specification defines "jCard", a JSON format for vCard data.
NEW:
   This specification defines "jCard", a JSON representation of the
   vCard data format.   The vCard data format is a text format for
   representing and exchanging information about individuals and
   other entities, for example telephone numbers, email addresses,
   structured names and delivery addresses.

In section 2:
   The underlying format used for jCard is JSON.  Consequently, the
   terms "object" and "array" as well as the four primitive types are to
   be interpreted as described in Section 1 of [RFC4627].

It would be relatively inexpensive to enumerate the names of those types
here, and might make the reader's life a little easier, although I'm sure
the type names are going to be familiar.

Given the round-tripping requirements mentioned in the introduction, I
find the treatment of date and time formats confusing; RFC 6350 forbids
the use of the extended format, and this document seems to require it,
according to the last paragraph of section 3.1. I dove deeper into the
spec to find clarification, but the text on dates and times later in the
document didn't help me.

I am certain that this was a conscious decision of the working group, so
I don't mean to suggest that this is a mistake, but the text in RFC 6350
talks about various sections of the ISO date specification and is very
clear about which section is being referenced and which is being
excluded; the text in this document is not specific in this way, so it's
difficult to figure out how the specifications differ.

It would help when talking about dates and times if the text in this
document could be written to more closely mirror the style of the similar
sections in RFC 6350, so as to help make these differences clear. I wish
I could offer text, but I don't actually know what the working group
intended, which seems like the core of the problem.

>From 5.3, I was surprised based on my reading of 5.2 that this:

   ["x-karma-points", {}, "integer", 95]

came out as this:

   X-KARMA-POINTS:95

and not this:

   X-KARMA-POINTS;VALUE=INTEGER:95

The explanatory text says:

   It is
   assumed that the parser has knowledge of the default data type for
   the "x-karma-points" property.

This explains why there's no value parameter in the vCard translation,
but I don't know _why_ it is assumed that the parser has this knowledge,
particularly given that 5.2 seems to say that the conversion should
assume that the parser _doesn't_ have this knowledge. Am I missing
something obvious?   If I'm missing something subtle, perhaps more text
is called for... :)

It's really too late to make this criticism, since the working group has
consensus on the document, but I think Appendix A is a really bad idea—if
the text isn't normative, what good is it?   I understand why it wouldn't
be normative, but generally speaking non-normative restatements of
normative text are a bad idea because they inevitably wind up being
treated as normative by some implementors.   This comment is based on
real-world experience.   Appendix B seems much more helpful.

Thanks for writing this document—I can already envision using this format
in my own code.

---

From: Barry Leiba <[email-masked]>
Date: Thu, 18 Jul 2013 12:56:30 -0400

>    structured names and delivery addresses.

The author just used RFC 6351 as a model.  I agree that a better
abstract would be... better.

> something obvious?   If I'm missing something subtle, perhaps more text

Perhaps if the text said this, you'd understand the point better:

<< It is assumed that the parser supports the "x-karma-points"
property, and that the property is defined with a default data type of
"integer". >>

The problem with giving an example here is that there are no base
properties in RFC 6350 that have default type of "integer".  So the
author had to make up a hypothetical property to use.

Barry

---

From: Ted Lemon <[email-masked]>
Date: Thu, 18 Jul 2013 17:16:24 +0000

> author had to make up a hypothetical property to use.

It might be best to say something like:

There are no base properties in RFC 6350 that have a default type of integer.   Consequently, we are using the following hypothetical property which we treat as being known to the parser, and having a type of integer, in order to illustrate how a known property with an integer type would be transformed.

---

From: Philipp Kewisch <[email-masked]>
Date: Sun, 21 Jul 2013 21:57:18 +0200

>     structured names and delivery addresses.
Indeed, I've copied this from rfc6351, assuming the idea of the abstract 
it was to be just a single sentence. I'm happy to expand the abstract a 
little. How about this? The only downside may be that the purpose is 
also defined with a little different wording later on, but given this is 
an abstract I think its still valid.

OLD:
    This specification defines "jCard", a JSON format for vCard data.
NEW:
    This specification defines "jCard", a JSON format for vCard data.
    The vCard data format is a text format for representing and
    exchanging information about individuals and other entities, for
    example telephone numbers, email addresses, structured names and
    delivery addresses.  JSON is a lightweight, text-based, language-
    independent data interchange format commonly used in internet
    applications.

    The purpose of jCard is to bring together these two formats to
    provide a lightweight, language-independent data interchange format
    for information about individuals and other entities.
> the type names are going to be familiar.
Sure, I've added the four types:

OLD:
    The underlying format used for jCard is JSON.  Consequently, the
    terms "object" and "array" as well as the four primitive types are to
    be interpreted as described in Section 1 of [RFC4627].
NEW:
    The underlying format used for jCard is JSON.  Consequently, the
    terms "object" and "array" as well as the four primitive types
    (strings, numbers, booleans, and null) are to be interpreted as
    described in Section 1 of [RFC4627].

> intended, which seems like the core of the problem.
The main reason we went with the extended format is that it is much more 
commonly used in internet applications and JavaScript. Confusion as to 
which formats are allowed has come up in the past, which is why I have 
added the tables in Section 3.4.3, 3.4.4 and 3.4.5. As far as I am 
aware, the tables are complete and consider all possible conversion 
cases. Doesn't this make the difference clear enough?

I'm happy to add some words to Section 3.1 to clarify why we went with 
the extended format though, how about this:

OLD
    One key difference in the formatting of values used in vCard and
    jCard is that in jCard the specification uses date/time values
    aligned with the extended format of [ISO.8601.2004].  The sections of
    this document describing the various date and time formats contain
    more information on the use of the complete representation, reduced
    accuracy or truncated representation.

NEW:
    One key difference in the formatting of values used in vCard and
    jCard is that in jCard the specification uses date/time values
    aligned with the extended format of [ISO.8601.2004], which is more
    commonly used in internet applications that make use of the JSON
    format.  The sections of this document describing the various date
    and time formats contain more information on the use of the complete
    representation, reduced accuracy or truncated representation.

Does this alleviate all your concerns regarding the date format?

> something obvious?   If I'm missing something subtle, perhaps more text
I've read the replies you and Barry sent, I'd like to make some slight 
modifications to better align with vCard/jCard terminology. How is this?

OLD:
    The following is an example of a jCard property (where the
    corresponding vCard property uses a "INTEGER" value as its default),
    and the equivalent vCard representation of that property.  It is
    assumed that the parser has knowledge of the default data type for
    the "x-karma-points" property.

NEW:
    There are no standard properties in [RFC6350] that have a default type
    of integer.  Consequently, this example uses the following extended
    property which we treat as having a default type known to the parser,
    namely integer, in order to illustrate how a property with a known
    default type would be transformed.

> real-world experience.   Appendix B seems much more helpful.
If we were to change something here, what would it be? I do think the 
ABNF schema is helpful to understand some parts of the document and I've 
done my best to make it as normative as possible. There are a few spots 
where supplying a full ABNF capturing all the semantics would bloat it 
unnecessarily, but I've at least added comments in those places.
> Thanks for writing this document—I can already envision using this format
Super! I'm glad this is picking up so quickly :)

Philipp

---

From: Ted Lemon <[email-masked]>
Date: Mon, 22 Jul 2013 12:46:18 +0000

On Jul 22, 2013, at 1:41 AM, Philipp Kewisch <[email-masked]> wrote:
> hope you are aware that you just replied to me? Anyway, replying inline. Feel free to forward to the list if you like.

Yeah, I noticed that as I was hitting send, and it was too late to do anything about it other than resend, and I was too lazy to do that... :)

> Ok, removed the second paragraph.

Thanks!

> All date and time formats allowed in RFC6350 can be round-tripped without losing information. The extended format is really just adding dash-separators to dates and colon-separators to times. There are no ambiguities with the truncated representations, since there the dashes are added to the beginning of the date/time.

Okay, then I don't think this is an issue that needs to be addressed.  You might want to just mention that no information is lost when converting between formats, but I don't think a reader who is just trying to implement this will care—the only reason I brought it up was that it looked like a possible contradiction.

> I understand your concerns and I admit to at least starting off with the ABNF when reading rfcs I want to implement. Maybe I just feel attached to it since it was a certain amount of work to make sure its right that I don't want it to go away, but if it gives you a a better feeling on the document, maybe it makes sense to bring this up in an extra thread on the WG list. Maybe we can instead make the changes so it is indeed normative, but organize the text in a way that its still easy to understand.

I leave it up to you—it's not a DISCUSS, after all.   I mentioned it late in the process—the time when my comment would have been most useful would have been when you did the first draft, not during the approval process.   If you think that deleting it from this document will mean that it never gets published, that's a strong enough reason to keep it.   I do not suggest that you do a lot of additional work that may make the section less readable—even if you made the ABNF perfect, you would then have two bits of normative text describing the same thing, so it wouldn't really address my objection.