AW: AW: ACTION-733: Go over exi for json draft and ask the group for review in preparation for publication

Hi Don,

> Draft is looking good.  Great work Daniel!

Thanks for your positive feedback and thanks for all your comments!

Please find my response inline.

(Note: updates currently in my local copy given that I would like to give others the chance to take a look first)
See http://services.w3.org/htmldiff?doc1=http%3A%2F%2Fwww.w3.org%2FXML%2FEXI%2Fdocs%2Fjson%2Fexi-for-json.html&doc2=http%3A%2F%2Fwww.peintner.org%2Ftmp%2Fexi-for-json.html for an HTML diff.

Thanks,

-- Daniel



> Editorial comments:
> ====================================================================================================
> 1.  RFC 7159 is not the normative document, rather it is an amplification.  ECMA-404 is normative.  Both references should be provided in this document, please add:
> 
> JSON Data Interchange Format, ECMA Standard ECMA-404, first edition, October 2013.
> http://www.ecma-international.org/publications/standards/Ecma-404.htm

We did have once the discussion during our telecon and decided to stick with RFC (see http://www.w3.org/2015/12/15-exi-minutes.html#item06).
That said, I am open to discuss this topic again.



> =========================================================
> 2. Concept
>
> Change
> =============================
> A number of mappings between JSON structures and XML documents have been
> proposed. Because none of these mappings is ideal in all circumstances,
> this specification does not define such a mapping, and instead converts 
>  JSON structures to XML event streams.
> =============================
>
> to
> =============================
> A number of general mappings between JSON object structures and XML
> documents have been proposed. Because none of these mappings is ideal
> in all circumstances, this specification does not attempt to define such
> a general mapping.
>
> Rather, the EXI for JSON approach is to equivalently convert any well-formed
> JSON structures to XML event streams that are directly suitable for
> datatype-aware EXI compression.  Lossless round-trip conversion back to the
> original JSON structures is supported.
> =============================

Implemented with some one minor change ("EXI representation" instead of "EXI compression").

> Editorial note:
> "Do we want to make sure that these EXI options are not overridden?"
>
> I think that this is related to interoperability.  We could be silent about it.  
> However it is quite conceivable that simple JSON-EXI converters might be written, 
> for example in client-side Javascript, in a browser/server, or even in hardware. 
> If failure to conform an JSON-EXI stream to the recommended options might break
> simple converters (i.e. minimalist EXI-JSON converters, not full EXI engines), then
> we should require the correct values.

I think the two options "strict" and "schemaId" should not be overridden.
That said, I think other options should be tunable...


> Most of the options look simple enough; questions follow.
> http://www.w3.org/TR/exi/#exiOptionsInOptionsField
>
> Default EXI Option compression=false which doesn't seem like what we want.
>
> Allowing different/smaller blockSize (default 1,000,000) would allow smaller-footprint implementations

I tend to say that we should stick with the default value "false" for "compression". Doing so allows to support much smaller implementations.

> The schemaId should include version information since approach in this document might eventually change.  Thus
>
> - "schema-for-json-1" or, better yet,
> - "schema-for-json-1-draft"
> 
> Also update year and identifier:
>
> Prefix	Namespace Name
> j	http://www.w3.org/2015/EXI/json
>
> to use  http://www.w3.org/2016/EXI/json-1-draft
>
> =================================================
> B Schema for JSON
>
> change
> xmlns:j="http://www.w3.org/2015/EXI/json"
> 
> to
> xmlns:j="http://www.w3.org/2016/EXI/json-1-draft"

(Note I moved similar comments to this section)

To me no version information means always version 1. A second version might add the "2".

Adding "draft" might seem useful. On the contrary, often it is not useful assuming no change... mhhh, not sure.

Hence, I would like to hear others opinion.


> ========================================================
> Sections 3 and 3.2.  Whenever mentioning conversion from EXI to JSON,
> need to note that the only eligible EXI must conform to the rules of this document.
> Am hoping to avoid individuals reading the document from misinterpreting that this
> is a general approach.
>
> Existing prose:
> =============================
> JSON data can be converted to EXI.
> At the same time, EXI streams, following the rules of this specification, can be converted to JSON.
> =============================
>
> Suggested rephrase:
> =============================
> Any valid JSON data can be converted to equivalent EXI.
> Similarly, corresponding EXI streams that conform to the rules and schema of
> this specification can be converted to equivalent JSON.
> This approach is not suitable for arbitrary EXI or XML data.
> =============================
>
> Also "on the contrary,"
> to   "for equivalent round-trip conversion,"

Sounds good to me.


> =======================================================
> 3.1 subsections.
> 
> Style question:  shouldn't the j: prefix appear in the prose when referring
>  to one of the encoding elements?  For example,
> 
> =============================
> 3.1.2 JSON array
> A JSON array is transformed to an array element whose members are the values of the JSON array.
> =============================
>
> to
>
> =============================
> 3.1.2 JSON array
> A JSON array is transformed to a j:array element whose members are the values of the JSON array.
> =============================

Agree!


> =====================================================
> d. Typo:
> =============================
>3.1.4 JSON number
>
> A JSON string MAY be transformed to a number element.
> =============================
> 
> to
>
> =============================
> 3.1.4 JSON number
>
> A JSON *number* MAY be transformed to a j:number element.
> =============================

Thanks!


> ==================================================
> Please check the html markup for highlighting "numbers" in the following Editorial note:
>
> "The working group considers the xsd:decimal representation for numbers currently at risk..."
>
> Wondering why is this so?  We should explain our concerns so that the feedback might be helpful.

We could extend "The benefit and the need of xsd:decimal is unclear." By adding additional information like

"EXI for JSON provides already xsd:double support. Also, requiring additional code for reversing the fractional portion of the Decimal value may not be desired."

What do you think?


> ===================================================
> Section C.1 phrasing
>
> "The selection of these additional datatypes concluded based on the foreseen efficiency and the use in JSON documents."
>
> to
>
> "The selection of these additional datatypes is based on their foreseen efficiency and potential usage in JSON documents."

Sounds good!


> ====================================================================================================
> Section C.2 Character Encoding
> =============================
> JSON text may be encoded in UTF-8, UTF-16, or UTF-32 (see JSON Character Encoding).
> EXI for JSON does not provide any mean to transmit these encodings information.
> Processors are recommended to use the default UTF-8 when creating JSON documents.
> The preservation of the original JSON character encoding does seem to provide a substantial benefit.
> =============================
>
> to
> 
> =============================
> JSON text may be encoded in UTF-8, UTF-16, or UTF-32 (see JSON Character Encoding).
> EXI for JSON matches the JSON specification in that it does not provide an explicit label for the included characters.
> If possible without loss of correctness, processors are recommended to use the default UTF-8 for maximum potential compression when creating JSON documents.
> =============================

Sounds good. I would rather state the last sentence as follows, ok?
"If possible without loss of correctness, processors are recommended to use the default UTF-8 for maximum interoperability when creating JSON documents."

> ====================================================================================================
> Consider adding an Editorial note:
> 
> "The working group asks for feedback whether noting the original encoding
> (UTF-8, UTF-16, or UTF-32) is considered useful."
> 
> We can probably guess that someone will make the case for strict round-tripping,
>  even if UTF-8 is used when compressed.
>
> To guarantee symmetric encoding/decoding while allowing processors leeway during
> compression likely means that we would have to add a property or attribute for
>  "originalEncoding" with default UTF8 and optional enumerations UTF16, UTF32.
>
> On the other hand we can play the same JSON game and simply remain silent about it...

Adding an editorial note makes sense to me.


> ================================================
> Section D. Examples.
>
> Another simple example (or a longer example) that shows parent-child nesting of
> JSON objects down a level would be useful.

I added a more complex example. 
Please feel free to provide me with additional JSON examples...
 

> ===============================================
> Choice of words:  I usually find that the word "very" is superfluous and adds very little value...  Suggest removing it, no other wording is affected.

Makes sense.

I believe we do have 4 appearances in "Abstract", "1. Introduction" and "2. Concept".
I removed all of them.


> =============================================
> Attached is schema-for-json.xsd documentation in .pdf form (generated by
> XML Spy and Word) to facilitate review.
>
> Check question:  it appears that the scope of the uniqueness constraint is
> limited to the map element it is defined within.
> http://www.w3.org/TR/xmlschema-0/#specifyingUniqueness
> =============================================

I think the uniqueness is w.r.t. to the key and the XML schema takes already care of that? Do you think differently?





On 12/16/2015 8:25 AM, Peintner, Daniel (ext) wrote:
> All,
>
> based on the feedback so far I integrated the following updates to the EXI for JSON document [1].
>
> * marked the exi:decimal datatype for the other element at risk
> * created non-normative appendix section for "Design Decisions"
>
> The document seems functionally complete and I would like to ask everyone for a final review and feedback. The plan foresees a first publication by the beginning of next year.
>
> Thanks,
>
> -- Daniel
>
> [1] http://www.w3.org/XML/EXI/docs/json/exi-for-json.html
>
> ________________________________
> Von: Efficient XML Interchange Working Group Issue Tracker [sysbot+tracker@w3.org]
> Gesendet: Dienstag, 8. Dezember 2015 16:53
> An: public-exi@w3.org
> Betreff: ACTION-733: Go over exi for json draft and ask the group for review in preparation for publication
>
> ACTION-733: Go over exi for json draft and ask the group for review in preparation for publication
>
> https://www.w3.org/2005/06/tracker/exi/actions/733
>
> Assigned to: Daniel Peintner


all the best, Don
-- 
Don Brutzman  Naval Postgraduate School, Code USW/Br       brutzman@nps.edu
Watkins 270,  MOVES Institute, Monterey CA 93943-5000 USA   +1.831.656.2149
X3D graphics, virtual worlds, navy robotics http://faculty.nps.edu/brutzman

Received on Monday, 11 January 2016 12:29:50 UTC