jCard: The JSON Format for vCard
RFC 7095

[Ballot comment]
UPDATE for -06: I find this version much easier to follow -- the organizational issues have been fixed, as I see it, and thanks very much for dealing with this -- I know it was a lot of work.

UPDATE for -07: And this version resolves all if my comments, including the minor issues that came out of the previous edit round.  I think it's ready to go.

[Ballot comment]
UPDATE for -06: I find this version much easier to follow -- the organizational issues have been fixed, as I see it, and thanks very much for dealing with this -- I know it was a lot of work.

I still have a few non-blocking comments that I hope you'll fix in one more pass.  But they are non-blocking, and if you really don't want to deal with any more updates I'll be disappointed, but will not start buying automatic weapons.  Consider these as you would last call comments.

-- Section 3.2 --
An example that's just a skeleton seems a bit useless, and there are examples in the next section.  Maybe it's good enough to say, "For examples, see Section 3.3 and Appendix B."

And for the last paragraph, maybe:
OLD
  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 object.
NEW
  Consumers of this format wishing to define content that can
  represent multiple jCards within the same JSON document can use a
  simple JSON array, each element being a jCard object.
END

-- Section 3.3 --

I think two examples would be better merged into one, with a lead-in such as this:

  In the following example, the "categories" property is
  multi-valued and has two values, while all other properties
  are single-valued:

(If you don't do this, the second example is wrong, in that it does not have "version" as the first property in the array.  Better to just merge them, eh?)

-- Section 3.3.1.2 --

I suggest that it would be best to make it clear that because the value of the "group" parameter will be used as part of the property name in the vCard version, the value is limited to characters that are permitted in vCard property names: ALPHA, DIGIT, and "-".  You might put this into the "Format definition" in the registration template.

-- Section 3.3.1.2.1 --

This one is unchanged from my original review: 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?

-- Section 3.4 --
The example is wrong, because it does not have "version" as the first property in the array.  I think the right fix here is to isolate just the "role" property array (as you do with "adr" above).

-- Section 3.4.2 --
The example is wrong, because it does not have "version" as the first property in the array.  The right fix for this one is just to add a "version" property.

-- Section 8 --

I think the "optional parameters" and "encoding considerations" would be a little better this way, because asking someone to look through a big document to find the relevant part is a lot to ask:

OLD
  Optional parameters:  version as defined for the text/vcard media
      type in [RFC6350].

  Encoding considerations:  Same as encoding considerations of
      application/json as specified in [RFC4627].
NEW
  Optional parameters:  "version", as defined for the text/vcard media
      type in [RFC6350], Section 10.1.

  Encoding considerations:  Same as encoding considerations of
      application/json as specified in [RFC4627], Section 6.
END

[Ballot comment]

Thanks for adding the new security considerations
text.

The comments below are on the earlier version, I
didn't check 'em to see if you handled 'em (but if
you did, thanks!). Let me know if I should look at
anything.

------------

- 3.4.3-3.4.5: Would it be worth pointing out a
preferred date/time form for applications that want
to use JOSE data integrity services? Not sure that'd
belong here really but I do wonder where it might
belong.

- 3.4.12 - I expected this to map to RFC 6350 section
5.1 but it doesn't. What if a 6350, 5.1 LANGUAGE
property parameter is present? Where's that go?

- section 6 is missing the boilerplate from rfc6982.
Maybe a bit late, but that's a pity. Is this section
supposed to be removed or kept in the RFC?

- please see the secdir review [1] from which it
seems some changes ought arise.

[1] http://www.ietf.org/mail-archive/web/secdir/current/msg04095.html

[Ballot comment]
C1. In Section 3.1: It would be helpful to give a brief example of "escaping mandated by JSON"
OLD: "escaping mandated by JSON."
NEW: "escaping mandated by JSON (e.g., for control characters)."

C2. In Section 3.2.1: This sentence doesn't make sense to me: "The value could turn out to be a structured value, in which case the data type is an array."  It seems like the value could also be a number, boolean, null, or object; not just array.

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

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

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

