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

From: Bert Greevenbosch <[email-masked]>
Date: Wed, 21 Aug 2013 08:58:55 +0000

Hi Barry, Philipp, all,

To mingle with the discussion, here is my suggestion to resolving some of the issues:

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

Here is my attempt to clarify:

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

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

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.

  As described in Section 3.3.1.3, a property value may be a
  structured property value, in which case it is represented as an
  array encapsulated in the array that represents the overall property.
   
  Strictly speaking, this means that the property value is not
  represented in the format indicated by the type identifier, but by an
  array instead. However, the values inside the encapsulated array are
  of the format identified by the type identifier.

  This also holds for multi-valued properties, where some of the values
  may be structured property values, and therefore are represented as an
  encapsulated array.

  It is therefore important, that the parser checks the format of each
  property value, as it may either be directly of data type, or it may be
  a structured value of which the sub-elements are of value type.
END

<QUOTE>

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

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

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

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

</QUOTE>

How about the following:

OLD:
   The vCard format is versioned.  [RFC6350] defines the VERSION
   property to be mandatory, therefore a "version" property MUST also be
   specified in a jCard component.  Similarly, the value of the version
   property MUST be "4.0".

NEW:
   The vCard format is versioned.  [RFC6350] defines the VERSION
   property to be mandatory, therefore a "version" property MUST also be
   specified in a jCard component.

   It is RECOMMENDED for the value of the "version" property in a jCard
   component compliant to this document to be equal to "4.0", similar to
   the latest version of vCard [RFC6350] at the time of writing.

   Depending on other factors, jCard implementations MAY defer from "4.0"
   for the "version" property. This could e.g. be useful when
   converting from a later version of vCard. For security reasons, parsers
   that are unfamiliar with a deviating "version" property value MUST
   reject the jCard.

END

For the last sentence, I was first considering instead:

ALTERNATIVE:
   How parsers handle a jCard with such a deviating version number is
   left out of scope of this document.
END

But I have the strong feeling that this could lead to serious trouble...

What do you think?

Best regards,
Bert

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Barry Leiba
Sent: 2013年7月26日 23:14
To: Philipp Kewisch
Cc: [email-masked]; The IESG; [email-masked]; [email-masked]
Subject: Re: [Jcardcal] Barry Leiba's Discuss on draft-ietf-jcardcal-jcard-05: (with DISCUSS and COMMENT)

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

> 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
>
> This is not quite what was intended. The parser should specifically NOT rely
> on the third element of the array to determine the type of the value. If the
> third element is "text", it does not mean that the fourth (and following)
> values are string values. They may be array values, if it is a structured
> text value.
>
> What about putting the existing paragraph just after the text describing the
> remaining elements? This way the text is close to the array elements it
> affects:
>
> OLD:
>
>   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.
>
>    The array describing the property can then be inserted into the array
>    designated for properties in the jCard component.
> 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.
>
>    As described in Section 3.3.1.3, it is important for a parser to
>    check the data type of the value even if it is assumed to be a string
>    in most cases.  The value could turn out to be a structured value, in
>    which case the data type is an array.
>
>    The array describing the property can then be inserted into the array
>    designated for properties in the jCard component.
> END

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

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

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

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

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

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

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

Barry
_______________________________________________
jcardcal mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/jcardcal

---

From: Michael Angstadt <[email-masked]>
Date: Wed, 21 Aug 2013 09:45:39 -0400

I think making "4.0" RECOMMENDED is dangerous too.  Adding a short
explanation for *why* it MUST be "4.0" might make the passage clearer and
more amendable to future vCard versions.  The reason is: (1) 4.0 is the
latest version and (2) jCard does not support earlier versions.

OLD:

NEW:
   The vCard format is versioned.  [RFC6350], the most recent version of the
   vCard standard at the time of this writing, defines the VERSION property
to
   be mandatory and the property's value to be "4.0".  Therefore, a
"version"
   property MUST also be specified in a jCard component and its value MUST
   also be "4.0".  Older versions of the vCard standard are not supported
by jCard.

END

Thanks,
Mike

