[Json] terminology issues in RFC4627 JSON

=JeffH <Jeff.Hodges@KingsMountain.com> Tue, 12 March 2013 13:20 UTC

Message-ID: <513F2B7D.7070105@KingsMountain.com>
Date: Tue, 12 Mar 2013 06:19:57 -0700
From: =JeffH <Jeff.Hodges@KingsMountain.com>
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/20130221 Thunderbird/17.0.3
MIME-Version: 1.0
To: json@ietf.org
Content-Type: text/plain; charset="UTF-8"; format="flowed"
Content-Transfer-Encoding: quoted-printable
Subject: [Json] terminology issues in RFC4627 JSON
Precedence: list

the message below tacitly identifies some issues with RFC4627's terminology, 
especially the term "JSON object" (I've trimmed the below to include only the 
json-specific portion) There's other issues with RFC4627's terminology to 
highlight, I can try to do that (in company with other folks' observations).

HTH,

=JeffH
------

Re: [OAUTH-WG] review: draft-ietf-oauth-json-web-token-05
https://www.ietf.org/mail-archive/web/oauth/current/msg10324.html

Subject: Re: [OAUTH-WG] review: draft-ietf-oauth-json-web-token-05
From: =JeffH <Jeff.Hodges@KingsMountain.com>
Date: Fri, 21 Dec 2012 14:41:49 -0800
To: Mike Jones <Michael.Jones@microsoft.com>
Cc: IETF oauth WG <oauth@ietf.org>



  > Aah  I now see that this is the real misunderstanding.  The string
  > representing a JSON object is not the base64url encoded form  its the
  > string representation thats parseable into a JSON object.

Thanks, yes, this is a key aspect of my difficulty in parsing the spec.

Though my misunderstanding is subtlety different than you characterized it above.

Rather, it's that my understanding from RFC4627 is that a "JSON object" /is a
string/. Thus "string representing a JSON object" reads as "string representing
a string", which implied to me that the base64-encoded form was implied.

Since you don't mean to imply that, then yes, my suggestions re terminology were
somewhat incorrect (apologies).

However, I have these revised suggestions..

  > The reason for the syntactic construction string representing a JSON object
  > is that its string representation is distinct from the abstract JSON object
  > itself.

In RFC4627 there isn't an "abstract JSON object". It says..

     JavaScript Object Notation (JSON) is a text format for the
     serialization of structured data.
                    .
                    .
     A JSON text is a serialized object or array.


..from which I understand the latter to mean..

     A JSON text is a string-serialized abstract object or array.


Unfortunately, the overloaded term "JSON object" appears to be used in some
contexts to refer to programmatic artifacts (eg the "window.JSON" javascript
object implemented in browsers), and in other contexts (such as Section "8.
Examples" in RFC4627) to refer to JSON texts.

So I suggest defining the term "JSON text object", which from nosing around
seems to be also used in various other places/documents to refer to JSON texts
that match the "object" ABNF production in RFC4627 "Sec 2.2. Objects" (note that
by definition a JSON text is a "serialized object or array" [RFC4627])..

     JSON text object   A JSON text matching the "object" ABNF production
        in Section 2.2 of [RFC4627]. JSON text objects MUST UTF-8 encoded.


So instead of using the "string representing a JSON object" construct, the JW*
specs could use "JSON text object" to refer to the non-base64-encoded things.
Then you have..

     JWT Claims Set  A JSON text object containing a set of claims. ...

     JWT Header  A JSON text object describing the
        cryptographic operations applied to the JWT. ...


<snip/>

---
end

[Json] terminology issues in RFC4627 JSON =JeffH