[Ballot discuss]
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 (and not yet complete, as I finish reviewing -- I hadn't been expecting it to be on the telechat quite so soon, considering when Last Call ends).  Please don't be daunted by that, and let's work on the text to make sure it says what's necessary for clarity and good implementation.

[Ballot comment]
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.

-----------------------------------------

STILL REVIEWING...

-----------------------------------------

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.

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

[Ballot discuss]

vCards can be used to represent unexpected stuff that
might have security issues, e.g. see RFC 6869.
Aren't you missing a security consideration here
along the lines of saying that a vCard->jCard
translator that knows the generic syntax but does not
know the sensitivity associated with various vCard
things is very very liable to get something wrong
leading to unexpectd exposures? I'm not sure what
text might work for that, nor am I sure if we can
really ensure that a vCard->jCard convertor (or
vice-versa) will really understand the security
issues with the translations they are doing.

[Ballot comment]

- 3.4.3-3.4.5: Would it be worth pointing out a
preferred date/time form for applications that want
to use JOSE data integrity services? Not sure that'd
belong here really but I do wonder where it might
belong.

- 3.4.12 - I expected this to map to RFC 6350 section
5.1 but it doesn't. What if a 6350, 5.1 LANGUAGE
property parameter is present? Where's that go?

- section 6 is missing the boilerplate from rfc6982.
Maybe a bit late, but that's a pity. Is this section
supposed to be removed or kept in the RFC?

- please see the secdir review [1] from which it
seems some changes ought arise.

[1] http://www.ietf.org/mail-archive/web/secdir/current/msg04095.html

[Ballot comment]
C1. In Section 3.1: It would be helpful to give a brief example of "escaping mandated by JSON"
OLD: "escaping mandated by JSON."
NEW: "escaping mandated by JSON (e.g., for control characters)."

C2. In Section 3.2.1: This sentence doesn't make sense to me: "The value could turn out to be a structured value, in which case the data type is an array."  It seems like the value could also be a number, boolean, null, or object; not just array.

C3. It seems like your rule for multi-valued properties (collapse them all into a single property) ensures that each property only has one line in the array.  So why not instead use an object, keyed on property name?  It seems like this would be simpler to program with.

IESG/Authors/WG Chairs:

IANA has reviewed draft-ietf-jcardcal-jcard-05.  Authors should review the comments and/or questions below.  Please report any inaccuracies and respond to any questions as soon as possible.

We received the following comments/questions from the IANA's reviewer:

We have a question about one of the IANA actions requested in this document.

We understand that, upon approval of this document, there are three actions which we must complete.

This document, upon approval, requests adding a single media type to the applications media type registry located at:

http://www.iana.org/assignments/media-types/application/index.html

The media type to be added is:

vcard+json

Currently the application media type library is maintained through expert review as defined in RFC 5226.

Question -> Is this a Standards Tree request?

Second, in the vCard Parameters subregistry of the vCard Elements registry, located at:

www.iana.org/assignments/vcard-elements

a single, new vCard Parameter will be registered as follows:

Namespace:
Parameter: GROUP
Reference: [ RFC-to-be, Section 3.2.1.3 ]

Third, in the vCard Value Data Types subregistry of the vCard Elements registry, located at:

www.iana.org/assignments/vcard-elements

the current early registration for vCard Value Data Type UNKNOWN will be made permanent as follows:

Value Data Type: UNKNOWN
Reference: [ RFC-to-be, Section 5 ]

We understand that these three actions are the only ones required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed
until the document has been approved for publication as an RFC.
This message is only to confirm what actions will be performed.

[Ballot comment]
Please confirm that these are all correct:

3.2.1.2: Change "In jCal these properties" to "In jCard these properties"

10.1: None of the following are normative. Please move them to 10.2:

ietf-jcardcal-jcal
RFC 5545
RFC 6321
RFC 6351

10.2: RFC 4627 is normative. Please move it to section 10.1.

[Ballot comment]
In the introduction shows twice this sentence.

  The purpose of this specification is to
  define "jCard", a JSON format for vCard data.  One main advantage to
  using a JSON-based format as defined in [RFC4627] over the classic
  vCard format is easier processing for JavaScript based widgets and
  libraries, especially in the scope of web-based applications.

[Ballot comment]
Just one please-clue-the-AD question ...

In 3.1.  Pre-processing

  vCard uses a line folding mechanism to limit lines of data to a
  maximum line length (typically 72 characters) to ensure maximum
  likelihood of preserving data integrity as it is transported via
  various means (e.g., email) - see Section 3.2 of [RFC6350].  Prior to
  converting vCard data into jCard all folded lines MUST be unfolded.

  vCard data uses an "escape" character sequence for text values and
  property parameter values.  See Section 3.4 of [RFC6350] as well as
  [RFC6868].  When such text elements are converted into jCard, the
  vCard escaping MUST be removed first.  The only escaping that may be
  applied is any escaping mandated by JSON.

Does the order here matter? Would "unfold and remove escapes" and "remove escapes and unfold" give you the same result?

I peeked at RFC 6350, and I don't THINK the order matters, but wasn't sure after reading Sections 3.2 and 3.4.

The following Last Call announcement was sent out:

From: The IESG
To: IETF-Announce
CC:
Reply-To: ietf@ietf.org
Sender:
Subject: Last Call:  (jCard: The JSON format for vCard) to Proposed Standard


The IESG has received a request from the JSON data formats for vCard and
iCalendar WG (jcardcal) to consider the following document:
- 'jCard: The JSON format for vCard'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits
final comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2013-07-18. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the
beginning of the Subject line to allow automated sorting.

Abstract


  This specification defines "jCard", a JSON format for vCard data.




The file can be obtained via
http://datatracker.ietf.org/doc/draft-ietf-jcardcal-jcard/

IESG discussion can be tracked via
http://datatracker.ietf.org/doc/draft-ietf-jcardcal-jcard/ballot/


No IPR declarations have been submitted directly on this I-D.

1. Summary

Shepherd: Bert Greevenbosch

AD: Pete Resnick

The document defines "jCard", which is a JSON format for vCard [RFC6350]
data.

The main advantage of using a JSON-based format over the classic vCard
format is easier processing for JavaScript based widgets and libraries,
especially in the scope of web-based applications.

The jCard format is designed to be semantically equivalent to the vCard
format, and conversion between the formats can be done without loss.

Finally, the jCard format is designed to be easily used by a similar
JSON-based format for calendar data: jCal. The latter format is still
under development, but is expected to be finalized soon after
finalization of jCard.

The working group thinks that a Proposed Standard publication is
suitable. It is a normative document, and therefore Standards track.
The document defines a data format that will need to be interoperable
and is planned to be used by other IETF protocols.

2. Review and Consensus

Since the document's WG adoption on 25 March 2013, it has been widely
discussed on the mailing list. In addition, other working groups have
been consulted. The IETF working groups are SCIM, WEIRDS and CALSIFY. In
addition, we have contacted W3C public-contacts-cord and the
portablecontacts Google group. In-dept comments have been received from
WEIRDS and CALSIFY. WEIRDS has a jCal example in its
draft-ietf-json-response.

All technical issues raised on the mailing list have been resolved. The
topics have not been controversial, although several topics required
some rounds of discussion. Topics included the format for date and time,
handling of default values when converting between vCard and jCard,
structured values and grouping.

Section 6 of the draft mentions three implementations. These are
ICAL.js, Py Calendar and ez-vcard. The implementations have led to some
discussions on the list, resulting in clarifications in the text.

3. Intellectual Property

No IPR declarations have been made. An e-mail reminding the requirement
to disclose known IPR was sent on 22 May to the jcardcal mailing list.
Several people, among which the author of the draft, have confirmed that
they are not personally aware of any IPR related to the draft.

4. Other Points

Section 8 contains IANA considerations. The definition tables of the
GROUP parameter and the UNKNOWN data type are similar to the definition
tables of other parameters and data types in RFC 6350. A registration
e-mail with more verbose information as required by RFC 6350 sections
10.2.4 and 10.2.5 has been sent to vcarddav@ietf.org and iana@iana.org,
and is awaiting further processing.