JSON Namespace Proposal

[Sledged]

In the interest of avoiding key collisions, I think that JSON Schema
should implement namespaces (keyspaces?). The obvious problem with
this idea is that there has been a JSON namespace proposal (at least
not that I could find). so I decided to take a crack at it.

The first thing needed is a means to associate prefixes and
namespaces:

{
"name" : "http://json-schema.org/",
"prefixes" : [ "jsd" ],
"schema" : "http://jsonschema.googlecode.com/files/
schemaForSchema.json"
}

The (required) "name" key is self-explanitory. It's what designates
the namespace name. I'd recommend that the namespace name be limited
to absolute URIs. The (required) "prefixes" key is set to an array
that has at least one value. The values may be either strings or a
null (which would indicate the default namespace). The (optional)
"schema" key would specify the location of the schema document against
which the properties of this namespace can be validated against.

For multiple namespaces, I figured that multiple namespace objects
could be grouped together in an array, like so:

[
{
"name" : "http://json-schema.org/",
"prefixes" : [ "jsd" ],
"schema" : "http://jsonschema.googlecode.com/files/
schemaForSchema.json"
},
{
"name" : "http://somedomain.com/persons",
"prefixes" : [ null, "pers" ]
}
]

and in any given object, this array is set to the key "json:ns" where
the prefix "json" is reserved and implicitly associated with a
specific URI (yet to be determined), and the local key "ns" is
reserved within the "json" namespace and may be set to a single
namespace object or an array containing namespace objects. (As a side
note, other reserved keys in the "json" namespace would include "id",
"lang", and maybe "base".)