On Wed, Aug 21, 2013 at 4:58 AM, Bert Greevenbosch <
[email-masked]> wrote:

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

---

From: Barry Leiba <[email-masked]>
Date: Wed, 21 Aug 2013 12:04:08 -0400

>   a structured value of which the sub-elements are of value type.

Ohhhhhhhhhh... is THAT what it's supposed to mean?  Yes, indeed.  If
Bert's text is technically correct, it clarifies the situation
perfectly for me, and I'll be very happy with it.  Thanks for that.

On Wed, Aug 21, 2013 at 9:45 AM, Michael Angstadt
<[email-masked]> wrote:
>    also be "4.0".  Older versions of the vCard standard are not supported by
> jCard.
>
> END

I'm still puzzled about why you want to expressly *forbid* using, say,
"4.1", should such a vCard version be published and should that
version remain compatible with this spec.

If that's really the consensus, I won't block it.  But I strongly urge
you not to, as I said, box yourself in that way -- I've seen too many
instances of that sort of boxing-in that was looked at later with
great regret.

Would this work?:
NEW:
   The vCard format is versioned.  [RFC6350], the most recent version of the
   vCard standard at the time of this writing, defines the VERSION property
   to be mandatory and the property's value to be "4.0".  Therefore, a
   "version" property MUST also be specified in a jCard component and its
   value MUST also be "4.0" or greater, and MUST represent a version that
   is compatible with this specification.  Older versions of the vCard standard
   are not compatible, and are not supported by jCard.
END

Barry

---

From: Cyrus Daboo <[email-masked]>
Date: Wed, 21 Aug 2013 12:41:31 -0400

Hi Barry,

>>   of the format identified by the type identifier.

The last sentence is not entirely true. Consider (example from 6350):

N:Stevenson;John;Philip,Paul;Dr.;Jr.,M.D.,A.C.P.

jCard equivalent:

['n', {}, 'text', ['Stevenson', 'John', ['Philip', 'Paul'], 'Dr.', ['Jr.', 
'M.D.', 'A.C.P.']]]

Note how the 3rd and 5th elements of the value array are themselves arrays. 
jCard draft also has an example of this in section 3.2.1.4.

Proposed text to replace the paragraph above:

  Strictly speaking, this means that the property value is not
  represented in the format indicated by the value type identifier, but by 
an
  array instead. The values inside the encapsulated array are
  of the format identified by the value type identifier, or are arrays with 
values
  of the format identified by the value type identifier.

Proposed text to replace the last paragraph of Bert's original proposal:

  It is therefore important that the parser checks the format of each
  property value, as it might either directly match the value type, or it 
might be
  a structured value where nested sub-elements directly match the value 
type.

-- 
Cyrus Daboo

---

From: Bert Greevenbosch <[email-masked]>
Date: Thu, 22 Aug 2013 02:04:14 +0000

Hi Barry, Cyrus, all,

I agree that Cyrus's text is technically more accurate.

I did some further editing and came up with text as follows:

BEGIN

  The above also holds for multi-valued properties, where some of the values
  may be structured property values, and therefore are represented as an
  encapsulated array.

  A special case is where a value in an encapsulated array consists of
  multiple components itself, in which case it is represented as yet another
  nested array, with elements matching the value type. Section 3.3.1.3
  describes this in more detail.

  The above illustrates the importance for the parser to check the format of
  each property value, as it might either directly match the value type, or
  it might be a structured value where nested sub-elements match the value
  type.
END

What do you think?

Best regards,
Bert

-----Original Message-----
From: [email-masked] [mailto:[email-masked]] On Behalf Of Cyrus Daboo
Sent: 2013年8月22日 0:42
To: Barry Leiba; Bert Greevenbosch
Cc: [email-masked]; Philipp Kewisch; The IESG; [email-masked]; [email-masked]
Subject: Re: [Jcardcal] Barry Leiba's Discuss on draft-ietf-jcardcal-jcard-05: (with DISCUSS and COMMENT)

Hi Barry,

jCard equivalent:

-- 
Cyrus Daboo

---

