Subject: [weirds] JSON naming

From: Andy Newton <[email-masked]>
Date: Fri, 15 Jun 2012 14:06:06 +0000

In working on the Using HTTP draft, I've attempted to make clearer the JSON naming section since it received feedback on this list and my sense is that  parts of it were confusing. Hopefully this is clearer. Since the draft is not yet ready for publication but I want feedback on this, I'm sending just this section.

Your comments are much appreciated.

-andy

6.2.  Naming

   Clients processing JSON [RFC4627] responses SHOULD ignore values
   associated with unrecognized names.  Servers MAY insert values
   signified by names into the JSON responses which are not specified in
   this document.  Insertion of unspecified values into JSON responses
   SHOULD have names prefixed with a short identifier followed by an
   underscore followed by a meaningful name.

   For example, a JSON object may have "handle" and "remarks" formally
   documented in a specification.  Clients adhering to that
   specification will have appropriate knowledge of the meaning of
   "handle" and "remarks".

   Consider the following JSON response with JSON names.

     {
       "handle" : "ABC123",
       "remarks" : [
         "she sells seas shells",
         "down by the seashore"
       ]
     }

                                 Figure 3

   If The Registry of the Moon desires to express information not found
   in the specification, it might select "lunarNic" as its identifying
   prefix and insert, as an example, the name
   "lunarNic_beforeOneSmallStep" to signify registrations occuring
   before the first moon landing and the name
   "lunarNic_harshMistressNotes" containing other descriptive text.

   Consider the following JSON response with JSON names, some of which
   should be ignored by clients without knowledge of their meaning.

     {
       "handle" : "ABC123",
       "lunarNic_beforeOneSmallStep" : "TRUE THAT!",
       "remarks" : [
         "she sells seas shells",
         "down by the seashore"
       ],
       "lunarNic_harshMistressNotes" : [
         "In space,",
         "nobody can hear you scream."
       ]
     }

                                 Figure 4

   Insertion of unrecognized names ignored by clients may also be used
   for future revisions to specifications and specifications deriving
   extensions from a base specification.

   JSON names SHOULD only consist of the alphabetic ASCII characters A
   through Z in both uppercase and lowercase, the numerical digits 0
   through 9, underscore characters, and SHOULD NOT begin with an
   underscore character, numerical digit or the characters "xml".  The
   following describes the produciton of JSON names in ABNF [RFC5234].

   ABNF for JSON names

     name = ALPHA *( ALPHA / DIGIT / "_" )

                                 Figure 5

   This restriction is a union of the Ruby programming language
   identifier syntax and the XML element name syntax and has two
   purposes.  First, client implementers using modern programming
   languages such as Ruby or Java may use libraries that automatically
   promote JSON names to first order object attributes or members (e.g.
   using the example above, the values may be referenced as
   network.handle or network.lunarNic_beforeOneSmallStep).  Second, a
   clean mapping between JSON and XML is easy to accomplish using the
   JSON representation.

   Clients processing JSON responses MUST be prepared for values
   specified in the registry response documents to be absent from a
   response as no JSON value listed is required to appear in the
   response.  In other words, servers MAY remove values as is needed by
   the policies of the server operator.

---

From: Leif Johansson <[email-masked]>
Date: Fri, 15 Jun 2012 16:18:06 +0200

On 06/15/2012 04:06 PM, Andy Newton wrote:
> In working on the Using HTTP draft, I've attempted to make clearer
> the JSON naming section since it received feedback on this list and
> my sense is that  parts of it were confusing. Hopefully this is
> clearer. Since the draft is not yet ready for publication but I
> want feedback on this, I'm sending just this section.
> 

Another approach taken by SCIM is to stick extensions in
their own structs and register the key thus:

{
"base": "spec",
number: 1,
"name": "bla",
"urn:foo:my:extension": { "bla": 4711 }
}

---

From: Alex Sergeyev <[email-masked]>
Date: Fri, 15 Jun 2012 23:22:29 -0400

