Subject: [Jcardcal] Barry Leiba's Discuss on draft-ietf-jcardcal-jcard-05: (with DISCUSS and COMMENT)

From: "Barry Leiba" <[email-masked]>
Date: Thu, 18 Jul 2013 10:55:01 -0700

Barry Leiba has entered the following ballot position for
draft-ietf-jcardcal-jcard-05: Discuss

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.

----------------------------------------------------------------------
DISCUSS:
----------------------------------------------------------------------

UPDATE: I've finished my review, so this is now complete.  Please look it
over again to get the latest version of all comments.

Two blocking points:

DISCUSS POINT 1: As I read this document, I found its organization
confusing.  I was going to say that it has serious organizational
problems that impede understanding, but in the end, after getting through
it, I understood it.  Still, readers shouldn't be confused as they read,
even if they "get it" in the end, so let me try to make some suggestions
about organization.  I'm concerned that the issues are sufficient to
confound implementations.

My comments below include things that will, for me, correct the
organizational problems.  I haven't separated them out specifically,
because what I suggest below isn't what's *required* to clear my DISCUSS.
 Other clarifications and reorganization might do as well.  But let's
talk about how the document is organized, and please consider my
suggestions below.  I'll be happy to do some concentrated work with the
author on this, if he'd like.

I'm afraid my comments below are extensive.  Please don't be daunted by
that, and let's work on the text to make sure it says what's necessary
for good implementation.  There are no fundamental issues here -- it's
all about clarity and organization.

DISCUSS POINT 2: Please update Section 8 (the media type registration) to
conform to the template in RFC 6838.

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

UPDATE: I've finished my review, so this is now complete.  Please look it
over again to get the latest version of all comments.

Section 3.2 describes how properties are encoded, and relies on the
subsections to add to the description.  The problem is that I didn't find
it to be clear that way, kept wondering what happened to [some case],
then wasn't completely clear about things when I got to the special
section that covered that case.

I don't think it's necessary to described multi-valued properties
separately; the description of handling multiple values can be rolled
into the base Section 3.2 (Section 3.2.1.2 adds little), and I think that
would help a lot.  Perhaps this as a start, along with other tweaks (such
as getting rid of the "depending on if" stuff in the first paragraph):

OLD
   The remaining elements of the array are used for the value of the
   property.  For single-value properties, the array MUST have exactly
   four elements, for multi-valued properties as described in
   Section 3.2.1.2 there can be any number of additional elements.
NEW
   The remaining elements of the array are used for one or more values
   of the property.  For single-value properties, the array has exactly
   four elements; for multi-valued properties, each value is another
   element, and there can be any number of additional elements.
END

