jCard: The JSON Format for vCard
RFC 7095
Revision differences
Document history
Date | Rev. | By | Action |
---|---|---|---|
2015-10-14
|
07 | (System) | Notify list changed from jcardcal-chairs@ietf.org, draft-ietf-jcardcal-jcard@ietf.org to (None) |
2014-01-16
|
07 | Jean Mahoney | Request for Last Call review by GENART Completed: Almost Ready. Reviewer: Ben Campbell. |
2014-01-14
|
07 | (System) | RFC published |
2014-01-09
|
07 | (System) | RFC Editor state changed to AUTH48-DONE from AUTH48 |
2013-12-23
|
07 | (System) | RFC Editor state changed to AUTH48 from RFC-EDITOR |
2013-12-06
|
07 | (System) | RFC Editor state changed to RFC-EDITOR from EDIT |
2013-11-11
|
07 | (System) | IANA Action state changed to RFC-Ed-Ack from Waiting on RFC Editor |
2013-11-11
|
07 | (System) | IANA Action state changed to RFC-Ed-Ack from Waiting on RFC Editor |
2013-11-11
|
07 | (System) | IANA Action state changed to Waiting on RFC Editor from Waiting on Authors |
2013-11-11
|
07 | (System) | IANA Action state changed to Waiting on Authors from In Progress |
2013-11-08
|
07 | (System) | IANA Action state changed to In Progress from Waiting on Authors |
2013-11-08
|
07 | (System) | IANA Action state changed to In Progress from Waiting on Authors |
2013-11-07
|
07 | (System) | IANA Action state changed to Waiting on Authors from In Progress |
2013-11-05
|
07 | Amy Vezza | State changed to RFC Ed Queue from Approved-announcement sent |
2013-11-05
|
07 | (System) | RFC Editor state changed to EDIT |
2013-11-05
|
07 | (System) | Announcement was received by RFC Editor |
2013-11-05
|
07 | (System) | IANA Action state changed to In Progress |
2013-11-05
|
07 | Cindy Morgan | State changed to Approved-announcement sent from Approved-announcement sent |
2013-11-05
|
07 | Cindy Morgan | IESG has approved the document |
2013-11-05
|
07 | Amy Vezza | State changed to Approved-announcement sent from Approved-announcement to be sent |
2013-11-05
|
07 | Amy Vezza | IESG has approved the document |
2013-11-05
|
07 | Amy Vezza | Closed "Approve" ballot |
2013-11-05
|
07 | Pete Resnick | State changed to Approved-announcement to be sent from Approved-announcement to be sent::Point Raised - writeup needed |
2013-11-05
|
07 | Pete Resnick | Ballot approval text was generated |
2013-11-05
|
07 | Pete Resnick | Ballot writeup was changed |
2013-10-15
|
07 | Barry Leiba | [Ballot comment] UPDATE for -06: I find this version much easier to follow -- the organizational issues have been fixed, as I see it, and … [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. |
2013-10-15
|
07 | Barry Leiba | Ballot comment text updated for Barry Leiba |
2013-10-15
|
07 | Philipp Kewisch | New version available: draft-ietf-jcardcal-jcard-07.txt |
2013-10-03
|
06 | Pete Resnick | I need to go through the remaining comments and make sure everything that needs addressing has been dealt with. |
2013-10-03
|
06 | Pete Resnick | State changed to Approved-announcement to be sent::Point Raised - writeup needed from IESG Evaluation::AD Followup |
2013-09-30
|
06 | Barry Leiba | [Ballot comment] UPDATE for -06: I find this version much easier to follow -- the organizational issues have been fixed, as I see it, and … [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 |
2013-09-30
|
06 | Barry Leiba | [Ballot Position Update] Position for Barry Leiba has been changed to Yes from Discuss |
2013-09-27
|
06 | Stephen Farrell | [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 … [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 |
2013-09-27
|
06 | Stephen Farrell | [Ballot Position Update] Position for Stephen Farrell has been changed to No Objection from Discuss |
2013-09-26
|
06 | (System) | Sub state has been changed to AD Followup from Revised ID Needed |
2013-09-26
|
06 | Philipp Kewisch | IANA Review state changed to Version Changed - Review Needed from IANA OK - Actions Needed |
2013-09-26
|
06 | Philipp Kewisch | New version available: draft-ietf-jcardcal-jcard-06.txt |
2013-07-18
|
05 | Tero Kivinen | Request for Last Call review by SECDIR Completed: Has Issues. Reviewer: Stephen Kent. |
2013-07-18
|
05 | Richard Barnes | [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." … [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. |
2013-07-18
|
05 | Richard Barnes | Ballot comment text updated for Richard Barnes |
2013-07-18
|
05 | Barry Leiba | [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. … [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. |
2013-07-18
|
05 | Barry Leiba | [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. … [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. |
2013-07-18
|
05 | Barry Leiba | Ballot comment and discuss text updated for Barry Leiba |
2013-07-18
|
05 | Cindy Morgan | State changed to IESG Evaluation::Revised I-D Needed from IESG Evaluation |
2013-07-18
|
05 | Amy Vezza | State changed to IESG Evaluation from Waiting for AD Go-Ahead |
2013-07-18
|
05 | Gonzalo Camarillo | [Ballot Position Update] New position, No Objection, has been recorded for Gonzalo Camarillo |
2013-07-18
|
05 | (System) | State changed to Waiting for AD Go-Ahead from In Last Call |
2013-07-17
|
05 | Ted Lemon | [Ballot comment] Abstract is a bit weak. How about: OLD: This specification defines "jCard", a JSON format for vCard data. NEW: This specification … [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. |
2013-07-17
|
05 | Ted Lemon | [Ballot Position Update] New position, No Objection, has been recorded for Ted Lemon |
2013-07-17
|
05 | Barry Leiba | [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 … [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. |
2013-07-17
|
05 | Barry Leiba | [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 … [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 |
2013-07-17
|
05 | Barry Leiba | [Ballot Position Update] New position, Discuss, has been recorded for Barry Leiba |
2013-07-17
|
05 | Stephen Farrell | [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 … [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. |
2013-07-17
|
05 | Stephen Farrell | [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 … [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 |
2013-07-17
|
05 | Stephen Farrell | [Ballot Position Update] New position, Discuss, has been recorded for Stephen Farrell |
2013-07-17
|
05 | Adrian Farrel | [Ballot Position Update] New position, No Objection, has been recorded for Adrian Farrel |
2013-07-17
|
05 | Richard Barnes | [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." … [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. |
2013-07-17
|
05 | Richard Barnes | [Ballot Position Update] New position, Yes, has been recorded for Richard Barnes |
2013-07-17
|
05 | Brian Haberman | [Ballot Position Update] New position, No Objection, has been recorded for Brian Haberman |
2013-07-16
|
05 | Joel Jaeggli | [Ballot Position Update] New position, No Objection, has been recorded for Joel Jaeggli |
2013-07-16
|
05 | Jari Arkko | [Ballot comment] I would like to see a response to the Gen-ART review from Ben Campbell on July 17th. |
2013-07-16
|
05 | Jari Arkko | [Ballot Position Update] New position, No Objection, has been recorded for Jari Arkko |
2013-07-16
|
05 | (System) | IANA Review state changed to IANA OK - Actions Needed from IANA OK - No Actions Needed |
2013-07-16
|
05 | (System) | IANA Review state changed to IANA OK - No Actions Needed from IANA - Review Needed |
2013-07-16
|
05 | Pearl Liang | 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 … 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. |
2013-07-16
|
05 | Stewart Bryant | [Ballot Position Update] New position, No Objection, has been recorded for Stewart Bryant |
2013-07-16
|
05 | Pete Resnick | [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 … [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. |
2013-07-16
|
05 | Pete Resnick | Ballot comment text updated for Pete Resnick |
2013-07-16
|
05 | Pete Resnick | Ballot writeup was changed |
2013-07-16
|
05 | Benoît Claise | [Ballot comment] In the introduction shows twice this sentence. The purpose of this specification is to define "jCard", a JSON format for vCard … [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. |
2013-07-16
|
05 | Benoît Claise | [Ballot Position Update] New position, No Objection, has been recorded for Benoit Claise |
2013-07-16
|
05 | Martin Stiemerling | [Ballot Position Update] New position, No Objection, has been recorded for Martin Stiemerling |
2013-07-15
|
05 | Spencer Dawkins | [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 … [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. |
2013-07-15
|
05 | Spencer Dawkins | [Ballot Position Update] New position, No Objection, has been recorded for Spencer Dawkins |
2013-07-14
|
05 | Philipp Kewisch | New version available: draft-ietf-jcardcal-jcard-05.txt |
2013-07-09
|
04 | Pete Resnick | Ballot has been issued |
2013-07-09
|
04 | Pete Resnick | [Ballot Position Update] New position, Yes, has been recorded for Pete Resnick |
2013-07-09
|
04 | Pete Resnick | Created "Approve" ballot |
2013-07-05
|
04 | Peter Yee | Request for Last Call review by GENART is assigned to Ben Campbell |
2013-07-05
|
04 | Peter Yee | Request for Last Call review by GENART is assigned to Ben Campbell |
2013-07-05
|
04 | Peter Yee | Closed request for Last Call review by GENART with state 'Withdrawn' |
2013-07-05
|
04 | Peter Yee | Request for Last Call review by GENART is assigned to David Black |
2013-07-05
|
04 | Peter Yee | Request for Last Call review by GENART is assigned to David Black |
2013-07-05
|
04 | Tero Kivinen | Request for Last Call review by SECDIR is assigned to Stephen Kent |
2013-07-05
|
04 | Tero Kivinen | Request for Last Call review by SECDIR is assigned to Stephen Kent |
2013-07-04
|
04 | Cindy Morgan | IANA Review state changed to IANA - Review Needed |
2013-07-04
|
04 | Cindy Morgan | 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 … 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. |
2013-07-04
|
04 | Cindy Morgan | State changed to In Last Call from Last Call Requested |
2013-07-04
|
04 | Pete Resnick | Placed on agenda for telechat - 2013-07-18 |
2013-07-04
|
04 | Pete Resnick | Last call was requested |
2013-07-04
|
04 | Pete Resnick | Ballot approval text was generated |
2013-07-04
|
04 | Pete Resnick | State changed to Last Call Requested from AD Evaluation::AD Followup |
2013-07-04
|
04 | Pete Resnick | Ballot writeup was changed |
2013-07-04
|
04 | Pete Resnick | Ballot writeup was generated |
2013-07-04
|
04 | Pete Resnick | Last call announcement was generated |
2013-07-02
|
04 | (System) | Sub state has been changed to AD Followup from Revised ID Needed |
2013-07-02
|
04 | Philipp Kewisch | New version available: draft-ietf-jcardcal-jcard-04.txt |
2013-06-17
|
03 | Cindy Morgan | Notification list changed to : jcardcal-chairs@tools.ietf.org, draft-ietf-jcardcal-jcard@tools.ietf.org, jcardcal@ietf.org, jcardcal@ietf.org |
2013-06-17
|
03 | Pete Resnick | AD Evaluation sent to WG |
2013-06-17
|
03 | Pete Resnick | State changed to AD Evaluation::Revised I-D Needed from AD Evaluation |
2013-06-17
|
03 | Pete Resnick | Notification list changed to : jcardcal-chairs@tools.ietf.org, draft-ietf-jcardcal-jcard@tools.ietf.org, jcardcal@ietf.org |
2013-06-14
|
03 | Pete Resnick | State changed to AD Evaluation from Publication Requested |
2013-06-14
|
03 | Pete Resnick | Changed consensus to Yes from Unknown |
2013-06-14
|
03 | Pete Resnick | Note field has been cleared |
2013-06-14
|
03 | Pete Resnick | Document shepherd changed to Bert Greevenbosch |
2013-06-10
|
03 | Amy Vezza | 1. Summary Shepherd: Bert Greevenbosch AD: Pete Resnick The document defines "jCard", which is a JSON format for vCard [RFC6350] data. The main … 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. |
2013-06-10
|
03 | Amy Vezza | Note added 'Shepherd: Bert Greevenbosch (bert.greevenbosch@huawei.com)' |
2013-06-10
|
03 | Amy Vezza | Intended Status changed to Proposed Standard |
2013-06-10
|
03 | Amy Vezza | IESG process started in state Publication Requested |
2013-06-08
|
03 | Bert Greevenbosch | IETF WG state changed to Submitted to IESG for Publication from WG Document |
2013-06-08
|
03 | Bert Greevenbosch | Changed document writeup |
2013-06-07
|
03 | Bert Greevenbosch | Changed document writeup |
2013-06-07
|
03 | Bert Greevenbosch | Changed document writeup |
2013-05-18
|
03 | Philipp Kewisch | New version available: draft-ietf-jcardcal-jcard-03.txt |
2013-04-30
|
02 | Philipp Kewisch | New version available: draft-ietf-jcardcal-jcard-02.txt |
2013-04-02
|
01 | Philipp Kewisch | New version available: draft-ietf-jcardcal-jcard-01.txt |
2013-03-26
|
00 | Philipp Kewisch | New version available: draft-ietf-jcardcal-jcard-00.txt |