On Fri, Jun 15, 2012 at 10:18 AM, Leif Johansson <[email-masked]> wrote:

>> the JSON naming section...
>> ...
>> First, client implementers using modern programming
>> promote JSON names to first order object attributes or members...

> "urn:foo:my:extension": { "bla": 4711 }

Nice, something I can talk about :)

If you ask me "would programmers have problem with
'urn:foo:my:extension' ", I'd say "NO". There is nothing that prevents
anyone from using those keys in Javascript nor Ruby (I don't think
I've seen Java doing properties from JSON but I know very little of
it, might be worth to check if you use it). Both Javascript and Ruby
(and I'd say here Python and Perl too) also will not have problems
with keys in non latin-1 encoding.

BUT

I like idea of making life of developers a bit easier. We don't know
what tools might be out there that would require "decent" keys, at
least at top level of the structure to nicely store WEIRDS results.

I can imagine someone using DB to store data from keys they care
about. Who knows.  Also converting names 1:1 to plain vanilla,
no-namespace XML would be so much easier (and, if you wish,
transforming it to neat, some-schema-conforming using XSLT).

Andy's naming "policy" is not limiting too much and not requires
"prefixes". I'd  support that.

Alex.

---

From: Leif Johansson <[email-masked]>
Date: Sat, 16 Jun 2012 23:45:45 +0200

On 06/16/2012 05:22 AM, Alex Sergeyev wrote:
>>> In working on the Using HTTP draft, I've attempted to make
>>> clearer the JSON naming section... ... First, client
>>> implementers using modern programming languages such as Ruby or
>>> Java may use libraries that automatically promote JSON names to
>>> first order object attributes or members...
> 
>> Another approach taken by SCIM is to stick extensions in their
>> own structs and register the key thus:
>> 
>> { "base": "spec", number: 1, "name": "bla", 
>> "urn:foo:my:extension": { "bla": 4711 } }
> 
> 
> 'urn:foo:my:extension' ", I'd say "NO". There is nothing that
> prevents anyone from using those keys in Javascript nor Ruby (I
> don't think I've seen Java doing properties from JSON but I know
> very little of it, might be worth to check if you use it). Both
> Javascript and Ruby (and I'd say here Python and Perl too) also
> will not have problems with keys in non latin-1 encoding.
> 
> BUT
> 
> I like idea of making life of developers a bit easier. We don't
> know what tools might be out there that would require "decent"
> keys, at least at top level of the structure to nicely store WEIRDS
> results.
> 

Being a coder myself (at least sometimes) I know that ':' in
strings isn't an issue.

---

From: Alex Sergeyev <[email-masked]>
Date: Sat, 16 Jun 2012 22:22:34 -0400

Leif,

> Being a coder myself (at least sometimes) I know that ':' in

But what value do you see using them in WEIRDS JSON output structures?

I'd like to hear some reasons because so far I just think XML when I
see urn:somename and stumbling on it in JSON is very odd to me....

I also think that eventually it'll be strange when some keys have ":",
and some do not.

And when it'll be time, to find commonalities in how people use weirds
and make v2, with more "recommended keys" it would require to switch
already used names with ":" to names without it. I'd rather to see all
names "plain" from the start.

-- 
Alex Sergeyev.

---

From: Leif Johansson <[email-masked]>
Date: Sun, 17 Jun 2012 09:11:14 +0200

> But what value do you see using them in WEIRDS JSON output structures?

Conflict avoidance, but it was really just an example: an IANA registry of "short" identifiers would work just as well.

> see urn:somename and stumbling on it in JSON is very odd to me....

I don't understand that.

> I also think that eventually it'll be strange when some keys have ":",

I don't get that either.

---

From: "John Levine" <[email-masked]>
Date: 17 Jun 2012 15:27:08 -0000

>Conflict avoidance, but it was really just an example: an IANA registry of
>"short" identifiers would work just as well.

Even that seems like overkill.  The plan, as I understand it, is to
produce an RFC, or maybe two RFCs, that describe the response formats,
including the fields names.  No conflict there.  If someone wants to
do a revised version, there'll be a new RFC.

I suppose that if we anticipate large numbers of small extensions, it
might make sense to have an IANA registry for the field names, but
speaking as someone who's planning to write and use WEIRDS clients,
please don't do that.

R's,
John

---

From: Leif Johansson <[email-masked]>
Date: Sun, 17 Jun 2012 20:52:38 +0200

On 06/17/2012 05:27 PM, John Levine wrote:
>> Conflict avoidance, but it was really just an example: an IANA
>> registry of "short" identifiers would work just as well.
> 
> Even that seems like overkill.  The plan, as I understand it, is
> to produce an RFC, or maybe two RFCs, that describe the response
> formats, including the fields names.  No conflict there.  If
> someone wants to do a revised version, there'll be a new RFC.
> 
> I suppose that if we anticipate large numbers of small extensions,
> it might make sense to have an IANA registry for the field names,
> but speaking as someone who's planning to write and use WEIRDS
> clients, please don't do that.

If you don't care about extensibility (and maybe you don't) then
that will work just fine.

---

From: "Linlin Zhou" <[email-masked]>
Date: Mon, 18 Jun 2012 13:50:52 +0800

> -----Original Message-----
> From: [email-masked] [mailto:[email-masked]] On Behalf
Of
> Leif Johansson
> Sent: Sunday, June 17, 2012 3:11 PM
> To: Alex Sergeyev
> Cc: [email-masked]
> Subject: Re: [weirds] JSON naming
> 
> 
> 
> 
> 
> >> Being a coder myself (at least sometimes) I know that ':' in strings
> >> isn't an issue.
> >

urn:somename is the namespace used in XML to avoid keys collisions. I think
namespaces is templates that say what data is permitted and what value to
give data that is not defined. JSON is a simple and light weighted protocol,
so if a namespace is added, shall we have to first check whether all the
objects included in the namespace? If so, I think it's a little complicated.

> > I also think that eventually it'll be strange when some keys have ":",

colon in JSON keys depending on coding style

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

---

From: Dave Piscitello <[email-masked]>
Date: Sun, 17 Jun 2012 23:00:29 -0700

I don't see how john's vision excludes extensibility 

Sent from my iPhone

On Jun 17, 2012, at 8:53 PM, "Leif Johansson" <[email-masked]> wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.11 (GNU/Linux)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
> 
> iEYEARECAAYFAk/eJ3UACgkQ8Jx8FtbMZneFvgCbBP1BrHqmg3zuTzSpSfcAWy6A
> 56UAn0yyklmkj+GafcBLucLZ3E1YI0DX
> =3vhQ
> -----END PGP SIGNATURE-----

---

From: Leif Johansson <[email-masked]>
Date: Mon, 18 Jun 2012 08:09:25 +0200

> urn:somename is the namespace used in XML to avoid keys
> collisions. I think namespaces is templates that say what data is
> permitted and what value to give data that is not defined. JSON is
> a simple and light weighted protocol, so if a namespace is added,
> shall we have to first check whether all the objects included in
> the namespace? If so, I think it's a little complicated.
> 

I still don't get what anyone is saying on this topic.

Structured names (like URIs) have *nothing* do do with XML per se. They
are neither more or less "complicated" than unstructured names and they
do not affect code in any reasonable way.

I was making a point about extensibility.

Joe Levine seems to say that extensibility isn't necessarily in scope
for weirds. If so then the issues we discuss in this thread are of no
consequence to weirds and we can just stop this thread :-)