If this were applied to the first JSON Schema example in the JSON
Schema Proposal (http://json-schema.org/), we would get:

{
"json:ns" :
[
{
"name" : "http://json-schema.org/",
"prefixes" : [ "jsd" ],
"schema" : "http://jsonschema.googlecode.com/files/
schemaForSchema.json"
},
{
"name" : "http://somedomain.com/persons",
"prefixes" : [ null, "pers" ]
}
],

"jsd:description" : "A person",
"jsd:type" : "object",

"jsd:properties" : {
"name" : { "jsd:type" : "string" },

"born" : {
"jsd:type" : [ "integer" , "string" ],
"jsd:minimum" : 1900,
"jsd:maximum" : 2010,
"jsd:format" : "date-time",
"jsd:optional" : true
}

"gender" : {
"jsd:type" : "string",

"jsd:options" : [
{ "value" : "male", "label" : "Guy" },
{ "value" : "female", "label" : "Gal" }
]
},

"address" : {
"jsd:type" : "object",

"jsd:properties" : {
"street" : { "jsd:type" : "string" },
"city" : { "jsd:type" : "string" },
"state": { "jsd:type" : "string" }
}
}
}
}

Sledge

[roB...@mobileonlinebusiness.com.au]

Hey Sledge,

I think that's a great direction.

Would be good to set...

"prefixes" : [ null, "jsd" ]

...to encourage the json-schema.org schemas to be used as default and
to allow backward compatibility for use of existing schema files
already deployed in the wild.

Any specific ideas on what should happen with namespace clashes and
would it allow extensions?
e.g. if two namespaces with the same prefix but using different schema
were defined.

Also, how would you see tools specifically handling this...would there
be a strict and loose mode?



roBman

[Sledged]

On Dec 3, 7:41 pm, "roB...@MobileOnlineBusiness.com.au"

<roB...@MobileOnlineBusiness.com.au> wrote:
> Would be good to set...
>
> "prefixes" : [ null, "jsd" ]
>
> ...to encourage the json-schema.org schemas to be used as default and
> to allow backward compatibility for use of existing schema files
> already deployed in the wild.

I was thinking backwards compatibility wouldn't be a problem since the
"json:ns" key is optional. No object is required to have it, but
every object is allowed to have it.

> Any specific ideas on what should happen with namespace clashes and
> would it allow extensions?
> e.g. if two namespaces with the same prefix but using different schema
> were defined.

Well, in ECMAScript (why isn't JSON called "ECMASON?"), if an object
has the same key used twice, E.g.:

{
"key" : "value",
"key" : "value2"
}

the initial value would be overwritten. Since prefixes act as keys of
a sort, a namespace-aware parser could silently honor the last
assignment only. I'm more inclined for having the namespace-aware
parser to throw an error (or at the very least, a warning).

> Also, how would you see tools specifically handling this...would there
> be a strict and loose mode?

Possibly, maybe add a third tolerant mode, but the strict mode should
be heavily encouraged.

Sledge

[Kris Zyp]

Sledged wrote:
> In the interest of avoiding key collisions, I think that JSON Schema
> should implement namespaces (keyspaces?).

Is there a particular area where you see an issue with key collisions?
Obviously the spirit of JSON is keeping things simple, hence JSON specs
avoid namespaces (certainly many have considered it), and I wouldn't
want to utilize such complexity in JSON Schema unless absolutely
necessary. Do you further motivation for namespaces?
Kris

[roB...@mobileonlinebusiness.com.au]

I think it could be useful...but making it option and starting with
the base schemas supporting "null" would mean it's only used where
necessary.

One place I think could be relevant is with extensions. In some cases
you may want to use the parent schema type and not the extended
version. This would allow you to explicitly do that.


Sledge, (as per your comment one message above) I think accepting the
overriding and possibly throwing a warning would be good.


roBman

[Leon]

In your example you have two namespaces but you only use one of them.
Where does "pers" come in and how does it create a collision with the
standard JSD (JSON schema definition) declarations? Namespaces have to
be unique so using a registered URI is not a recommendation, that
would have to be an iron-clad rule. The prefixes are localized syntax
sugar. The "xsd" convention can appear in a hundred schemas applied to
a single XML document instance, zero collisions. The collisions come
in when you have two Person definitions in two separate schemas
included within a single document instance. In that case the
*instance* gets the namespace prefix (usually the short form that only
has to be unique in that particular document).

JSON property names cannot contain embedded colons so neither the
object instance nor the schema definition can have colon-separated
property names. Can you provide a very short and to the point example
of a collision (e.g., two Person definitions) and what legal syntax
could resolve it?

[Stephen McKamey]

Actually JSON property names are any valid JSON string, so they could
contain a single string with namespace and colon as a prefix:

{
"myJsonNamespace:myJsonPropertyName" : 42
}

This is how JsonML gets around namespace support in serialization of
XML documents.

In my person opinion, I agree with Kris: JSON is about simplicity and
if the case isn't strong enough then namespaces complicate
everything. On the other hand having *very optional* scenario whereby
namespaces are an exception rather than a rule might make for good
future-proofing.

XML 1.0 did not explicitly provide namespace support but it did allow
the colon character in element and attribute names which gave way to
later namespace support.

[Leon]

That property names can be any string gives off a strong odor but it
is probably a natural scent in dynamic script world. If you were to
evaluate such a property it would have to be coerced to conform to
valid object literal notation (which JSON claims to be a proper subset
of). That means the property names "jsdanger" and "jsd:anger" would
generate a name collision, as would a couple gillion other character
combos. Just another pothole on the road to convenience! I agree that
namespaces are probably beyond the pale as far as JSON is concerned.
They add more overhead and complexity than most folks will ever need
when exchanging JSON objects.

[Stephen McKamey]

Perhaps I wasn't clear, there isn't any coercion necessary.

In JavaScript (which JSON is a syntactical subset of), objects are
effectively hashtables with string keys. Therefore it is perfectly
valid to have an object with a property named "jsd:anger". JSON
actually further restricts JavaScript's object literals to say that
all property names must be quoted. Therefore, "jsd:anger: and
"jsdanger" would never conflict. It wouldn't make sense to map one to
the other because they are both valid values. This isn't limited to
JavaScript either, as any JSON serializer must support this syntax to
be able to properly interact.

In fact, JavaScript supports escaping of arbitrary unicode
characters. So your property name could even include oddities like
"\u00E6" which represents a lowercase "ae" ligature.

No name coercion means no additional collisions for this example.

[Rod Macpherson]

OK, I get that the string content is irrelevant in terms of the property name. However, the typical scenario is you send me { "bar" : 42 } and that can be evaluated and assigned to foo. Now we have foo.bar because the quotes were stripped off. What happens if instead you send me { "bar:baz" : 42 } and I do the same thing?  How do you access the "bar:baz" property at that point?

[Stephen McKamey]

This is getting a little off topic, but the quick answer is treat the
object like a hashtable:

To access "bar:baz" property on the object would be like this:

var myObj = { "bar:baz" : 42 };
var myProp = myObj["bar:baz"];

// now (myProp === 42) is true

In the first case,

foo.bar === foo["bar"]

is true.

[Rod Macpherson]

All clear. The foo.bar pattern is sugar applicable to suitable property names, and { foo : 42 } is sugar coated { "foo" :42 }. Neat, thanks for clarifying. .

[roB...@mobileonlinebusiness.com.au]

Here's a rough example of where I see namespaces would be useful.

Imagine there were two separate existing schemas...one for a specific
company's "products" and one for a retail service's "orders".

NOTE: These examples use Sledge's proposed format to illustrate this
point.

Schema 1:
-------------
{
"json:ns" :[
{
"name":"http://domain1.com/",
"prefixes":["d1prod"],
"schema":"http://domain1.com/products"
}
],
"id":"domain1_product",
"description":"A product from domain1",
"type":"object",
"properties":{
"id":{"type":"string"},
"name":{"type":"string"},
"amount":{"type":"number"},
...
}
}

Schema 2:
-------------
{
"json:ns":[
{
"name":"http://domain2.com/orders",
"prefixes":["d2order"],
"schema":"
}
],
"id":"domain2_order",
"description":"An order from domain2",
"type":"object",
"properties":{
"id":{"type":"string"},
"qty":{"type":"integer"},
...
}
}

Now imagine that these two schemas had been used independently for a
while and were working fine without any need for namespaces...then for
a specific project they both needed to be used.

Without namespaces completely new schema would have to be created.

With namespaces this simple instance could be created.

Instance 1:
{
"d2order:id":"ABC121212",
"d1prod:id":"12345-00",
"name":"Rubber duck",
"amount":"9.95",
"qty":"200",
...
}

I agree that the majority of the time namespaces wouldn't be necessary
and we should KISS. But in circumstances like this (and the extension
example I described earlier) this could be essential.


roBman

PS: I know that this example just highlights why people shouldn't use
generic property names like "id"...but in reality they do.

[roB...@mobileonlinebusiness.com.au]

Doh...Schema 2 should have been like this:

Schema 2:
-------------
{
"json:ns":[
{

"name":"http://domain2.com/",
"prefixes":["d2order"],
"schema":"http://domain2.com/orders"

[Rod Macpherson]

The benefits are obvious and ancient but not compelling. The question seems to be whether a JSD namespace implementation can be simple enough to satisfy the "simplicity" requirement. I would vote "nay" and refer those who need those facilities to XML technologies. Multiple schemas are easy to combine under the current proposal, and a simple lint check could warn about collisions. Take the pool of JSON users and I will bet the number of JSD (JSON Schema Definition) users will fit in an average sized tub. The number of users in that tub who experience collisions by combining third-party JSDs will fit in a thimble, and there are still remedies outside of namespaces.

[David Waite]

> With namespaces this simple instance could be created.
>
> Instance 1:
> {
>     "d2order:id":"ABC121212",
>     "d1prod:id":"12345-00",
>     "name":"Rubber duck",
>     "amount":"9.95",
>     "qty":"200",
>     ...
>
> }

But wouldn't doing this mean that it would break both all code that
deals with orders and all code that deals with products? Why not (to
keep your example schemas):

{
"order" : {
"id" : "ABC121212",
"qty" : 200
},
"product : {
"id" : "12345-00",
"name" : "Rubber Duck",
"amount" : 9.95
}
}

The example you gave is akin to multiple inheritance, which really was
the primary case I could think of for needing namespaces to
differentiate conflicting fields. If the types are not designed to be
composable, then trying to represent them all with a single object is
probably not a good idea.

-DW

[Rod Macpherson]

It would break the code and it's a really bad example of namespace usage in any event. I have never seen a namespace wrapped around one property in an XML element and it is not even possible to apply a namespace to a single field or method in terms of C# or Java classes (package name in the latter case). What you want is to apply a namespace, to an embedded Thing like an Address witin a Person.

You have to use them from the start and you have to be able to dictate the prefix of each namespace (only one should be allowed) in the document instance, up to and including the default (no prefix) namespace. Otherwise your code will break or you will have to fix-up all of your data structures manually.

Imagine you have a schema with an embedded prefix "foo" and somebody else decides to use that inside their schema? So much for avoiding collisions! Plus, you really have to distinguish between the "location" and the schema. XML provides a working model and it would be less-than-sensible not to follow it, if they ever do add such a feature.