Type variance in Swagger models

[David Lee]

A couple of month ago I posted a question about how I might document in Swagger a field whose type might vary. Swagger didn't really have a way of defining this, so we ended up with this sort of model.

"Obj": { "id": "Obj",

    "properties": {

        "foo": { "type": "Foo" },

        "bar": { "type": "Bar" },

        "bam": { "type": "Bam" }

    }

}

Actually, you can see exactly what our model is. As we're getting more into it, users of the API are having trouble using it. Inferring the type from the field name is really awkward. We could add a type field which gives the name of the data field, which makes things only slightly awkward. It also irks me to have redundant information in the message ({ "type": "foo", "foo": {}}).

So I'd like to go down the path of adding either subclassing or discriminated unions to Swagger model definitions.

Since Swagger models will need to map to statically typed languages, I think a subclassing approach might be best. Here's what a model might look like:

{ "id": "Base",

  "properties": {

    "type": { "type": "DISCRIMINATOR" },

    ...

  }

}

{ "id": "Foo", "extends": "Base", "properties": { ... } }

{ "id": "Bar", "extends": "Base", "properties": { ... } }

{ "id": "Bam", "extends": "Base", "properties": { ... } }

{ "id": "Obj",

    "properties": {

        "data": { "type": "Base" }

    }

}

And some examples of Obj:

{ "type": "Foo", "foo-specific": "whatever" }

{ "type": "Bar", "foo-specific": "whatever" }

etc.

Thoughts on this approach?

-- 

David M. Lee
Digium, Inc. | Software Developer
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at:  www.digium.com  & www.asterisk.org

[Tony Tam]

Hey David,

I looked at supporting pure JSON schema for swagger 1.2 spec (currently implementation is 1.3.0-SNAPSHOT on sonatype) but it was really messy.  JSON schema seems to take the lowest common denominator approach, and dealing with attribute typing is an afterthought.

That said, we are currently sticking with a custom model schema.  But as you pointed out, it's not sufficient for things like type inheritence. 

I propose we take this discussion to a public gist, and start putting some examples in there.  Want to translate your examples into one?

[David Lee]

Done - https://gist.github.com/leedm777/5730877

-- 
David M. Lee
Digium, Inc. | Software Developer
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at:  www.digium.com  & www.asterisk.org

[Tony Tam]

Well github isn't accepting my comment right now, so to avoid leaving you hanging:

I think this is sound, I'll see if anyone else has feedback and if it passes muster, we'll get it in the 1.2 spec before release.

[Tony Tam]

Hi David, just commented on your gist as I was implementing this.  Let me know what you think...

https://gist.github.com/leedm777/5730877#comment-851757

Tony

[David M. Lee]

Replied - https://gist.github.com/leedm777/5730877#comment-851776

dave

<><

---

From: Tony Tam <feh...@gmail.com>
To: wordn...@googlegroups.com
Sent: Tuesday, June 25, 2013 9:27 PM
Subject: [wordnik-api] Re: Type variance in Swagger models

[Tony Tam]

Not sure if you get notifications on comments on the gist, so just in case...

https://gist.github.com/leedm777/5730877#comment-851831

[David M. Lee]

AFAIK, there are no notifications on Gist comments. Maybe if I star my own gist...

Replied - https://gist.github.com/leedm777/5730877#comment-852410

dave

<><

---

From: Tony Tam <feh...@gmail.com>
To: wordn...@googlegroups.com

Cc: David M. Lee <leed...@yahoo.com>
Sent: Wednesday, June 26, 2013 1:52 AM
Subject: Re: [wordnik-api] Re: Type variance in Swagger models

[Tony Tam]

Ring Ring 

https://gist.github.com/leedm777/5730877#comment-852434

[David M. Lee]

Knock, knock.

https://gist.github.com/leedm777/5730877#comment-852442

dave

<><

---

From: Tony Tam <feh...@gmail.com>
To: wordn...@googlegroups.com

Cc: Tony Tam <feh...@gmail.com>; David M. Lee <leed...@yahoo.com>
Sent: Wednesday, June 26, 2013 3:24 PM

Subject: Re: [wordnik-api] Re: Type variance in Swagger models

--
You received this message because you are subscribed to a topic in the Google Groups "Wordnik API" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/wordnik-api/EC3rGajE0os/unsubscribe.
To unsubscribe from this group and all its topics, send an email to wordnik-api...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[David M. Lee]

Looks great!

I've updated the gist as we discussed, and fleshed it out a bit more. I'm fairly happen with the end result.

Thanks!

dave

<><

---

From: Tony Tam <feh...@gmail.com>
To: wordn...@googlegroups.com

Cc: Tony Tam <feh...@gmail.com>; David M. Lee <leed...@yahoo.com>
Sent: Wednesday, June 26, 2013 3:24 PM

Subject: Re: [wordnik-api] Re: Type variance in Swagger models