If extensibility is needed and unless weirds wants to mandate that all
extensions must be based on published specs then some form of uniqueness
for JSON key names is needed.

There are two ways to obtain uniqueness of identifiers: structured names
or a registry. Take your pick.

However this may all be a moot point if extensibility isn't needed so
perhaps the WG should have consensus on that point first.

> 
>>> 
>>> I also think that eventually it'll be strange when some keys 
>>> have ":", and some do not.
>> 
>> I don't get that either.
>> 
> 

No it doesn't. These are not variables. JSON is not code but a data
representation language.

Saying "colons are bad" is only true for variable names in certain
languages but no programming language that I've ever encountered has
problems with colons in strings.
	
	Cheers Leif

---

From: "Murray S. Kucherawy" <[email-masked]>
Date: Mon, 18 Jun 2012 01:33:09 -0700

On Sun, Jun 17, 2012 at 11:00 PM, Dave Piscitello <[email-masked]
> wrote:

> I don't see how john's vision excludes extensibility
Indeed, the "E" in "WEIRDS" stands for "extensible".

-MSK

---

From: Alessandro Vesely <[email-masked]>
Date: Mon, 18 Jun 2012 10:42:53 +0200

> for JSON key names is needed.

Uniqueness would be implied by the data source if there are no
provisions for "resolving" whois servers.  Clients who don't care
about data origin shouldn't be interested in origin-specific
extensions anyway.  A meaningful prefix is a favor that designers do
to interested clients, syntactic sugar that reminds the scope of a name.