From: Cyrus Daboo <[email-masked]>
Date: Thu, 22 Aug 2013 10:01:19 -0400

Hi Bert,

--On August 22, 2013 at 2:04:14 AM +0000 Bert Greevenbosch 
<[email-masked]> wrote:

>   The above also holds for multi-valued properties, where some of the
> values   may be structured property values, and therefore are represented
> as an   encapsulated array.
>
>   multiple components itself, in which case it is represented as yet
> another   nested array, with elements matching the value type. Section
> 3.3.1.3   describes this in more detail.
>
>   The above illustrates the importance for the parser to check the format
> of   each property value, as it might either directly match the value
> type, or   it might be a structured value where nested sub-elements match
> the value   type.
> END
>
> What do you think?

The only thing I would say is that I used the term "value type", whereas 
you have used "type" - and both those appear in the current text. Not sure 
which is preferred but we should be consistent. I think I prefer "value 
type" just to disambiguate it from a JSON type.

-- 
Cyrus Daboo

---

From: Bert Greevenbosch <[email-masked]>
Date: Mon, 26 Aug 2013 00:44:58 +0000

Hi Cyrus, Barry, all,

> type" just to disambiguate it from a JSON type.

Yes, I noticed that one. The document normally talks about "value type" when talking about the type of the value, whereas it uses "type identifier" when referring to the signalling of the value type. I have tried to follow that convention. The JSON data type can be referred to as "JSON data type".

Most of the text is consistent on this, except for

<QUOTE section 5.1>
   To correctly implement this format, it is critical that if the
   default type is not known that the type "unknown" is used.  If this
   requirement is ignored and for example "text" is used, additional
   escaping may occur which breaks round-tripping values.
</QUOTE>

<QUOTE section 5.3>
   The following is an example of how to cope with jCard data where the
   parser was unable to identify the type.  Note how the "unknown" value
   type is not added to the vCard data and escaping, aside from standard
   JSON string escaping, is not processed.
   ...
   The following is an example of a jCard property (where the
   corresponding vCard property uses a "INTEGER" value as its default),
   and the equivalent vCard representation of that property.  It is
   assumed that the parser has knowledge of the default data type for
   the "x-karma-points" property.
</QUOTE>

I would be OK with the following changes:

Section 5.1: 'the type "unknown"' -> 'the value type "unknown"'
Section 5.2: 'to identify the type' -> 'to identify the value type'; 'default data type' -> 'default value type'

The "JSON data type" seems to be resolved already. The occurrence in 3.2.1.4 is correct, and the text in section 3.2 will be replaced. I'll open a separate thread to continue the discussion on section 3.2.

Best regards,
Bert

> From: Cyrus Daboo [mailto:[email-masked]]
> Sent: 2013年8月22日 22:01
> To: Bert Greevenbosch; Barry Leiba
> Cc: [email-masked]; Philipp Kewisch;
> [email-masked]; [email-masked]; The IESG
> >   As described in Section 3.2.1.4, a property value may be a

---

From: Bert Greevenbosch <[email-masked]>
Date: Mon, 26 Aug 2013 01:07:53 +0000

Hi all,

I have the impression that new text in 3.2 as discussed in the separate thread is considered quite acceptable.

Since I am not the editor, just the shepherd, I want to provide exactly how section 3.2 would look like through this mail.

Here is the new proposed complete section 3.2:

BEGIN

3.2.  Properties (RFC6350 section 6)

   Each individual vCard property is represented in jCard by an array
   with three fixed elements, followed by one or more additional
   elements, depending on if the property is a multi-value property as
   described in Section 3.3 of [RFC6350].

   The array consists of the following fixed elements:

   1.  The name of the property as a string, but in lowercase.

   2.  An object containing the parameters as described in Section 3.3.

   Example:

   ["vcard",
     [
       ["version", {}, "text", "4.0"],
       ["fn", {}, "text", "John Doe"],
       ["gender", {}, "text", "M"],
       ...
     ]
   ]

END;

Notice that I left the original example in between the new text.

Do folks agree with the new section 3.2?

Best regards,
Bert