Subject: Re: [Json] Some thoughts on the "text model" discussion - terminology

From: =JeffH <[email-masked]>
Date: Thu, 08 Aug 2013 20:12:22 -0700

[email-masked] said:
 >
 > - The discussion at the beginning regarding "a JSON object" vs. "a JSON
 > text" was very revealing to me because it leads me to believe that
 > nowhere do we have a general concept of a "JSON entity" aside from [its]
 > encoding or representation in memory.

Although I agree the above touches upon the overall issue, I think it sort of 
misstates the issue.

The issue is, IMV, that people use the term "JSON object" to refer to either, or 
both, "serialized data in JSON format" or/and "structured data [in memory]" -- 
e.g., the latter often occurs as "object literals" or "array literals" in 
JavaScript.

Thus the term in common usage for what you're referring to as a "JSON entity" 
/is/ (for the most part, AFAICT) "JSON object".

And, because RFC4627 is inconsistent in its terminology, it isn't successful in 
unambiguously differentiating between (a) "serialized data in JSON format" and 
(b) "structured data [in memory]", and also does not provide clearly distinct 
names for each of those things.

Now, since RFC4627 is explicitly a MIME Media Type registration vehicle, it was 
clear to me, when I was referred to it, that it is describing "serialized data 
in JSON format". But this isn't necessarily clear to all readers, an example 
being the folks writing the JWT spec, hence my comments on that spec, which I 
related here to the JSON WG a while back [1].

In terms of rectifying the lack of clarity in RFC4627 between (a) and (b), I 
suggest making some changes to the terminology in RFC4627 -- i.e., via 
draft-ietf-json-rfc4627bis -- along the below (rough draft) lines [2].

HTH,

=JeffH

[1] [Json] terminology issues in RFC4627 JSON
     https://www.ietf.org/mail-archive/web/json/current/msg00211.html

[2] ...
 > Network Working Group                                       D. Crockford
 > Request for Comments: 4627                                      JSON.org
 > Category: Informational                                        July 2006
 >
 >
 >
 > The application/json Media Type for JavaScript Object Notation (JSON)
 >
 >
<snip>
 >
 > Abstract
 >
 >    JavaScript Object Notation (JSON) is a lightweight, text-based,
 >    language-independent data interchange format.  It was derived from
 >    the ECMAScript Programming Language Standard.  JSON defines a small
 >    set of formatting rules for the portable representation of structured
 >    data.
 >
 > 1. Introduction
 >
 >
<snip>

 >    JSON can represent four primitive types (strings, numbers, booleans,
 >    and null) and two structured types (objects and arrays).
 >
 >    A string is a sequence of zero or more Unicode characters [UNICODE].
 >
 >    An object is an unordered collection of zero or more name/value
 >    pairs, where a name is a string and a value is a string, number,
 >    boolean, null, object, or array.
 >
 >    An array is an ordered sequence of zero or more values.

rewrite the immediately above four paragraphs as:

    A JSON text is data serialized according to the grammar specified in
    Section 2.  A JSON text is composed of some combination of four primitive
    JSON text entities: strings, numbers, booleans, and null; as well as two
    structured JSON text entities: objects and arrays.

    A JSON text string is a sequence of zero or more Unicode characters
    [UNICODE].

    A JSON text object is an unordered collection of zero or more
    name/value pairs, where a name is a JSON text string and a value
    is a one of the following JSON text entities: string, number, boolean,
    null, object, or array.

    A JSON text array is an ordered sequence of zero or more JSON text
    values.

 >    The terms "object" and "array" come from the conventions of
 >    JavaScript.
 >
 >    JSON's design goals were for it to be minimal, portable, textual, and
 >    a subset of JavaScript.
 >
 >
 >
 > 1.1. Conventions Used in This Document
 >
 >
 >    The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 >    "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
 >    document are to be interpreted as described in [RFC2119].
 >
 >    The grammatical rules in this document are to be interpreted as
 >    described in [RFC4234].
 >
 > 2. JSON Grammar
 >
 >
 >    A JSON text is a sequence of tokens.  The set of tokens includes six
 >    structural characters, strings, numbers, and three literal names.
 >
 >    A JSON text is a serialized object or array.
 >
 >       JSON-text = object / array

