openstack team mailing list archive

[Jay Pipes <jaypipes@xxxxxxxxx>]

On 04/09/2012 02:16 PM, Justin Santa Barbara wrote:
>     Justin, what does "design a model which works with XML" mean?
>
> Simply avoiding the handful of things that are specific to JSON (or
> specific to XML).  Nothing too onerous (no angle brackets)!

I see, gotcha.

>         I think this is only done in the image properties.
>
>     No, the image properties have been removed in the 2.0 Images API and
>     replaced with the standard concept of "tags":
>
>     https://docs.google.com/__document/d/1rb7ZVn0Du___5NZqUyQpqUZSmv7Qd66TMHYAtvsow7__LH4/edit#heading=h.__y10rq9pdt27y
>     <https://docs.google.com/document/d/1rb7ZVn0Du_5NZqUyQpqUZSmv7Qd66TMHYAtvsow7LH4/edit#heading=h.y10rq9pdt27y>
>
> I was looking at properties in "GET /schemas/image/access" and "GET
> /schemas/access".  In general, the Glance 2.0 model is very close to
> being XML-compatible.

OK.

>         On the downside: The JSON isn't as JSON-ic as it could be.
>
>     In what ways?
>
> When you're designing JSON considering only JSON, you'd probably use {
> key1: value1 } - as you have done.  If you're designing generically,
> you'd probably use { key: key1, value: value1 }.

You mean we'd have to do dumb crap because XML doesn't have the native 
concept of a list? ;)

>         On the upside: You need never worry about XML again
>
>     We haven't worried about it at all up until now. And Glance has been
>     perfectly fine without it. ;)
>
> Well yes, I agree that our XML support generally is sufficiently buggy
> as to be unusable, hence unused.  I don't actually care about XML, I
> just care about having a well-specified API that works.

I wasn't actually talking about Nova. :) Glance doesn't have ANY support 
for XML at all. It's been using JSON and only JSON from its inception... 
 And for the record, we will absolutely NOT be generating JSON from XML 
schemas. That is pure lunacy.

> In my opinion, the way to do that is to specify a model, and we have
> JSON and XML representations of that model.  If we design the model
> right, JSON & XML both "just work" without any code (and less code =
> less bugs).

I shall refer you to Keystone Legacy to see how well that strategy works 
in practice.

> Moreover, when someone introduces another data interchange
> format, we again just write one piece of middleware, one documentation
> generator, and we're done.  Doing this by hand for each format is simply
> busywork.

You'd *think* this would work. In practice, however, it really doesn't. 
Neither does (good, valid) code generation...

> I don't care whether we specify the model as a Python class, Java class,
> XML schema, JSON schema, or using stick figures with long arms pointing
> at boxes.  You can even specify it in JSON if you stick to a "lowest
> common denominator" subset.

In the 2.0 API we *are* specifying it in JSON. JSON Schema, specifically...

> I think the only thing you need to avoid is
> "no changing-at-runtime keys"; I think this makes it compatible
> with XML, Avro, ProtocolBuffers & Thrift.

That is antithetical to having dynamic, but discoverable, schemas. JSON 
Schema (and XSD, fwiw) provide things like additionalProperties and 
<xsd:any> for just this sort of thing. Making a schema entirely static 
is really only useful for generating (bad and soon-to-be-outdated) 
client code.

Having dynamic and discoverable schemas enables clients to respond to 
backwards-compatible schema changes (like the addition of standard 
properties or the addition of "extra-standard" additionalProperties) 
without having to recompile a client or change any client code at all...

> I don't think it should be a big deal for the JSON format to avoid
> dynamic keys, given how much you win whenever you have to support a new
> format.

By dynamic keys, are you referring to the additionalProperties? If so, I 
disagree.

> Incidentally, I just heard about yet another new format - apparently
> this one is going to be the standard for use with node.js
> - Hypertext-Powered-State-Transfer-Representation.

HPSTR? H(i)PST(e)R? Are you sure that wasn't an April Fool's Joke? :)

Best,
-jay