IESG Narrative Minutes
Narrative Minutes of the IESG Teleconference on 2013-07-18. These are not an official record of the meeting.
Narrative scribe: John Leslie (The scribe was sometimes uncertain who was speaking.)
Corrections from:
1 Administrivia
2. Protocol Actions
2.1 WG Submissions
2.1.1 New Items
Telechat:
Telechat:
Telechat:
Telechat:
2.1.2 Returning Items
2.2 Individual Submissions
2.2.1 New Items
2.2.2 Returning Items
2.3 Status Changes
2.3.1 New Items
2.3.2 Returning Items
3. Document Actions
3.1 WG Submissions
3.1.1 New Items
Telechat:
3.1.2 Returning Items
3.2 Individual Submissions Via AD
3.2.1 New Items
3.2.2 Returning Items
3.3 Status Changes
3.3.1 New Items
3.3.2 Returning Items
3.4 IRTF and Independent Submission Stream Documents
3.4.1 New Items
3.4.2 Returning Items
1200 EDT no break
4 Working Group Actions
4.1 WG Creation
4.1.1 Proposed for IETF Review
4.1.2 Proposed for Approval
4.2 WG Rechartering
4.2.1 Under evaluation for IETF Review
Telechat::
4.2.2 Proposed for Approval
1235 EDT no break
1240 EDT back
5. IAB News We can use
6. Management Issues
Telechat::
Telechat::
Telechat::
7. Agenda Working Group News
1313 EDT Adjourned
(at 2013-07-18 07:30:07 PDT)
draft-ietf-payload-vp8
In 4.1, in the caption for figure 1:
The VP8 payload descriptor and VP8 payload header will be described
in the sequel. OPTIONAL RTP padding MUST NOT be included unless the
P bit is set.
What does "will be described in the sequel" mean? I looked for an antecedent
earlier in the document, and was unable to locate one, and the word "sequel"
never appears elsewhere in the document. I presume this is referring to some
follow-on document or later section in the current document, but that isn't
clear from the text. If by sequel you mean "sections 4.2 and 4.3" then you
should just say that. If you are using xml2rfc you can reference a section as
described here: http://xml.resource.org/xml2rfcFAQ.html#anchor17
If you are using something other than xml2rfc, I would just say "is described
in the following two sections" or else refer to the sections by title.
Also in 4.1:
Timestamp: The RTP timestamp indicates the time when the frame was
sampled at a clock rate of 90 kHz.
Is the frame sometimes sampled at other clock rates? I suspect you mean
something like this:
Timestamp: The RTP timestamp indicates the time when the frame was
sampled. The granularity of the clock is 90 kHz, so a value of 1
represents 1/90,000 of a second.
Also, the definition of timestamp doesn't say what the timestamp is relative
to. I think this would prevent interoperation, since absent any additional
specification I can think of at least three times it could be relative to: the
time the first packet was sent, the time since the beginning of the video at
which the current frame occurs, or the time at which the preceding packet was
sent. I was going to make this a DISCUSS, but on reading section 4.5, it
looks like this is the time of the frame relative to the beginning of the
video, and I suspect implementors will figure this out. However, I still
think you ought to say explicitly.
Also:
Sequence number: The sequence numbers are monotonically increasing
and set as packets are sent.
Do you mean "set in the order that packets are sent"?
At the beginning of 4.3:
The beginning of an encoded VP8 frame is referred to as an
"uncompressed data chunk" in [RFC6386], and co-serve as payload
header in this RTP format.
I guess Barry already hassled you about this; I found it equally puzzling.
From 5.1:
pictures. The positive feedback method is useful for VP8 used as
unicast. The use of RPSI for VP8 is preferably combined with a
I almost think I know what "VP8 used as unicast" means, but I'm probably wrong.
Could you clarify this sentence?
Here, First is the macroblock address (in scan order) of the first
lost block and Number is the number of lost blocks. PictureID is the
six least significant bits of the codec-specific picture identifier
in which the loss or corruption has occurred. For VP8, this codec-
specific identifier is naturally the PictureID of the current frame,
What is a macroblock address? I suspect that this is a VP8-specific term, but
it would help to say where the reader could find out more. Also, searching
back through the document I notice that the second paragraph of the
introduction talks about "decomposition of frames into square sub-blocks of
pixels" and subsequently mentions macroblocks; are macroblocks these square
sub-blocks of pixels? If so, you should say "square sub-blocks of pixels,
called macroblocks," so that the reader can clearly see the connection, rather
than having to infer it and be uncertain whether the inference is correct.
In section 7:
Integrity of the RTP packets through suitable
cryptographic integrity protection mechanism.
Where is the verb?
Thanks for documenting this!
Supporting Barry's Discuss
Holding pending resolution of late LC comments.
I agree with the other discusses and comments. I also got the impression this either hadn't been that thoroughly reviewed or else had been so controversial that folks maybe concentrated only on the difficult parts and not on ovrerall clarity. I think it'd be very good to get someone to do a pass over the whole thing to improve clarity. If there weren't so many other discusses I think this would have been one. - section 3: where do I find out how to set up a reference hierarchy? - 4.1: "PID MUST NOT be larger than" 7 surely? Also given the "SHOULD increment" doesn't that mean I can send PIDs 0,3 and 7 only and that's ok? Do you want that? - 4.1: " If the X bit is 0, the extension bit field MUST NOT be present, and all bits below MUST be implicitly interpreted as 0." If X=0 then these octets are not sent so the various flags are not "bits" really. Suggest s/bits/values/ or similar. - 4.1: I assume TL0PICIDX etc are defined somewhere. Where? Adding some references would seem to be needed. - 4.5: Why is this an example? That's confusing. So is the structure of 4.5 then 4.5.1. - Please see the secdir review [1] which raises a couple more minor issues. [1] http://www.ietf.org/mail-archive/web/secdir/current/msg04030.html
I cannot determine if the references are normative or not. Perhaps a change of
the section title would be in order? Clearly some references are normative, but
what about these, for instance:
[RFC6386] Bankoski, J., Koleszar, J., Quillio, L., Salonen, J.,
Wilkins, P., and Y. Xu, "VP8 Data Format and Decoding
Guide", RFC 6386, November 2011.
[RFC6838] Freed, N., Klensin, J., and T. Hansen, "Media Type
Specifications and Registration Procedures", BCP 13,
RFC 6838, January 2013.
See also the Gen-ART review from Elwyn Davies: s10: Are all of the refs normative? If so change the section title. The only one which I am dubious about is RFC 4566 (and there is 6386 - see next comment).
4.1:
Sequence number: The sequence numbers are monotonically increasing
and set as packets are sent.
I think you mean "strictly increasing". "Monotonically increasing" can (in some
circles) mean "nondecreasing".
6.1:
max-fr, max-fs These parameters MAY be used to signal the
capabilities of a receiver implementation. These parameters
MUST NOT be used for any other purpose.
Putting MAY and MUST NOT like directives *inside* of the media type
registration is a way to get them lost. They should be part of the spec. I
suggest just moving the above to somewhere else in section 6.
Regarding Barry's DISCUSS on downref (which I support obviously)
See RFC 3967
3. The Procedure to Be Used
For Standards Track or BCP documents requiring normative reference to
documents of lower maturity, the normal IETF Last Call procedure will
be issued, with the need for the downward reference explicitly
documented in the Last Call itself. Any community comments on the
appropriateness of downward references will be considered by the IESG
as part of its deliberations.
See http://tools.ietf.org/group/iesg/trac/wiki/DownrefRegistry
However, idnits shows:
Checking nits according to http://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
** The document seems to lack separate sections for Informative/Normative
References. All references will be assumed normative when checking for
downward references.
I guess RFC 6386 should be normative (but not 100% sure). This makes the link
with Jari's DISCUSS.
I really wish the IESG would not have to spend time on idnits problems, and I
even think the IESG should send the document back to the WG. This elevates my
feedback to a DISCUSS, even if the problems have been reported in several
DISCUSSes.
Richard will hold this document until all comments have been addressed.
Two points, highlighted below...
From the shepherd writeup:
There are a few ID nits.
1) Unused reference: RFC 3984
2) Obsolete normative reference: RFC 4288 (Obsoleted by RFC 6838)
3) Downref: Normative reference to an Informational RFC: RFC 6386
Why weren't these fixed before the document went out for Last Call and then
IESG Evaluation? I don't care about #1, but...
On #2, it's not just that 4288 is an obsolete reference. It's that the
template used in Section 6.1 is from 4288, and that template *changed* in 6838.
These idnits warnings have a purpose: you're supposed to fix the reference
*and* you're supposed to make sure that the new reference still applies, and
make any necessary changes to the document.
The template changed in 6838 ("Fragment identifier considerations" was added;
there were a couple of other minor changes, but that's the important one). The
shepherd writeup says, "The media subtype registration is compliant with the
registration template (RFC 6838)." It is not. The procedure for media-type
registrations also changed, but I don't think that affects this document.
DISCUSS POINT 1: Please update the document with respect to RFC 6838.
On #3, the downref was not called out in the Last Call message; that's required
in order to support a downref, unless the referenced document is in the downref
registry (which 6386 isn't). That means we'd need to re-run a two-week last
call for that.
DISCUSS POINT 2 (for the AD, not the authors): I think we need to re-run the
Last Call for this document.
I find a number of things in Section 4.2 to be confusing. These comments are
non-blocking, but I think it would be a very good idea to do some clarification
here:
When the X bit is set to 1 in the first octet, the OPTIONAL extension
bit field MUST be present in the second octet. If the X bit is 0,
the extension bit field MUST NOT be present, and all bits below MUST
be implicitly interpreted as 0.
This is a very odd use of "OPTIONAL"; it's not optional at all. The value of
the X bit specifies exactly what the state of the extension bit field has to
be. The same is true for the I, L, T, and K fields, which also claim to be
OPTIONAL.
I'm not making this a DISCUSS, because I think the likelihood of actual
misunderstanding is low, but I really think it's best to remove the
"OPTIONAL"s, and to state instead that these fields might or might not be
present, depending upon the values of the control bits.
I also do not understand the last clause: what does "and all bits below MUST be
implicitly interpreted as 0" mean?
Wait, I think I get it: you mean, "and no extensions (I, L, T, or K) are
permitted." Yes? Can you say it that way, or in some other, clearer way?
M: The most significant bit of the first octet is an extension flag.
The field MUST be present if the I bit is equal to one. If set
the PictureID field MUST contain 16 bits else it MUST contain 8
bits including this MSB, see PictureID.
This is a little disconnected: the second sentence makes the antecedent of the
third sentence unclear. The third sentence appears to have something to do
with the I bit.
In fact, I think the whole explanation of the extension fields would be better
off with each extension field clearly separated out. Something like this (if I
may indulge in some suggested re-wording):
-------------------
After the extension bit field follow the extension data fields that
are enabled.
The PictureID extension:
If the I bit is set to one, the PictureID extension field MUST be
present, and MUST NOT be present otherwise. The field consists of
two parts:
M: The most significant bit of the first octet is an extension flag.
If M is set, the remainder of the PictureID field MUST contain
15 bits, else it MUST contain 7 bits.
PictureID: 7 or 15 bits (not including the M bit). This is a
running index of the frames, which SHOULD begin as a random
number, MUST increase by 1 for each subsequent frame, and MUST
wrap to 0 after reaching the maximum ID (all bits set). The
7 or 15 bits of the PictureID go from most significant to
least significant, beginning with the first bit after the M bit.
The sender chooses a 7 or 15 bit index and sets the M bit
accordingly.
The TL0PICIDX extension:
If the I bit is set to one, the TL0PICIDX extension field MUST be
present, and MUST NOT be present otherwise. The field consists of
one part:
TL0PICIDX: 8 bits temporal level zero index. TL0PICIDX is a
running index for the temporal base layer frames, i.e., the
frames with TID set to 0. If TID is larger than 0, TL0PICIDX
indicates which base layer frame the current image depends on.
TL0PICIDX MUST be incremented when TID is 0. The index SHOULD
start on a random number, and MUST restart at 0 after reaching
the maximum number 255.
The TID/KEYIDX extension:
...etc...
-------------------
-- Section 4.3 --
The beginning of an encoded VP8 frame is referred to as an
"uncompressed data chunk" in [RFC6386], and co-serve as payload
header in this RTP format.
"co-serve"? What's that mean?
This discuss point should be easy to clear - there were just a couple of places
that were too unclear for me to be confident that implementers would read them
the same way.
In 4.2. VP8 Payload Descriptor
PictureID: 8 or 16 bits including the M bit. This is a running
index of the frames. The field MUST be present if the I bit is
equal to one. The 7 following bits carry (parts of) the
PictureID. If the extension flag is one, the PictureID continues
in the next octet forming a 15 bit index, where the 8 bits in the
second octet are the least significant bits of the PictureID. If
the extension flag is zero, there is no extension, and the
PictureID is the 7 remaining bits of the first (and only) octet.
The sender may choose 7 or 15 bits index. The PictureID SHOULD
start on a random number, and MUST wrap after reaching the maximum
ID. The receiver MUST NOT assume that the number of bits in
PictureID stay the same through the session.
Did I miss (or does everyone know) how to set the PictureID if you're using a
15-bit index, you have a current value that won't fit in 7 bits, and then the
sender decides for whatever reason to start using 7-bit indexes? Should the
receiver expect to see the lower 7 bits of the incremented 15-bit PictureID, a
newly random 7-bit PictureID, 0, or "something else"?
TL0PICIDX: 8 bits temporal level zero index. The field MUST be
present if the L bit is equal to 1, and MUST NOT be present
otherwise. TL0PICIDX is a running index for the temporal base
layer frames, i.e., the frames with TID set to 0. If TID is
larger than 0, TL0PICIDX indicates which base layer frame the
current image depends on. TL0PICIDX MUST be incremented when TID
is 0. The index SHOULD start on a random number, and MUST restart
at 0 after reaching the maximum number 255.
KEYIDX: 5 bits temporal key frame index. The TID/KEYIDX octet MUST
be present when either the T bit or the K bit or both are equal to
1, and MUST NOT be present otherwise. The KEYIDX field MUST be
ignored by the receiver when the K bit is set equal to 0. The
KEYIDX field is a running index for key frames. KEYIDX MAY start
on a random number, and MUST restart at 0 after reaching the
maximum number 31.
I'm not quite sure why PictureID says "MUST wrap" and TL0PICIDX and KEYIDX say
"MUST restart at 0". Are these the same thing (I would have thought so, but I'm
not the codec guy). If they are the same, and you could consider using one term
or the other in the document, that would be great. If they aren't the same,
please say more about that.
In 4.4. Aggregated and Fragmented Payloads
An encoded VP8 frame can be divided into two or more partitions, as
described in Section 1. One packet can contain a fragment of a
partition, a complete partition, or an aggregate of fragments and
partitions. In the preferred use case, the S bit and PID fields
described in Section 4.2 should be used to indicate what the packet
contains. The PID field should indicate which partition the first
octet of the payload belongs to, and the S bit indicates that the
packet starts on a new partition.
I'm not bitching about 2119 lower-case "should"s, but I am wondering if this
would be clearer if you just said "is used to indicate", etc. Even in the
common English sense of the word, "should be used to" leaves the door open that
the S bit and PID fields could be used to do something else. Same for PID field.
In 4.5.1. Partition reconstruction algorithm
2: Continue scan to detect end of partition; hence a new S=1
(previous packet was the end of the partition) is found or the
marker bit is set. If a loss it detected before the end of the
^^ "is detected", I think? but it's a nit.
I am entering no objection on the basis of a short review which indicated no impact on the routing system.
This document would probably be fine were it not for the obvious problems citied in the genart review and the other discusses. imho I have nothing more to add, I wouldn't object to the document were it actually ready.
draft-ietf-abfab-eapapplicability
I'm really happy to see this work being done. Thanks for doing it.
I support Bernard Adoba and Patrik Fältström's concerns regarding internationalization. This is covered by Barry's DISCUSS. Not point to have a second DISCUSS on the exact same topic. I trust Barry and Stephen on the resolution.
Here's the necessary DISCUSS, so's I can be the guy who gets to type a bunch of long words on his iPad: As has been discussed already, this document needs to say something about internationalization: the situation for normalization / canonicalization / comparison of strings is not covered, and needs to be.
Nit - GSSAPI used without expansion
draft-ietf-xrblock-rtcp-xr-discard-rle-metrics
Section 2: "...and indicate requirement levels for compliant implementations." What does that mean? 2119 defines the terms specifically to be used only when necessary for interoperability. To use them to indicate compliance requirements is to do something different than 2119 defines. Why was this added to the boilerplate? Section 3: I agree with Spencer that the two "SHALL"s in the first paragraph need to be removed. rsvd (3 bits): These reserved bits SHOULD be set to zero by receivers and MUST be ignored by senders. Shouldn't both statements be MUST? Is there a reason that a receiver would ever set it to other than 0? The 'E' bit MUST be set to '1' if the chunks represent packets discarded due to too early arrival and MUST be set to '0' otherwise. These are definitions, not requirements. Nobody would choose to do differently. Instead: "When the 'E' bit is set to '1', it indicates that the chunks represent packets discarded due to early arrive. Otherwise, the 'E' bit is set to '0'." The same sorts of things appear in section 4, and should be corrected there too. Section 6: "The parameter 'discard-rle' MUST be used". Instead say, "The parameter 'discard-rle' is used".
I don't agree with the assertion in section 7 - sometimes more precision is in fact enough to cause a security issue, so the statement is just wrong. Was security really considered? The secdir review [1] also raises an interesting question, about which we've planned to chat in Berlin. [1] http://www.ietf.org/mail-archive/web/secdir/current/msg04048.html
C1. In Section 3: You say that this is the same format as in RFC 3611, when in reality it's different -- it adds the E flag. Suggest: OLD: "blocks in [RFC361]." NEW: "blocks in [RFC361], with the addition of the "E" flag to indicate the reason for discard." C2. In Section 3: In RFC 3611, the reserved bits MUST be set to zero. Wy is it only a SHOULD here? C3. In Section 3: The following phrase seems backwards: "These reserved bits SHOULD be set to zero by receivers and MUST be ignored by senders" I realize that you're talking about *media* senders and receivers, but in context, this seems wrong. Suggest reversing, so that you talk about the sender/receiver of the XR block. That is also how RFC 3611 is written. C4. The Interval Metric flag has defined meanings for the values 10, 01, and 11. Please note what the meaning is when it has the value 00, or to forbid this value (MUST be one of 10, 01, or 11).
DISCUSS: The performance metrics review done by Alan Clark highlighted many points. Some are editorial, but one is a DISCUSS level type of feedback:the lack of the RFC 6390 template. The ongoing discussion is going in the right direction (Thanks Varun), and I've even seen a temp draft version. However, it doesn't contain the RFC 6390 template yet.
- draft-ietf-xrblock-rtcp-xr-jb was changed so that all occurrences of "jitter buffer" was changed to "de-jitter buffer". A reference to RFC5481 was also given. For consistency reasons, you should do the same. - expand "RR statistics. "
I have no objection to this document, and just one non-blocking comment: I find the reference to "receiver" and "sender" (in the descriptions of the reserved bits in Sections 3 and 4, and in Section 5, especially 5.2) to be confusing. The problem is that the media receiver is sending the report, and the media sender is receiving it, and the sense can easily get tangled. I suggest always using "media sender" and "media receiver", rather than just "sender" and "receiver", and explicitly saying that the media receiver generates these reports and that the media sender consumes them. Then stick with "generate" and "consume" to avoid confusion with "send" and "sender", and so on. Does that make sense?
This discuss point will be amazingly easy to resolve. It's either a one-word cut and paste error, or I don't understand RTCP-XR. In 5.1. Reporting Node (Receiver) Transmission of RTCP XR Discard RLE Reports is up to the discretion of the receiver, as is the reporting granularity. However, it is RECOMMENDED that the receiver signals all discarded packets using the method defined in this document. If all packets over a reporting period were lost, the receiver MAY use the Discard Report Block [I-D.ietf-xrblock-rtcp-xr-discard] instead. Is this "all packets were lost", or "all packets were discarded"? Doesn't RFC 3611 treats packet loss and packet discard as two different things? That's the way I understood the third paragraph in the Introduction.
In 3. XR Discard RLE Report Block The XR Discard RLE report block uses the same format as specified for the loss and duplicate report blocks in [RFC3611]. Figure 1 describes the packet format. The fields "BT", "T", "block length", "SSRC of source", "begin_seq", and "end_seq" SHALL have the same semantics and representation as defined in [RFC3611]. The "chunks" encoding the run length SHALL have the same representation as in RFC3611, but encode discarded packets. I don't think either SHALL is an RFC 2119 SHALL, but this text works just fine if you omit both SHALLs ...
draft-ietf-jcardcal-jcard
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.
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.
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.
- 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
I would like to see a response to the Gen-ART review from Ben Campbell on July 17th.
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.
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.
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.
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
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.
draft-ietf-dhc-dhcpv6-failover-requirements
(1) Section 8 says that security is only required to be specified. Why would BCP61 not apply here? That would require that a security solution is implemented but can still be turned off in a deployment. (2) 4.6: I hate the example at the end which seems to represent an abuse of DHCP and not a valid use for DHCP. I don't think we should be designing for that requirement at all. Please remove that example or replace it with something that's not an abuse of IETF protocols. I realise people might do these kinds of things, but we should not be designing protocols that are designed to make e2e hard.
- s2: expand IA on 1st use - s3: I have no idea why a set of documents of increasing specificity is considered a good thing. In particular I don't see why a design document is needed myself but whatever. - 3.1.1: what's PXE? - 3.1.3: wouldn't one also care about security here as well? I think just saying that is enough here. - 4.4: nit: m-to-m would be better as m-to-n IMO - 4.7: Is this meant to motivate a requirement? If so, then why not state the requirement? Or this might be intended to rule that scenario out of scope, in which case you should also say so. - s7, what does "secure" mean? integrity, confidentiality, non-replay? I'd suggest you might want roughly the same services as are offered by TLS or IPsec.
I would like to ensure that the authors have seen Elwyn's review. Have you?
This DISCUSS resolution might be a simple as educating a clueless AD, having a forward pointer (from the intro to section 6), reorganizing the sections, or clearly explaining what is specific to DHCPv6 versus common to DHCPv4/DHCPv6. "Why are these requirementis specific to DHCPv6?" I asked myself while reading this document. All of section 3, 4, and 5 (except maybe 4.5 and 4.6) is common for IPv4 and IPv6, right? It's only when I arrived at section 6 that I somehow understood. I should have paid more attention to the table of content. Proposal: the introduction could introduce a sentence or two, with a forward reference to section 6. However, I was wondering "There is surely a RFC for DHCPv4 failover!", but I could not find anything, except an old draft http://tools.ietf.org/html/draft-ietf-dhc-failover-12. Slightly confused, should be missing something ...
- Question: have you been thinking about all operational questions/requirements
from RFC 5706 appendix A?
-
A binding (or client binding) is a group of server data records
containing the information the server has about the addresses in
an IA or configuration information explicitly assigned to the
client.
What is "an IA"?
- "A notable example is a PXE scenario where hosts require an address during
boot." No idea what a PXE scenario is
- in order to match the statement
2. For each prefix or address pool, a server must not participate
in more than one failover relationship.
I believe you want
OLD:
4. Servers participating in multiple failover relationships for any
given pool.
NEW:
4. Servers participating in multiple failover relationships for any
given prefix or address pool.
I have no issues with the publication of this document. I do have some comments that I think will make it stronger. 1. There are instances of acronyms without expansion on the first use (e.g., PXE). 2. The models described in sections 4.1 & 4.2 talk about two servers remaining in contact with one another. I assume this is through messages outside of DHCP. If that is the case, it may be worthwhile to explicitly state that. 3. For completeness, are there scenarios that would involve cold (or warm) standby servers? 4. The discussion in 5.2.2 misses a key point. Lazy updates paired with Split Prefixes can be very efficient since there is little risk in overlapping assignments. 5. I find the wording in section 7, a little distressing. This document is just "an attempt to define requirements"? 6. Requirement 1 in section 7 is confusing for several reasons. The first sentence makes it sound like a DHCP server can have 2 failover partners. The next sentence says that a particular resource is protected by a pair-wise relationship between two servers. I don't understand the rationale for limiting the number of failover partners in a requirements statement. Additionally, this requirement is confusing given that section 4.4. talked about having m-to-m failover relationships. 7. It is unclear why section 7.1 is in this document. The requirements in section 7 describe the *minimum* set of functionality that has to be in the protocol. Why rule out other functionality?