rewrite the immediately above two paragraphs as:

    A JSON text is a serialized object or array, described by this ABNF
    [RFC5234]:

       JSON-text = object / array

    The serialized object or array is constructed as a sequence of tokens.
    The set of tokens includes six structural characters, as well as
    JSON text strings, JSON text numbers, and three literal tokens. The
    structural characters are used to delimit objects, arrays, names, and
    values.

 >    These are the six structural characters:
 >
 >       begin-array     = ws %x5B ws  ; [ left square bracket
 >
 >       begin-object    = ws %x7B ws  ; { left curly bracket
 >
 >       end-array       = ws %x5D ws  ; ] right square bracket
 >
 >       end-object      = ws %x7D ws  ; } right curly bracket
 >
 >       name-separator  = ws %x3A ws  ; : colon
 >
 >       value-separator = ws %x2C ws  ; , comma
 >
 >    Insignificant whitespace is allowed before or after any of the six
 >    structural characters.
 >
 >       ws = *(
 >                 %x20 /              ; Space
 >                 %x09 /              ; Horizontal tab
 >                 %x0A /              ; Line feed or New line
 >                 %x0D                ; Carriage return
 >             )
 >
 > 2.1. Values
 >
 >
 >    A JSON value MUST be an object, array, number, or string, or one of
 >    the following three literal names:

rewrite the immediately above paragraph as:

    A JSON text value MUST be an object, array, number, or string, or one of
    the following three literal names:

 >
 >       false null true
 >
 >
 >    The literal names MUST be lowercase.  No other literal names are
 >    allowed.
 >
 >          value = false / null / true / object / array / number / string
 >
 >          false = %x66.61.6c.73.65   ; false
 >
 >          null  = %x6e.75.6c.6c      ; null
 >
 >          true  = %x74.72.75.65      ; true
 >
 > 2.2. Objects

2.2. JSON Text Objects

 >
 >
 >    An object structure is represented as a pair of curly brackets
 >    surrounding zero or more name/value pairs (or members).

    A JSON text object constructed as a pair of curly brackets
    surrounding zero or more name/value pairs (or members).

 >                                                          A name is a
 >    string.  A single colon comes after each name, separating the name
 >    from the value.  A single comma separates a value from a following
 >    name.  The names within an object SHOULD be unique.
 >
 >       object = begin-object [ member *( value-separator member ) ]
 >       end-object
 >
 >       member = string name-separator value
 >
 > 2.3. Arrays
 >
 >    An array structure is represented as square brackets surrounding zero
 >    or more values (or elements).  Elements are separated by commas.

2.3. JSON Text Arrays

    A JSON text array is constructed as square brackets surrounding zero
    or more values, also known as array elements.  Array elements are
    separated by commas.

 >       array = begin-array [ value *( value-separator value ) ] end-array
 >
 > 2.4. Numbers
 >
 >
 >    The representation of numbers is similar to that used in most
 >    programming languages.  A number contains an integer component that
 >    may be prefixed with an optional minus sign, which may be followed by
 >    a fraction part and/or an exponent part.

