← Back to team overview

openstack team mailing list archive

Re: Image API v2 Draft 4

 

On 04/09/2012 05:14 PM, Justin Santa Barbara wrote:
        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? ;)


XML has lists, as does Avro, ProtocolBuffers & Thrift.  XML supports
extensible lists, which is why the syntax is different.

Extensible lists are pointless. Lists have no attributes other than their length. I made this point a couple design summits ago... but whatever :)

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

Of course it works!  Every JAX-RS webserver does this.  You just can't
start with JSON first and expect everything to magically be OK.

I'm not aware that I said to "start with JSON first and expect everything to magically be OK". I believe I put both JSON Schema and XSDs in the Images API 2.0 proposal?

If you think it doesn't work, can you provide an example?

I was referring specifically to the Keystone Legacy code that attempted to generate JSON from XSDs and WADLs. But for the life of me, I can't now find the code in GitHub that shows what I'm talking about... meh.

You start with an abstract model, and then check what it looks like in
JSON, in XML, in ProtocolBuffers, in Avro, in Thrift, in HPSTR, etc...

I'm not opposed to using an abstract model, I was just saying that the "easy as pie" solution you offered of "just having to create a new generator, etc" isn't in practice so easy and often leads to hard-to-debug subtle differences in output format that aren't fixable just be "editing the abstract model"...

  If you start with JSON, then of course it won't work. If we're going
to treat XML as an afterthought, then I'd rather we just didn't support
XML at all (and yes, I absolutely mean that - it is good that Glance is
honest that they don't support XML.)

Glad we took the high road ;P

Even ignoring XML, I can't help but think that not having a strict
delineation between user-provided data and the structure of your
document is a pretty risky idea.

Not quite sure I follow you here... are you referring to dynamic schemas here?

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

Are JSON schemas an April Fool's joke?  Once you introduce schemas, you
might as well just go with XML ;-)

I personally find JSON Schema to be as robust, and infinitely more readable, as XSD.

     > 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 couldn't disagree more: "what does it mean"?  There's the implicit
contract underlying the interface; the semantics that underpin the
syntax.  e.g. syntax: a glance image id is a string, semantics: the id
is unique to a glance installation and is used to refer to an image in
REST calls.

I think you're muddying WADL and XSD above?

xsd:any allows you to put elements _from another schema_ into your XML
document.  That foreign schema defines the semantics of those elements.
  It's schemas all the way down, giving semantics to your syntax.

That's exactly what JSON Schema's additionalProperties allows...

If your additional properties in Glance are properly schematized, then
that's great.  But true cross-representation schemas are an open
problem, I believe, so you're really painting yourself into a corner
(how do you support XML output, if you let people upload arbitrary JSON
schemas?)

They are absolutely properly schematized. They are nothing more than false (indicating the schema is fixed) or a list of other schemas...

        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? :)

Are you sure it wasn't mine? ;-)

:)

-jay


Follow ups

References