> perhaps the WG should have consensus on that point first.

While we don't want to specify attributes like beforeOneSmallStep now,
as time goes by more and more registries may find it useful to use it.
 Instead of having lunarNic_beforeOneSmallStep,
marsNic_beforeOneSmallStep, denebianNIC_beforeOneSmallStep, etcetera,
it will be handier to specify that attribute once and for all.  If
that's going to happen frequently, IMHO a registry is better than long
chains of "updated by" RFCs.

jm2c

---

From: Ray Bellis <[email-masked]>
Date: Mon, 18 Jun 2012 09:45:29 +0000

> Being a coder myself (at least sometimes) I know that ':' in

Indeed not, although it should be noted that within JS at least, a key with a ":" in it must be accessed as:

    obj["some:key"]

rather than:

    obj.somekey

This also means that JS debuggers will refuse to autocomplete any such property - keys that aren't legal tokens don't appear in the autocompletion list.

In other words, ":" works, but isn't IMHO "programmer friendly".

kind regards,

Ray

---

From: Leif Johansson <[email-masked]>
Date: Mon, 18 Jun 2012 11:47:55 +0200

On 06/18/2012 11:45 AM, Ray Bellis wrote:
> Indeed not, although it should be noted that within JS at least, a
> key with a ":" in it must be accessed as:
> 
> obj["some:key"]
> 
> rather than:
> 
> obj.somekey
> 
> This also means that JS debuggers will refuse to autocomplete any
> such property - keys that aren't legal tokens don't appear in the
> autocompletion list.
> 

OK so pick some transposition then. It really doesn't matter.

My point was (and is) that if all you restrict yourself to "flat" names
then you either do extensions as specs or run a registry or you'll have
implementations allocate the same "private" name for different purposes.

	Cheers Leif

---

From: Leif Johansson <[email-masked]>
Date: Mon, 18 Jun 2012 11:42:45 +0200

On 06/18/2012 10:33 AM, Murray S. Kucherawy wrote:
> On Sun, Jun 17, 2012 at 11:00 PM, Dave Piscitello 
> <[email-masked] <mailto:[email-masked]>>
> wrote:
> 

So in that case some thought needs to be spent on how to
manage JSON names.

---

From: Alex Sergeyev <[email-masked]>
Date: Mon, 18 Jun 2012 06:50:20 -0400

Leif,

> So in that case some thought needs to be spent on how to

Your assumption is "common sense is not enough" which could be true
but not for prevailing number of registries.

I was working on toy-implementation of WEIRDS for Dyn and found
following kinds of extension that we needed:

1. New types of objects. For example, dynamic DNS hosts, registered by
our clients in our zones

    it's easy, just maintain another /objectclass/id and send info
from there. Most of the fields
    are "new to weirds" but still resemble domains.

    Do you think this kind of extension requires some sort of non-flat
naming then? It will look ugly and
    has no practicality in terms of "making someone's life easier."

