[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Minor nits for Monday
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Greetings! Some suggested corrections: Part 1: 6.5 Header Field Extensibility reads in part: Services that support a version of OData understand and comply with the headers defined by that version. Compliance means either honoring the semantics of the header field or failing the request. ***** What drew my attention was "honoring," which I am not sure what that means. Should read: Services that support a version of OData conform to the processing requirements for the headers defined by this standards for that version. ********** 8.1.4 Header OData-Version reads in part: If not specified in a request, the service MUST assume the request is generated using the lesser of the OData-MaxVersion, if specified, and the maximum version of the protocol that the service understands. ***** I'm not sure what value the "lesser of the OData-MaxVersion" would be? or how to resolve a conflict between it and the "maximum version of the protocol that the service understands. Shouldn't this be phrased as alternatives? Suggest: If not specified in a request, the service MUST assume the request is generated using the [ whatever replaces lesser of the OData-MaxVersion], if specified, [or] the maximum version of the protocol that the service understands. ********** 8.2.7.1 Preference odata.allow-entityreferences reads in part: In the case the service [honors] the odata.allow-entityreferences preference it MUST include a Preference-Applied ***** "honors" occurs only here and one other place (8.2.7.7) Should read: [When a service responds to a request that includes] the odata.allow-entityreferences preference it MUST include a Preference-Applied ********** 8.2.7.4 Preference odata.include-annotations reads in part: The odata.include-annotations preference in a request for data or metadata is used to specify the set of annotations the client *desires* to be included, ***** Should read: The odata.include-annotations preference in a request for data or metadata is used to specify the set of annotations the client [requests] to be included, The term "desires" occurs once and only here. The term "requests" appears 88 times total, across all five parts. ********** 8.2.7.7 Preference respond-async reads in part: In the case that the service honors the respond-async preference it MUST include a Preference-Applied response header containing the respond-async preference. ***** Prior case of "honors" was 8.2.7.1. Should read: In the case that the service honors the respond-async preference it MUST include a Preference-Applied response header containing the respond-async preference. [When a service responds to a request that includes] the respond-async preference it MUST include a Preference-Applied response header containing the respond-async preference. ********** 8.3.1 Header ETag reads in part: As OData allows multiple formats for representing the same structured information, the use of weak ETags that only depend on the format-independent entity state is recommended. A strong ETag has to change whenever the representation of an entity changes, so it has to depend on the Content-Type, the Content-Language, and potentially other characteristics of the response. ***** This may be a next-time issue but I thought it was important enough to capture. This is the only use of weak versus strong Etag that I can find. And the definitions of both appear to be fairly fuzzy, as in "recommended" and "potentially other." If we can't fix now, suggest we open an issue for next time. ********** 11.4.8 Managing Stream Properties reads in part: *Stream properties are not deletable or directly creatable by the client.* The service owns their lifetime. The client can request to set the stream data to empty (0 bytes). ***** Should read: Stream properties are defined by a service. A client can request setting of the stream day, by the service, to empty (0 bytes). My attention was drawn by "directly creatable," which allows room for indirectly creatable. Is that possible? To fashion a request that the service responds to by creating a stream property? If that is true, can a request trigger the service deleting a stream? ********** 11.5.4.1 Invoking an Action reads in part: If the client *only wants* an action to be processed when the binding parameter value, ***** Should read: If the client [requests] an action to be processed when the binding parameter value, "wants" occurs only once. ********** Part 2 5.1.1.4.13 day reads in part: Services *thta* are unable ***** Should read: Services that are unable ********** 5.1.1.4.17 fractionalseconds reads in part: TimeOfDay parameter value as a non-negative decimal value smaller than 1. ***** Should read: TimeOfDay parameter value as a non-negative decimal value [less than] than 1. The following example uses the correct term. BTW, "less than" occurs 22 times across the spec. "smaller" only once. ********** 5.1.1.7 Path Expressions reads in part: Example 83: similar behavior ***** Should read: Example 83: [S]imilar behavior On second thought, this is probably a next time issue. There are 366 uses of "Example" (across all five drafts) and the majority of them are followed by lower case prose. Not many but some. ********** Part 3: 3.3.1 Attribute Uri, reads in part: The value of the Uri attribute SHOULD be URL that locates a CSDL document ***** Should read: The value of the Uri attribute SHOULD be [a] URL that locates a CSDL document As a substantive matter for the next version, shouldn't that be URI (instead of URL?) - No time to debate now so not listing that as an issue. ********** 14.5.3.1.3 Function odata.uriEncode reads in part: Example 54:: ***** Should read: Example 54: Remove doubled colon. ********** ATOM 9.1.5 Attribute title reads in part: It has no implied semantics in OData. ***** Only place where "implied" occurs. No sure why this attribute is being called out for denial of implied semantics? Should read: Delete. JSON 3.1 Controlling the Amount of Control Information in Responses reads in part: For the purpose of this section, *we* will take the following two assumptions: ***** Section 3.1 is applied, assuming that: (list appears here) (I am not sure the second assumption is an assumption but pass it for now to address in a later draft.) ********** 4.3 Relative URLs reads in part: Note that *these rules imply* that for a context URL as a base the part starting with $metadata# is ignored when resolving the relative URL. ***** Several rules are listed, then followed by citation of RFC3986. It isn't clear which "these rules" are being referenced. Moreover, I am not sure what "imply" adds here. If the goal is to say $metadata# is not ignored when resolving the relative URL, why not just say so? State it explicitly as a rule, then followed by examples. Yes? Suggest: The portion of a URL beginning with $metadata# is not ignored when resolving a relative URL. ********** 4.5.3 Annotation odata.type reads in part: Similarly, decimal, double, and single values use the same representation and do not need any additional annotations. If the value of a property is represented as a number with a single dot (.), and/or a single e or E embedded, the type should be interpreted as a decimal, double, or single value. The values NaN, INF, and -INF are serialized as strings and MUST have an odata.type annotation to specify the numeric type. ***** This may be a next time issue but "similarly" caught my attention. Then I noticed that we call out Boolean and Numeric values in the list but then lump the others together with "similarly." Then have an unrelated list of NaN, etc. If we are going to enumerate the list, which I think is a good idea, then let's enumerate the whole list. ********** 4.5.7 Annotation odata.id reads in part: By convention the entity-id is identical to the canonical URL of the entity, as defined in [OData-URL]. The odata.id annotation MUST appear if odata.metadata=full is requested or if the entiy-id *deviates* from the canonical URL of the entity. ***** Should read: The odata.id annotation MUST appear if odata.metadata=full is requested or if the entiy-id [is not identical to] the canonical URL of the entity. "deviates" appears only once and that is here. BTW, I am assuming at some point we define "identical" for purposes of comparison, such as IDs? Recalling that for some purposes: http://www.durusau.net, http://www.durusau.net/, http://www.durusau.net/index.html, are all "equivalent." Whether we mean for those to also be "identical" isn't something to leave to chance. ********** Hopefully not too many next time issues, I tried to focus on typos, etc. that are unlikely to change the meaning but sharpen the prose. I will try to find some time tomorrow to pick this back up. Hope everyone is having a great weekend! Patrick - -- Patrick Durusau patrick@durusau.net Technical Advisory Board, OASIS (TAB) Former Chair, V1 - US TAG to JTC 1/SC 34 Convener, JTC 1/SC 34/WG 3 (Topic Maps) Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300 Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps) Another Word For It (blog): http://tm.durusau.net Homepage: http://www.durusau.net Twitter: patrickDurusau -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.11 (GNU/Linux) Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQIcBAEBAgAGBQJRxfwDAAoJEAudyeI2QFGoA2kQAIEILwLv7ISPzMhHY00DD3lc IVwFhqL3UnXXK7th/hh/Nv1hxAumR/kAgNJ44/Gh7DkRLtTV9j087SG2rscpuO7e nr+GvDOsz6bKqjMvb/oFYoQR3Vodux8I6ru9jSMjGz4Cv/mzFXxWBVi/2PmImeo1 G+YJI3swy0m5fBSt4ZgVYiaLujUc2X3fwUfp0RTTq6h3jbZvJVRzTwssSMgyZsfl hMeYXwTFiqH+QM6mppe4D7QZI6/VSvjgiOZ4nYaa82BpBKXyOp3wotfNexwkAQng yQOJKzEMaZd+YcDxdTNksCfwfQ3aurWEnx7J3sXfGacKy4+nSvdgc9/EvrBcYrUp Vi/EbLcH2OfIPW6u3GR7w6c2Yv6KG57wXsoDxIL8pmBBydDJAP5xj/TRaRSRxINU TheKe4rHA/d983AIanxdXWwjyL+LzP818FYwRhRzxtGeEXEyAsw3olVbXDzPBXSJ TifNJeOAFzxd1zxrWihdjv2hNjWrqBGmtyQ8s1F0GWSaad2jgSGpP9aXbzCx5ctG v8VEpMAQfeDGwMJ+0Qu906NrQNitYp/ZKVCshTpkjZKzKO/23znH/9gfm0aYQavz bt1ymIZOpQrmRkOhgVxKOSPIhewNifCIqbg+eCCzlhUjszEcgKwNJ+/KA6Lnxu3w o6ShAQ+jWsVfW55p17Li =F/QZ -----END PGP SIGNATURE-----
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]