Subject: [Json] Introduction

From: Douglas Crockford <[email-masked]>
Date: Thu, 06 Jun 2013 12:15:02 -0700

I propose changing the introduction to de-emphasize JavaScript and 
emphasize Data Format, conforming to the new title.

    JSON is a text format for the serialization of structured data. It
    was inspired by the object literals of JavaScript, as defined in the
    ECMAScript Programming Language Standard, Fifth Edition[ECMA].

    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 characters.

    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.

    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.  JSON stands for JavaScript Object Notation.

---

From: Tim Bray <[email-masked]>
Date: Thu, 6 Jun 2013 12:23:30 -0700

+1, except for: we need some more arguing on what goes after “a string
is...”

-T

On Thu, Jun 6, 2013 at 12:15 PM, Douglas Crockford <[email-masked]>wrote:

> ______________________________**_________________
> json mailing list
> [email-masked]
> https://www.ietf.org/mailman/**listinfo/json<https://www.ietf.org/mailman/listinfo/json>
>

---

From: Douglas Crockford <[email-masked]>
Date: Thu, 06 Jun 2013 12:25:37 -0700

> +1, except for: we need some more arguing on what goes after “a string 
In the introduction? Can't wait until the String section?

---

From: Paul Hoffman <[email-masked]>
Date: Thu, 6 Jun 2013 12:33:21 -0700

On Jun 6, 2013, at 12:25 PM, Douglas Crockford <[email-masked]> wrote:

>> +1, except for: we need some more arguing on what goes after “a string is...”

+1 

> In the introduction? Can't wait until the String section?

Nope. Preconceived notions start in the Introduction. :-)

--Paul Hoffman

---

From: "Joe Hildebrand (jhildebr)" <[email-masked]>
Date: Thu, 6 Jun 2013 19:57:16 +0000

>    A string is a sequence of zero or more characters.

How about:

"A string is a sequence of code points for almost any Unicode character."

("almost" here refers to the ones that need to be escaped)

>    The terms "object" and "array" come from the conventions of

I think this graf can be deleted.

>    a subset of JavaScript.  JSON stands for JavaScript Object Notation.

Should we add something like:

"However, JSON is now used in many different programming languages.  This
document describes a language-neutral approach."

-- 
Joe Hildebrand

---

From: Stephan Beal <[email-masked]>
Date: Thu, 6 Jun 2013 22:03:15 +0200

> "A string is a sequence of code points for almost any Unicode character."

... enclosed by double-quotes (ASCII 34 decimal, 0x22 hex).

(or whatever the convention is for being explicit about which exact
characters are being used.)

-- 
----- stephan beal
http://wanderinghorse.net/home/stephan/
http://gplus.to/sgbeal

---

From: Stephan Beal <[email-masked]>
Date: Thu, 6 Jun 2013 22:05:28 +0200

>    a subset of JavaScript.  JSON stands for JavaScript Object Notation.

i thought the expansion of the acronym was still under debate? (i don't
have an opinion either way, though.)

---

From: "Joe Hildebrand (jhildebr)" <[email-masked]>
Date: Thu, 6 Jun 2013 20:24:46 +0000

>characters are being used.)

I like it.  So:

A string is a sequence of code points for almost any Unicode character
enclosed by double-quotes (QUOTATION MARK, U+0022).

Or we can hold off on the U+ bit until the string section, which I think
would make the intro read better.

-- 
Joe Hildebrand

---

From: Tim Bray <[email-masked]>
Date: Thu, 6 Jun 2013 13:33:25 -0700

> >"A string is a sequence of code points for almost any Unicode character."

Well, surrogates are not code points for any Unicode character.  Two
surrogates may be combined to produce a code point for a character.  So if
we are going to treat unpaired surrogates as acceptable, then this is
false.  If we say that strings MUST NOT contain unpaired surrogates, then
this is correct.   -T

---

From: "Joe Hildebrand (jhildebr)" <[email-masked]>
Date: Thu, 6 Jun 2013 20:41:18 +0000

On 6/6/13 2:33 PM, "Tim Bray" <[email-masked]> wrote:

>On Thu, Jun 6, 2013 at 1:24 PM, Joe Hildebrand (jhildebr)
><[email-masked]> wrote:
>
>surrogates may be combined to produce a code point for a character.  So
>if we are going to treat unpaired surrogates as acceptable, then this is
>false.  If we say that strings MUST NOT
> contain unpaired surrogates, then this is correct.   -T

-- 
Joe Hildebrand

---

From: "Joe Hildebrand (jhildebr)" <[email-masked]>
Date: Thu, 6 Jun 2013 20:43:28 +0000

Sorry for the empty msg.  I'm still learning to live with sticky modifier
keys.

> contain unpaired surrogates, then this is correct.   -T

that was intentional.  I think unpaired surrogates are always a bug.

-- 
Joe Hildebrand

---

From: John Cowan <[email-masked]>
Date: Thu, 6 Jun 2013 17:07:09 -0400

> ... enclosed by double-quotes (ASCII 34 decimal, 0x22 hex).

No, these remarks confuse a string as an object in the data model
(which is what's being defined here) with the representation of a
string on the wire.

-- 
John Cowan   [email-masked]    http://ccil.org/~cowan
[R]eversing the apostolic precept to be all things to all men, I usually [before
Darwin] defended the tenability of the received doctrines, when I had to do
with the [evolution]ists; and stood up for the possibility of [evolution] among
the orthodox --thereby, no doubt, increasing an already current, but quite
undeserved, reputation for needless combativeness.  --T. H. Huxley

---

From: Stephan Beal <[email-masked]>
Date: Thu, 6 Jun 2013 23:20:52 +0200

> (which is what's being defined here) with the representation of a

Fair enough, but the quotes are very important to the definition of strings
for parsers and emiters. Imagine writing a parser for JSON if the quote
marks fell within the realm of the proposed definition (without the quotes
specifier). Imagine emiting strings per that definition - there's no
mention of quotation marks. Maybe this particular place in the document
isn't where it needs to be mentioned - it is part of the formal grammar,
after all.  If economy of words is a goal, trim it, by all means, but IMO
it's more correct (meaning correct for more cases, though admittedly
perhaps not for this particular level) if a quotes qualifier is included.

---

From: Stephan Beal <[email-masked]>
Date: Thu, 6 Jun 2013 23:23:08 +0200

> enclosed by double-quotes (QUOTATION MARK, U+0022).

We forgot "... any Unicode character or a JSON character escape sequence..."

though that sounds somewhat awkward.

---

From: Tim Bray <[email-masked]>
Date: Thu, 6 Jun 2013 14:36:32 -0700

Overthinking.  In the introduction, the key thing to get across is that a
string contains unicode characters.  The details of how it’s delimited and
escaped, and the few characters that are excluded and so on, can go in the
String section.  Assuming we are excluding naked surrogates:

“A string is a sequence of Unicode characters.”

On Thu, Jun 6, 2013 at 2:23 PM, Stephan Beal <[email-masked]> wrote:

> _______________________________________________
> json mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/json
>
>

---

From: "Matt Miller (mamille2)" <[email-masked]>
Date: Thu, 6 Jun 2013 21:36:37 +0000

> though that sounds somewhat awkward.

/me doffs hat

Remember is the intro.  It doesn't need to cover all of the details; that's done in other sections.

Personally, I think it would be better to say even less about the details, and more about origins and goals.

- m&m

Matt Miller < [email-masked] >
Cisco Systems, Inc.

---

From: "Pete Cordell" <[email-masked]>
Date: Thu, 6 Jun 2013 22:44:08 +0100

Original Message From: "Tim Bray"

> “A string is a sequence of Unicode characters.”

Does this allow for empty strings?  Maybe that's another detail that can be 
left to the string section.  I guess most people know that strings can be 
empty.

Pete Cordell
Codalogic Ltd
C++ tools for C++ programmers, http://codalogic.com
Read & write XML in C++, http://www.xml2cpp.com

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 7 Jun 2013 00:04:01 +0200

>   boolean, null, object, or array.

In the light of the "real-world examples" thread:
Is "unordered" still entirely true?
And should the expectation that the names are unique enter this overview?

(a string, .... -> any JSON value; we don't enumerate them all for arrays either.)

Grüße, Carsten

---

From: "Joe Hildebrand (jhildebr)" <[email-masked]>
Date: Thu, 6 Jun 2013 22:06:08 +0000

On 6/6/13 3:44 PM, "Pete Cordell" <[email-masked]> wrote:

>> ³A string is a sequence of Unicode characters.²
>
>

The empty sequence is a sequence.

-- 
Joe Hildebrand

---

From: "Joe Hildebrand (jhildebr)" <[email-masked]>
Date: Thu, 6 Jun 2013 22:08:04 +0000

>Is "unordered" still entirely true?

It is in the abstract model.  It never was in the wire-encoded.

>And should the expectation that the names are unique enter this overview?

No.  That's an edge case that doesn't belong in the intro.

-- 
Joe Hildebrand

---

From: Stephan Beal <[email-masked]>
Date: Fri, 7 Jun 2013 00:09:15 +0200

> Is "unordered" still entirely true?

i believe so. i have one C-based JSON lib which explicitly leaves the
ordering undefined and internally uses insertion order, and another C lib
which also leaves it undefined but internally uses reverse-insertion order.
Emiting does not change the order.

---

From: John Cowan <[email-masked]>
Date: Thu, 6 Jun 2013 18:12:51 -0400

Stephan Beal scripsit:

> Fair enough, but the quotes are very important to the definition of
> strings for parsers and emiters.

Oh yes.  But when you are defining the data model, define the data model;
when you are defining the format, define the format.  You'll note that the
definition of an array does not mention commas or square brackets.
By the same token, strings can contain quotation marks, the format
for which is \" or one of the alternatives.

-- 
Deshil Holles eamus.  Deshil Holles eamus.  Deshil Holles eamus.
Send us, bright one, light one, Horhorn, quickening, and wombfruit. (3x)
Hoopsa, boyaboy, hoopsa!  Hoopsa, boyaboy, hoopsa!  Hoopsa, boyaboy, hoopsa!
  --Joyce, Ulysses, "Oxen of the Sun"       [email-masked]

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 7 Jun 2013 00:16:09 +0200

> No.  That's an edge case that doesn't belong in the intro.

Hmm, the difference between a multimap (which is what the text actually appears to describe) and a map (which is what JavaScript objects are, but we don't talk about JavaScript here any more) is way more than an edge case.

Saying it is a multimap and then taking that back later in the document doesn't sound right.

Grüße, Carsten

---

From: "Matt Miller (mamille2)" <[email-masked]>
Date: Thu, 6 Jun 2013 22:26:24 +0000

/me doffs hat

I don't interpret the suggested intro text to describe a multimap, but my biases are different.

Not sure this helps but what about:

####

An object is an unordered collection of zero or more unique name/value pairs, where a name is a string and a value is a string, number, boolean, null, object, or array. 

####

- m&m

---

From: "Martin J. Dürst" <[email-masked]>
Date: Fri, 07 Jun 2013 10:40:33 +0900

> “A string is a sequence of Unicode characters.”

We can add in "zero or more" as Douglas proposed. That would make it:

"A string is a sequence of zero or more Unicode characters."

I think we don't need anything more in the Introduction.

Regards,   Martin.

>
> On Thu, Jun 6, 2013 at 2:23 PM, Stephan Beal<[email-masked]>  wrote:
>
>> On Thu, Jun 6, 2013 at 10:24 PM, Joe Hildebrand (jhildebr)<

---

From: "Pete Cordell" <[email-masked]>
Date: Fri, 7 Jun 2013 09:47:09 +0100

Original Message From: "Joe Hildebrand (jhildebr)"
>On 6/6/13 3:44 PM, "Pete Cordell"  wrote:

> The empty sequence is a sequence.

OK.  But in that case, for consistency, "zero or more" should probably be 
removed from the descriptions of object and array also.

Pete Cordell
Codalogic Ltd