2. Adding new info to domain name information.

    One thing I did to add pointer to "Dyn User" account is to
"extend" contacts and put it there (detailed information
    will be not accessible for public-facing weirds)

    Again, because of kind of information, it was logical to add this
to domain "contacts" as "dynuser" (and this is
    preliminary name for sure).

Both decisions were made assuming that "things that clients will not
use are going to be ignored".

If someone comes to us for info on domain after referral from Verisign
registry, they won't care about "dynuser" anyway. In case if they have
client for OUR service, they will read all fields.

What would you do differently? What other extensions you see that
would be hard or wrong to do with flat naming?
Look at this other way....
Say you have WEIRDS client and you see our fields (assume we'll add 10
more) as "unrecognized". Would that bother you? Is ":" solving a
problem at al? How?

-- 
Alex.

---

From: Leif Johansson <[email-masked]>
Date: Mon, 18 Jun 2012 14:46:25 +0200

On 06/18/2012 12:50 PM, Alex Sergeyev wrote:
>> So in that case some thought needs to be spent on how to manage
>> JSON names.
> 
> Your assumption is "common sense is not enough" which could be
> true but not for prevailing number of registries.

You need common sense in combination with coordination which
sorta spells like a registry to me :-)

> 1. New types of objects. For example, dynamic DNS hosts, registered
> by our clients in our zones
> 
> it's easy, just maintain another /objectclass/id and send info from
> there. Most of the fields are "new to weirds" but still resemble
> domains.
> 
> naming then? It will look ugly and has no practicality in terms of
> "making someone's life easier."
> 
> 
> One thing I did to add pointer to "Dyn User" account is to "extend"
> contacts and put it there (detailed information will be not
> accessible for public-facing weirds)
> 
> to domain "contacts" as "dynuser" (and this is preliminary name for
> sure).
> 
> 
> Both decisions were made assuming that "things that clients will
> not use are going to be ignored".
> 
> If someone comes to us for info on domain after referral from
> Verisign registry, they won't care about "dynuser" anyway. In case
> if they have client for OUR service, they will read all fields.

Thats fine unless Verising decide to use 'dynuser' for something
completely different.

	MVH leifj

---

From: "John Levine" <[email-masked]>
Date: 18 Jun 2012 13:20:34 -0000

>consequence to weirds and we can just stop this thread :-)

Well, other than that's not what I said and my name isn't Joe, OK.

The question of how one extends a standard is not exactly
unprecedented in the IETF.  If anyone can add any extensions they
want, even if there's a registry to avoid name collisions, you end up
with a mess that doesn't interoperate.  You'll have a dozen different
names for more or less the same thing, with slightly different syntax
and meaning.

The current plan is to come up with one or two RFCs that describe the
query and response formats, including all the fields.  Anyone who wants
to interoperate (which, I hope everyone remembers, is the point of a
standard) will implement those.

The usual approach in situations like this is to have a registry, but only
permit updates via new RFCs.

In the IETF, to add extensions, you write an Internet Draft, not
necessarily in a working group, run it through a review process, and
have it published as an RFC which updates the registry.  We do this all
the time.  It allows reasonable extensions, while keeping the chaos
under control.

If you think you have a private extension that nobody else will ever
use, ever, go ahead and invent a private name for it, but I can assure
you from long experience that those "private" extensions often end up
as undocumented de-facto exensions that don't interoperate very well.

We know how to do it right, so please don't ask us to do it wrong.

R's,
John

---

From: Peter Koch <[email-masked]>
Date: Mon, 18 Jun 2012 16:43:40 +0200

> permit updates via new RFCs.

not sure whether you mentioned this as an example or as a proposal
to go for "RFC required" ...
 
> have it published as an RFC which updates the registry.  We do this all

... or "IETF Review" as per RFC 5226.

> the time.  It allows reasonable extensions, while keeping the chaos

My reading of the emerging or current spirit in the apps area (probably
influenced by communities which have, say, different, approaches to
what standards are for) is that this intention might see significant
pushback.  There is increasing reluctance to use the standardization
process as either a quality gate or an architectural oversight tool.
Sadly so, one might say.