2.4. JSON Text Numbers

    The representation of numbers is similar to that used in most
    programming languages.  A JSON text number contains an integer
    component that may be prefixed with an optional minus sign,
    which may be followed by a fraction part and/or an exponent part.

 >    Octal and hex forms are not allowed.  Leading zeros are not allowed.
 >
 >    A fraction part is a decimal point followed by one or more digits.
 >
 >    An exponent part begins with the letter E in upper or lowercase,
 >    which may be followed by a plus or minus sign.  The E and optional
 >    sign are followed by one or more digits.
 >
 >    Numeric values that cannot be represented as sequences of digits
 >    (such as Infinity and NaN) are not permitted.
 >
 >
 >          number = [ minus ] int [ frac ] [ exp ]
 >
 >          decimal-point = %x2E       ; .
 >
 >          digit1-9 = %x31-39         ; 1-9
 >
 >          e = %x65 / %x45            ; e E
 >
 >          exp = e [ minus / plus ] 1*DIGIT
 >
 >          frac = decimal-point 1*DIGIT
 >
 >          int = zero / ( digit1-9 *DIGIT )
 >
 >          minus = %x2D               ; -
 >
 >          plus = %x2B                ; +
 >
 >          zero = %x30                ; 0
 >
 > 2.5. Strings
 >
 >
 >    The representation of strings is similar to conventions used in the C
 >    family of programming languages.  A string begins and ends with
 >    quotation marks.

2.5. JSON Text Strings

    The representation of strings is similar to conventions used in the C
    family of programming languages.  A JSON text string begins and ends
    with quotation marks.

 >                     All Unicode characters may be placed within the
 >    quotation marks except for the characters that must be escaped:
 >    quotation mark, reverse solidus, and the control characters (U+0000
 >    through U+001F).
 >
 >    Any character may be escaped.  If the character is in the Basic
 >    Multilingual Plane (U+0000 through U+FFFF), then it may be
 >    represented as a six-character sequence: a reverse solidus, followed
 >    by the lowercase letter u, followed by four hexadecimal digits that
 >    encode the character's code point.  The hexadecimal letters A though
 >    F can be upper or lowercase.  So, for example, a string containing
 >    only a single reverse solidus character may be represented as
 >    "\u005C".
 >
 >    Alternatively, there are two-character sequence escape
 >    representations of some popular characters.  So, for example, a
 >    string containing only a single reverse solidus character may be
 >    represented more compactly as "\\".
 >
 >    To escape an extended character that is not in the Basic Multilingual
 >    Plane, the character is represented as a twelve-character sequence,
 >    encoding the UTF-16 surrogate pair.  So, for example, a string
 >    containing only the G clef character (U+1D11E) may be represented as
 >    "\uD834\uDD1E".
 >
 >          string = quotation-mark *char quotation-mark
 >
 >          char = unescaped /
 >                 escape (
 >                     %x22 /          ; "    quotation mark  U+0022
 >                     %x5C /          ; \    reverse solidus U+005C
 >                     %x2F /          ; /    solidus         U+002F
 >                     %x62 /          ; b    backspace       U+0008
 >                     %x66 /          ; f    form feed       U+000C
 >                     %x6E /          ; n    line feed       U+000A
 >                     %x72 /          ; r    carriage return U+000D
 >                     %x74 /          ; t    tab             U+0009
 >                     %x75 4HEXDIG )  ; uXXXX                U+XXXX
 >
 >          escape = %x5C              ; \
 >
 >          quotation-mark = %x22      ; "
 >
 >          unescaped = %x20-21 / %x23-5B / %x5D-10FFFF
 >
 > 3. Encoding
 >
 >
 >    JSON text SHALL be encoded in Unicode.  The default encoding is
 >    UTF-8.
 >
 >    Since the first two characters of a JSON text will always be ASCII
 >    characters [RFC0020], it is possible to determine whether an octet
 >    stream is UTF-8, UTF-16 (BE or LE), or UTF-32 (BE or LE) by looking
 >    at the pattern of nulls in the first four octets.
 >
 >            00 00 00 xx  UTF-32BE
 >            00 xx 00 xx  UTF-16BE
 >            xx 00 00 00  UTF-32LE
 >            xx 00 xx 00  UTF-16LE
 >            xx xx xx xx  UTF-8
 >
< snip off rest of spec, you get the idea, changes of the above flavor ought to 
be carried throughout the doc >

---
end