revisit `schemas` for location of model defintions

[fehguy]

As pointed out in the workgroup, the term schemas is a bit confusing.

[fehguy]

example: https://github.com/reverb/swagger-spec/blob/master/examples/wordnik/petstore.json#L50

[raymondfeng]

I would prefer models. 2nd choice is schema.

[tedepstein]

My thoughts: models is a very generic term that could mean a model of anything, not necessarily a data model. schema is not bad, but #83 suggests that there can be external schema references as well. I haven't seen the examples, so I don't know if those go in the schemas section or somewhere else. But regardless, having one section called schema, where other schemas may also be referenced, seems a little off to me.

What about dataTypes (my first choice) or typeDefinitions?

[earth2marsh]

Models isn't terrible (agree with @tedepstein's point about how generic it is), but given that they're defined using JSON-schema, it seems like schema is technically accurate. I could live with either one, but prefer schema.

Personally, I don't have an issue with schemas, since we have established a patterns like paths, tags, properties, responses, etc that contain various definitions—essentially the same logic that has models in the running. Are schemas not a collection of individual schema definitions?

@tedepstein, generally speaking we've tried to keep the names of keys to single words whenever possible.

[tedepstein]

Well, in that case I nominate datatype to become an honorary single word. ;-) Kidding aside, I can certainly live with any of the proposed terms. I tend to favor clarity over brevity, but if single words are the style, it makes sense to stick with that.

[tedepstein]

types could be another option.

[earth2marsh]

or payloads

Given that we think json (with json-schema) and then xml (assuming xsd?), both of those are formal schema definitions. And since we are talking about a collection of formal schemas, I'm still biased toward schemas. Though if others are confused, that is most certainly a valid knock against.

[raymondfeng]

I'm fine with types (WSDL style:-)

[fehguy]

this is the problem with words (coming from a word company). Sometimes there is no single, correct one to use.

schema is not quite right, since we refer to schema throughout the spec in completely different context types is very generic schemas is what started this whole party

The point of that section is that they're definitions for models. Maybe we should just call it out as "definitions"? That's more json-schema-ish than anything.

{
  "definitions" {
    "Pet": {
      ...
    },
    "Error": {
      ...
    }
  }
}

[tedepstein]

'Definitions' is generic too, but the usage is very consistent with JSON schema. So it seems quite intuitive to me in this context. +1 for definitions.

[earth2marsh]

Well said! You jogged me out of my rut, Tony…

What about objects? The problem here is that these are more than name/value pairs, they're complex objects. Or would you object? (sorry)

I could also live with definitions, though its genericity is bothersome.

On Thu, Jul 31, 2014 at 4:45 PM, Tony Tam notifications@github.com wrote:

this is the problem with words (coming from a word company). Sometimes there is no single, correct one to use.

schema is not quite right, since we refer to schema throughout the spec in completely different context types is very generic schemas is what started this whole party

The point of that section is that they're definitions for models. Maybe we should just call it out as "definitions"? That's more json-schema-ish than anything.

{ "definitions" { "Pet": { ... }, "Error": { ... } }}

— Reply to this email directly or view it on GitHub https://github.com/reverb/swagger-spec/issues/81#issuecomment-50833295.

[paulhill]

models

If only because schemas isn't a word. (Schema is it's own plural)

On Thursday, July 31, 2014, Marsh Gardiner notifications@github.com wrote:

Well said! You jogged me out of my rut, Tony…

What about objects? The problem here is that these are more than name/value pairs, they're complex objects. Or would you object? (sorry)

I could also live with definitions, though its genericity is bothersome.

On Thu, Jul 31, 2014 at 4:45 PM, Tony Tam <notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');> wrote:

this is the problem with words (coming from a word company). Sometimes there is no single, correct one to use.

schema is not quite right, since we refer to schema throughout the spec in completely different context types is very generic schemas is what started this whole party

The point of that section is that they're definitions for models. Maybe we should just call it out as "definitions"? That's more json-schema-ish than anything.

{ "definitions" { "Pet": { ... }, "Error": { ... } }}

— Reply to this email directly or view it on GitHub https://github.com/reverb/swagger-spec/issues/81#issuecomment-50833295.

— Reply to this email directly or view it on GitHub https://github.com/reverb/swagger-spec/issues/81#issuecomment-50837584.

[earth2marsh]

Do not tempt me into pedantry, Paul! :)

Damn, it is too tempting…

Schema comes from the Greek with a plural of schemata, though schemas is considered acceptable.

$ref: http://en.m.wikipedia.org/wiki/Schema On Jul 31, 2014 6:39 PM, "Paul Hill" notifications@github.com wrote:

models

If only because schemas isn't a word. (Schema is it's own plural)

On Thursday, July 31, 2014, Marsh Gardiner notifications@github.com wrote:

Well said! You jogged me out of my rut, Tony…

What about objects? The problem here is that these are more than name/value pairs, they're complex objects. Or would you object? (sorry)

I could also live with definitions, though its genericity is bothersome.

On Thu, Jul 31, 2014 at 4:45 PM, Tony Tam <notifications@github.com javascript:_e(%7B%7D,'cvml','notifications@github.com');> wrote:

this is the problem with words (coming from a word company). Sometimes there is no single, correct one to use.

schema is not quite right, since we refer to schema throughout the spec in completely different context types is very generic schemas is what started this whole party

The point of that section is that they're definitions for models. Maybe we should just call it out as "definitions"? That's more json-schema-ish than anything.

{ "definitions" { "Pet": { ... }, "Error": { ... } }}

— Reply to this email directly or view it on GitHub < https://github.com/reverb/swagger-spec/issues/81#issuecomment-50833295>.

— Reply to this email directly or view it on GitHub https://github.com/reverb/swagger-spec/issues/81#issuecomment-50837584.

— Reply to this email directly or view it on GitHub https://github.com/reverb/swagger-spec/issues/81#issuecomment-50840460.

[fehguy]

I'm going to update it to definitions while you guys battle over etymologies of words.

[earth2marsh]

The thing about definitions is that almost any part of a Swagger specification could be called a definition. We're really dealing with formal schemas of models of (mostly) payload objects.

Do any of those seem workable?

[earth2marsh]

… or representations

[fehguy]

but in the spec, these are model definitions. So actually using /definitions is consistent with json schema convention.

[earth2marsh]

I'm not familiar enough with json schema to comment on that, so I'll defer to you and others on this one.

[fehguy]

take a look here

http://spacetelescope.github.io/understanding-json-schema/structuring.html#reuse

[earth2marsh]

Ah, I see. Thanks for the enlightenment.

[paulhill]

definitions!

(or schemata) :-)

On Thu, Jul 31, 2014 at 10:15 PM, Marsh Gardiner notifications@github.com wrote:

Ah, I see. Thanks for the enlightenment.

— Reply to this email directly or view it on GitHub https://github.com/reverb/swagger-spec/issues/81#issuecomment-50849662.