[calsify] AD review of draft-ietf-calext-jscontact-07

[Francesca Palombini <[e-mail]>]

Thank you for this document.

No major comments from me, only clarification questions and minor comments which you can address together with any other last call comments.

Francesca


1. -----

Section 1.5.4

> @type: String (mandatory). The allowed values are defined in the property definition that makes use of the Resource type.

All other properties are defined (for example for "type" "The type of the resource"), it would be good to add a short sentence.

2. -----

Section 1.8.1

> Section 4. All properties defined in this specification are IANA-registered properties.

Not only the properties, but also the values for some specific properties are registered, however that is not indicated in the document until the IANA section. I suggest that this be made clear (also possibly with a reference to the corresponding IANA section 4.4.3 for readibility) in each section (see for example 2.1.4, 2.3.2)

3. -----

Section 1.10

> name. This is to provide implementations with a name to map unknown or vendor-specific properties to, and which never may occur as a property in a JSContact object.

I sort of catch all, right? If we can't insure interoperability, maybe there should be some security considerations about this parameter.

4. -----

> of the JSContact MIME content type. All IANA-registered elements

> MIME type: application/jscontact+json;type=card

Should be media type not MIME (content) type. Also please add a reference to Section 4.1 from section 2.

5. -----

Section 2.1.1

Can we add a reference to the IANA registry in Section 4.3 here?

6. -----

Section 2.1.4

Please point to the relevant IANA registry/section


7. -----

Several occurrences (at least 6)

> ... MUST be either one of the following values, registered in a future RFC, or a vendor-specific value (Section 1.9.1):

I assume this is meant to be three possibilities (MUST be either A OR B OR C), but it could be interpreted as either A, which is to be registered in a future RFC, or B. I suggest to rephrase to avoid all ambiguityto:

NEW:
... MUST be either one of the following values, or registered in a future RFC, or a vendor-specific value (Section 1.9.1):

8. -----

I was surprised to see no text in the sections 2.X, at least introducing the following subsections.

9. -----

Section 2.3.2

> This SHOULD be the canonical service name including capitalization.

Probably nitpicking here, but what is the definition of "canonical service name"?

10. -----

> The type property defines the how to interpret the value.

s/the how/how

11. -----

Section 2.5.1

> countryCode: String (optional). The ISO-3166-1 country code.

This needs a normative reference to ISO-3166-1 (Reference missing)

12. -----

Section 4.1

Please forward the media type registration to the media-types mailing list for review (see https://mailarchive.ietf.org/arch/msg/media-types/sl2NFBvcaKtPH4LL7cCpTkwjy5E/ for an example)

13. -----

Section 4.2.4

> The owner of a JSContact property

I am not sure what is an owner of a property in this context. Did you mean change controller? I am not sure that it should be allowed to change change controller easily once registered, without further checks (for example by the DE or IESG).

14. -----

Section 4.2.5

> This is a comma-separated list of JSContact object types this property is allowed on.

Nitpicking but s/JSContact object types/JSContact types - even better if you can point to the registry of Section 4.3.2.

15. -----

Section 4.2.5

> Property Type:
This is the type of this property, using type signatures, as specified in Section 1.4. The property type MUST be registered in the "JSContact Types" registry.

String, Number and PatchObject are not registered in the JSContact Types registry.

16. -----

Section 4.4.1

> Change Controller:
(IETF for properties defined in RFCs from the IETF stream).

It is missing "who may request a change to this entry's definition "

17. -----

Section 4.4.3, table 6

I believe the registered value should be 1.0 - see also Section 2.1.2 where you write

> This specification registers the JSContact
version value 1.0 (Table 6).

Otherwise you should specify in 4.4.3 that it is only the major version value that is registered in the IANA registry.

18. -----

Section 6.1 References

RFC 2234 has been obsoleted by 4234 which is itself obsoleted by 5234. Please reference 5234 instead (Appendix B.1 instead of Section 6.1) and remove the reference to 2234.

6351 and 7095 could be informative

7942 could be informative but it will be removed so no problem leaving as is.

3339 4648 5322 should be normative in my opinion

8174 needs to be normative