The example could then include a property with multiple values (the
"categories" property from Section 3.2.1.2, perhaps.

This confused me at first, so let's try re-wording:
OLD
   The property parameters in the second element of the property array
   associate a set of parameter names with their respective value.
   Parameters are further described in Section 3.3.
NEW
   The parameters in the second element of the property array
   associate a set of parameter names and values with the property.
   Parameters are further described in Section 3.3.
END

On the other hand, why not just delete that paragraph?  The numbered list
already says that the second element is an object containing properties,
and refers the reader to Section 3.3.  What's the value in saying it
again?

   To allow for a cleaner implementation, the parameter object MUST be
   present even if there are no parameters.  In this case, an empty
   object MUST be used.

This paragraph should be removed, and the useful bit -- that en empty
object represents an absence of parameters -- should go in the numbered
list:

OLD
   2.  An object containing the parameters as described in Section 3.3.
NEW
   2.  An object containing the parameters as described in Section 3.3.
   If the property has no parameters, an empty object is used to
   represent that.
END

If you think the "MUST" needs to stay, you can do that this way (I don't
care either way on this one):
OLD
   The array consists of the following fixed elements:
NEW
   The array consists of three fixed elements, all of which MUST
   be present in this order:
END

Now, this:

   The array describing the property can then be inserted into the array
   designated for properties in the jCard component.

Wait... what array designated for properties?  Is there an overall
structure of the jCard component that you haven't introduced yet?  That
needs to come first.

I found this to be fractured and hard to follow:

   As described in Section 3.2.1.4, it is important for a parser check
   the data type of the value even if it is assumed to be a string in
   most cases.  The value could turn out to be a structured value, in
   which case the data type is an array.

I suggest merging this with numbered list item 3, this way, assuming that
I've understood it correctly:

OLD
   3.  The type identifier string of the value, in lowercase.
NEW
   3.  The type identifier string of the value, in lowercase.  It is
   important that parsers check this to determine the data type of the
   value, and that they do not rely on assumptions.  For example, for
   structured values the data type will be "array".
END

While we're at it, I don't think you've explained the uppercase/lowercase
stuff well, so let me suggest this:

OLD
   1.  The name of the property as a string, but in lowercase.
NEW
   1.  The name of the property, as a lowercase string.  The vCard
   format specifies that property names are case-insensitive, and
   recommends that they be rendered in uppercase.  In jCard, they
   MUST be in lowercase.
END

I think you also need to remind readers that when jCards are converted
back to vCards, the lowercase property (and parameter) names SHOULD be
put back into uppercase, as recommended in RFC 6350.

Section 3.2.1.1 doesn't really make sense to me as it is.  What you
should probably be saying earlier -- somewhere that describes general
conversion stuff -- is that all properties from the vCard MUST be
represented in the correcponding jCard.  Then you wouldn't need this
section at all.  Lacking that, perhaps you might do this section this
way:

NEW
   The vCard format specification [RFC6350] defines the VERSION
   property to be mandatory.  The "version" property MUST be
   represented in the corresponding jCard component, with the
   same value as in the vCard.  vCards that conform to RFC 6350
   will contain the value "4.0".
END

It's important not to say "MUST be 4.0", because then you will not be
independent of subsequent vCard updates.

I was quite confused by the whole "grouping" thing the first time I read
it, but eventually got over that.  I think it could be worded better, and
I ask you to take a look at that.  Feel free to contact me off list if
you'd like me to help, which I'll be happy to do.  Here are some points:

- In vCard, the grouping is accomplished by prefixing the property name
with "groupname.", and that should be noted here, if for no other reason
than to make it clear that the prefix is NOT included in the property
name in the first array element.  Something about that, with a citation
to this section, should be up there in the numbered list ("The property
name specified here does not include any group names; see Section
3.2.1.3, and [RFC6350], Section 3.3.")

- This isn't about "eliminating the need for an extra group syntax in
jCard".  This could have been done with the prefix on the property name,
just as in vCard.  Just say that in jCard, the "group" parameter is used
to encode the group name, which was specified as a property-name prefix
in vCard.

- In 3.2.1.3.1, I find it confusing to use "GROUP" in uppercase, and then
to say it gets lowercased "as any other parameter" (and it doesn't help
that you haven't talked about how to encode parameters yet -- this is
part of the organizational problem).

- You say that the group name's case MUST be preserved; why?  vCard says
that group names are case-insensitive, so why aren't group names put into
lowercase, just as property names are?

- In the jCard to vCard conversion of the group name, I wouldn't say "the
reverse is performed", because there's only one step you're omitting. 
Just say that the value of the "group" parameter is prepended with a "."
to the property name, and that the "group" parameter is discarded.

In Section 3.2.1.4:

   If a multi-valued text component is changed to hold only one value,
   the text component SHOULD be represented as a single primitive value,
   dropping the array completely.

Shouldn't that be "If a structured-value text component", rather than
"mutli-valued"?  I was confused by that at first.  And then what do you
mean "is changed"?  And I think the use of "component" and "value" are
confusing here, because the whole structured text string is a single
vCard "value", and you've presiously referred to its "components" as the
bits separted by semicolons.  Now you're using those words differently.

In Section 3.3.1, I don't think you make it at all clear what you have to
do to create the third array element.  Maybe something like this?:

OLD
   vCard defines a "VALUE" property parameter (Section 5.2 of
   [RFC6350]).  This property parameter MUST NOT be added to the
   parameters object.  Instead, the value type is always explicitly
   mentioned in the third element of the array describing the property.
   Thus, when converting from vCard to jCard, any "VALUE" property
   parameters are skipped.  When converting from jCard into vCard, the
   appropriate "VALUE" property parameter MUST be included in the vCard
   property if the value type is not "unknown" or the default value type
   for that property.  See Section 5 for information on handling unknown
   value types.
NEW
   vCard defines a "VALUE" property parameter (Section 5.2 of
   [RFC6350]).  This property parameter MUST NOT be added to the
   parameters object.  Instead, the value type is encoded as the
   third element of the array describing the property.  When converting
   a property from vCard to jCard, the value type is determined as
   follows:
   
   1. If the property has a "VALUE" parameter, that parameter's
   value is used as the type.

   2. If the property has no "VALUE" parameter but has a default type,
   the default type is used.

   3. If the property has no "VALUE" parameter and has no default type,
   "unknown" is used.

   Converting from jCard into vCard is done as follows:
   
   1. If the property's value type is "unknown", no "VALUE" parameter
   is included.

   2. If the property's value type is the default type for that
property,
   no "VALUE" parameter is included.

   3. Otherwise, a "VALUE" parameter is included, and the value type is
   used as the parameter value.
   
   See Section 5 for information on handling unknown value types.
END

In the example in Section 3.3.2, I'm confused: isn't the value of the "n"
property a structured value, and shouldn't it be converted as an array
(3.2.1.4)?

And I don't understand this paragraph:
   DQUOTE characters used to encapsulate the separated values MUST NOT
   be added to the jCard parameter value.

What's the point of Section 3.4?  This information has been thoroughly
specified earlier.  It would be more useful to say what you're actually
specifying here, something like this:
OLD
   The type of a vCard value is explicitly mentioned in the third
   element of the array describing a jCard property.  The actual values
   of the property can be found in the fourth and following elements of
   the array.
NEW
   The following subsections specify how vCard property value data
types,
   which are defined in the subsections of [RFC6350] Section 4, are
   represented in jCard.
END

In Section 3.4.9:

      The value elements are JSON primitive number values.

Are "1000.0" and "1E3" valid representations of integer values?  If so,
that's fine.  If not, I think you need to say "JSON primitive number
values without fraction or exponent parts."

Similar question about exponents in Section 3.4.10.  In either case, if
exponents are allowed, you should warn about removing them when
converting back to vCard.

In Section 5.2, the first paragraph isn't quite right:

   Since jCard always explicitly specifies the value type, it can always
   be converted to vCard using the VALUE parameter.

But the third paragraph describes when you MUST NOT use the VALUE
parameter.  Anyway, it seems to me that the first paragraph serves no
purpose, and can just be tossed.  And, in fact, if you use my suggested
text above for Section 3.3.1, you really don't need Sections 5.1 or 5.2
anyway.

In general, I think some (many?) of the examples would be far better if
they showed both vCard and jCard versions.

-----------------------------------------------
Very minor editorial comments:

The list at the end of the introduction would be improved by making the
four items parallel.  The first two are fine, but then the third should
be "Semantics of the vCard data will be preserved," and the fourth
"Extensions to the underlying vCard specification can be handled
without...."

-- Section 3 --

"In [RFC6350], vCard objects are comprised of ..." -- The whole comprises
the parts; this should be "In [RFC6350], vCard objects comprise ...".

Why "jCard component"?  The word "component" makes me wonder what it's a
component *of*, when it seems to refer to a high-level thing.  And, in
fact, the ABNF in Appendix A uses "jcardobject" as the overall
definition, so why aren't you calling it a "jCard object"?

-- Section 3.1 --
   vCard uses a line folding mechanism to limit lines of data to a
   maximum line length (typically 72 characters)

Actually, RFC 6350 Section 3.2 says "75 octets", not 72 characters.  This
should say the same, if it's going to say it at all (and remember that
octets != characters).

And, as has come out in the discussion of Spencer's comment, the last
line of that paragraph should say, "Prior to converting vCard data into
jCard all folded lines MUST be unfolded before any other processing is
done."

-- Section 3.2.1.4 --

I suggest this, as a reminder:

OLD
   In jCard, the property value is an array containing one
   element for each text component.
NEW
   In jCard, the property value is an array containing one
   element for each text component, with empty/missing text
   components represented by zero-length strings.
END

-- Section 3.4.4 --

      Contrary
      to [I-D.ietf-jcardcal-jcal], UTC offsets are permitted within a
      time value.

I find it generally helpful to include some indication of what the cited
document *is*, in addition to having the citation to it... for example,
"in the vCard specification [RFC6350]", rather than just "in [RFC6350]". 
That seems especially useful here, because once jCal is an RFC, a reader
would have no idea what you're referring to without going to the end of
the doc to the references.  I'd also rather not bury the lede here, so
why not this?:

      In jCard, UTC offsets are permitted within a time value; note
      that this differs from jCal [I-D.ietf-jcardcal-jcal], where they
      are not permitted.

---

From: Philipp Kewisch <[email-masked]>
Date: Sun, 21 Jul 2013 23:40:42 +0200

> DISCUSS POINT 1: As I read this document, I found its organization
I'm going to continue on this discussion point tomorrow, its getting 
late in Europe. I'm happy to make changes though, its nice to hear new 
perspectives on the document. Also thank you for such an elaborate 
review and all the suggestions on how to fix it.
> conform to the template in RFC 6838.
Ah I see, there are some more headings I missed. Probably the reason I 
left them out was that I believe they are all N/A. I would be adding 
these headlines, please let me know if they are ok, or if they should 
contain any information I am not aware of. We have decided not to 
register a file extension for this type as it is mostly used for 
interchange.

    Fragment identifier considerations:  N/A

    Additional information:
       Deprecated alias names for this type:  N/A
       Magic number(s):  N/A
       File extension(s):  N/A
       Macintosh file type code(s):  N/A

---

From: Philipp Kewisch <[email-masked]>
Date: Mon, 22 Jul 2013 14:20:23 +0200

On 7/18/13 7:55 PM, Barry Leiba wrote:
> [...]
Done. I've made them two separate examples and described the existing 
one as "Single-valued properties example" and the categories example as 
"Multi-valued property example".
> and refers the reader to Section 3.3.  What's the value in saying it
Indeed, this is redundant. I'm removing that paragraph.
>     If the property has no parameters, an empty object is used to
Yeah, after reading your previous point its obvious that that paragraph 
can be collapsed into the numbered list.
>     be present in this order:
Doing so, I think its good to mention.

> structure of the jCard component that you haven't introduced yet?  That
Sorry, this was an oversight when the "vcardstream" got removed. I had 
introduced the container in that section. I've added a section called 
"vCard Object and Syntactic Entities" just prior to the properties 
section, where I describe the general structure of a jCard. The dilemma 
is now that here I must forward reference properties since RFC6350 
defines the "BEGIN:VCARD" and "END:VCARD" as two "properties" BEGIN and END.

Also, due to what I read in the 6350 sections 6.1.1 and 6.1.2 
(BEGIN/END), this section is kind of the "return of the vcardstream", 
because it does make sense to at least mention how multiple vcard 
entities can be transported together. The consensus was to assume that 
multiple entities can just be put in a simple array, I have metntioned 
it in the section.

Here is the new section, to be inserted just before the "properties" 
section. Let me know what you think (also regarding the "comment" in the 
example, as comments are not really part of JSON and it is only to make 
clear where the properties go):

NEW:
    3.2.  jCard Component and Syntactic Entities (RFC6350 section 6.1.1 and
            6.1.2)

    In [RFC6350] Section 6.1.1 and 6.1.2, the "BEGIN" and "END"
    properties delimit a syntactic vCard entity.  In jCard, each
    syntactic entity is represented by an array with two elements and is
    named "jCard component".  The first element is the string "vcard",
    the second element is an array of jCard properties as described in
    Section 3.3, belonging to the entity.

    Although [RFC6350] defines BEGIN and END to be properties, they MUST
    NOT appear as properties of the jCard.  Instead, the jCard component
    is sufficient to define a vCard entity.  When converting from jCard
    to vCard, the BEGIN and END properties MUST be added to enclose the
    properties of the jCard component.

    Example:

    ["vcard", [
      /* Add properties in place of this comment */
      ]
    ]

    Consumers of this format wishing to define content that can contain
    multiple syntactic entities within the same JSON document can use a
    simple JSON array, each element being a jCard component.
END
>     structured values the data type will be "array".
This is not quite what was intended. The parser should specifically NOT 
rely on the third element of the array to determine the type of the 
value. If the third element is "text", it does not mean that the fourth 
(and following) values are string values. They may be array values, if 
it is a structured text value.

What about putting the existing paragraph just after the text describing 
the remaining elements? This way the text is close to the array elements 
it affects:

OLD:

NEW:

    As described in Section 3.3.1.3, it is important for a parser to
    check the data type of the value even if it is assumed to be a string
    in most cases.  The value could turn out to be a structured value, in
    which case the data type is an array.

>     recommends that they be rendered in uppercase.  In jCard, they
Done

> put back into uppercase, as recommended in RFC 6350.
I believe this is covered sufficiently in Section 4?

I've already replied this to the Gen-ART review with the following:
> On 7/22/13 1:55 PM, Philipp Kewisch wrote:
> I'd love to hear from the WG here, but given vCard 5.0 can at least in 
> theory be completely different, I think the correct thing to do would 
> be to restrict this jCard document to 4.x and when 5.x comes around 
> create a revision of the document. Of course the text could be changed 
> so that its "valid until revised by another document", in case the 
> changes in 5.x are minor enough that no change in jCard is needed.
>
> In any case, there should be a text change that any 4.x revision is 
> allowed. For example, I recently read a suggestion for signed vCards 
> that might use a version "4.0s".
I guess this is pending what the WG says, but I think we should add the 
MUST in some form.

> you'd like me to help, which I'll be happy to do.  Here are some points:
I'll take care of the grouping changes tomorrow or Wednesday.

> bits separted by semicolons.  Now you're using those words differently.
Yes, it should be structured value. This is mainly for GENDER which can 
be for example GENDER:F and GENDER:F;grrrl. If the last part is dropped, 
it SHOULD be changed from ["gender", {}, "text", ["F", "grrl"] ] to 
["gender", {}, "text", "F"]. "Changed" should mean the process of 
modifying a vcard, for example the client receives a vcard with ["F", 
"grrl"] and wants to change the value to just "F".

I'll also double check all places where I use "component". In general I 
want to use "jCard component" as the array ["vcard", [  /* properties 
here */ ] ]. Because this has similarities to jCal, where there are 
components and sub-components, i.e ["vcalendar", [ /* properties here */ 
], [ /* sub-components here */] ].

How is this?

OLD:
    If a multi-valued text component is changed to hold only one value,
    the text component SHOULD be represented as a single primitive value,
    dropping the array completely.  Nevertheless, a more simple
    implementation might choose to retain the array, with a single
    primitive value as its element.
NEW:
    If a structured text value has optional components of which all but
    one are dropped during modification, the resulting representation
    SHOULD use a single primitive value, dropping the array completely.
    Nevertheless, a more simple implementation might choose to retain the
    array, with a single primitive value as its element.
END

--- I'm going to make a cut here and continue working on the remaining 
points soon ---

Philipp

---

From: Barry Leiba <[email-masked]>
Date: Fri, 26 Jul 2013 11:14:21 -0400

Hiya.  Sorry: the mess that is the lead-in to the Berlin IETF meeting
is causing response delays.  Let me try to respond to the points that
still need something -- I'll just snip out anything that needs no
further discussion until we have a new draft to review.

> This is not quite what was intended. The parser should specifically NOT rely
> on the third element of the array to determine the type of the value. If the
> third element is "text", it does not mean that the fourth (and following)
> values are string values. They may be array values, if it is a structured
> text value.
>
> What about putting the existing paragraph just after the text describing the
> remaining elements? This way the text is close to the array elements it
> affects:
>
> OLD:
>

OK, the fact that my suggestion doesn't work is some evidence that
something's unclear, and I don't see an improvement in your version.
First, if there's a limitation on the use of the data type in the
third array element, I'd like bullet 3 to say what that is.  Second, I
don't understand how the parser can check the data type of the value,
beyond looking at the data type that's coded in the array.  It's the
thing that generates the jCard from the vCard that knows what it's
doing -- why can't it put the information in there that the parser can
use?

I think it will help a lot to explain this more thoroughly.

> theory be completely different, I think the correct thing to do would be to
> restrict this jCard document to 4.x and when 5.x comes around create a
> revision of the document. Of course the text could be changed so that its
> "valid until revised by another document", in case the changes in 5.x are
> minor enough that no change in jCard is needed.
>
> In any case, there should be a text change that any 4.x revision is allowed.
> For example, I recently read a suggestion for signed vCards that might use a
> version "4.0s".
>
> I guess this is pending what the WG says, but I think we should add the MUST
> in some form.

Why would you want to box yourself in like that?  You should certainly
say something about how significant version changes to vCard might
require a significant update of this.  But until there's actually an
update that makes this document not work, I don't see a reason to say
in advance that if the version number changes this document no longer
applies.

I suggest putting in warnings about applicability to future versions
of vCard, but make them non-alarming, and probably without 2119 key
words.

> --- I'm going to make a cut here and continue working on the remaining

OK... and after I get home on 8 Aug, I'll be my usual responsive self
again, so we should be able to get this turned around soon after that,
I hope.

Barry