-Peter

---

From: Leif Johansson <[email-masked]>
Date: Mon, 18 Jun 2012 17:18:44 +0200

> Well, other than that's not what I said and my name isn't Joe, OK.

Darnit. sorry, I had a feeling there was something wrong there... :-(

---

From: Leif Johansson <[email-masked]>
Date: Mon, 18 Jun 2012 17:25:36 +0200

> The usual approach in situations like this is to have a registry,
> but only permit updates via new RFCs.

I think that is one very reasonable approach. My original email served
to illustrate another approach and then we got bogged down in ':'ology.

Sorry about that...

> necessarily in a working group, run it through a review process,
> and have it published as an RFC which updates the registry.  We do
> this all the time.  It allows reasonable extensions, while keeping
> the chaos under control.

There are several other processes to choose from when setting up an
IANA registry as I think you know. Depending (in the case of weirds)
how names are allocated, not all extensions need be subject to IESG
review or even publication as RFC.

> 
> If you think you have a private extension that nobody else will
> ever use, ever, go ahead and invent a private name for it, but I
> can assure you from long experience that those "private" extensions
> often end up as undocumented de-facto exensions that don't
> interoperate very well.
> 

Which is why I was arguing for some coordination or structure around
so called private extensions.

> We know how to do it right, so please don't ask us to do it wrong.

Thank you for putting it succinctly.

	Cheers Leif

---

From: Leif Johansson <[email-masked]>
Date: Mon, 18 Jun 2012 17:26:33 +0200

On 06/18/2012 04:43 PM, Peter Koch wrote:
>> and have it published as an RFC which updates the registry.  We
>> do this all
> 
>> the time.  It allows reasonable extensions, while keeping the
>> chaos under control.
> 
> My reading of the emerging or current spirit in the apps area
> (probably influenced by communities which have, say, different,
> approaches to what standards are for) is that this intention might
> see significant pushback.  There is increasing reluctance to use
> the standardization process as either a quality gate or an
> architectural oversight tool. Sadly so, one might say.

Exactly my point. Thx.

---

From: "Linlin Zhou" <[email-masked]>
Date: Tue, 26 Jun 2012 09:48:10 +0800

> From: Leif Johansson [mailto:[email-masked]]
> Sent: Monday, June 18, 2012 2:09 PM
> To: Linlin Zhou
> Cc: 'Alex Sergeyev'; [email-masked]
> Subject: extensibility in weirds
> 
> > urn:somename is the namespace used in XML to avoid keys collisions. I
> > think namespaces is templates that say what data is permitted and what
> > value to give data that is not defined. JSON is a simple and light
> > weighted protocol, so if a namespace is added, shall we have to first
> > check whether all the objects included in the namespace? If so, I
> > think it's a little complicated.
> >
> 
are
> neither more or less "complicated" than unstructured names and they do not
> affect code in any reasonable way.
> 

Agreed. So in draft draft-kong-dnrd-ap-response-json-00, we prefer this way
to show extension:

	{
     "domain": {
     ...
     },
     "nameserver": [
     ...
     ],
     "contact": [
     ...
     ],
     "registrar": {
     ...
     },
     "extension": {
     ...
     }
   }

> Joe Levine seems to say that extensibility isn't necessarily in scope for
weirds.
> If so then the issues we discuss in this thread are of no consequence to
weirds
> and we can just stop this thread :-)
> 
for
> JSON key names is needed.
> 
or a
> registry. Take your pick.
> 
perhaps
> the WG should have consensus on that point first.
> 
> >
> >>>
> >>> I also think that eventually it'll be strange when some keys have
> >>> ":", and some do not.
> >>
> >> I don't get that either.
> >>
> >
languages but
> no programming language that I've ever encountered has problems with
colons
> in strings.
I know that JSON can handle colon. I just feel a little uncommon to define a
key like the namespace in XML. :)

> 	Cheers Leif
Linlin Zhou