Altering a model

[Neil Young]

Hi,

I'm having a response model, which is literally the same as the request model, except that two properties are added: An ID and a creation date.

Is it possible to define something like this in swagger 2.0?

{

    "definitions": {

        "Request": {

            "properties": {

                "name": {

                    "type": "string"

                }

            }

        },

        "Response": {

            "properties": {

                "id": {

                    "type": "number"

                },

                "$ref": "Request"

            }

        }

    }

}

I know that the "$ref" construct doesn't work, but I hope you see the point.

[Ron]

Yup, it's possible. The way to describe it would be:

{
  "definitions": {
    "Request": {
      "properties": {
        "name": {
          "type": "string"
        }
      }
    },
    "Response": {

      "allOf": [
        {
          "$ref": "#/definitions/Request"
        },
        {
          "properties": {
            "id": {
              "type": "string"
            }
          }
        }
      ]
    }
  }
}

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Neil Young]

Hi Ron,

thanks for the quick answer. To be honest: In gray past I already used the allOf... Shame on me.

However, although syntactically correct as schema, it is neither recognized by swagger.io editor preview nor swagger.ui... Too bad...

[Ron]

Yes, some patience is required with both tools as they are still under development with regards to Swagger 2.0 support.

Many of the basic features are already supported, but the more complex aspects of schema/models are yet to be implemented.

[Neil Young]

Too bad. I don't think this is really a complex issue. I hesitate a bit to double my model definitions just for this...

Do you know a good site to place this as feature request?

[Ron]

As you already know, each project has its own github repository.
And it's not a matter of complexity, it's a matter of priorities. We have a limited number of people working on each project, just like any project out there, you can't deliver 100% of the content in zero time.

So in terms of priorities, yes, it seems to be more important to be able to describe operations in general than support some of the finer details in schemas/models like validations and inheritance. It doesn't mean it won't get implemented, it's just not first on the list of priorities.

On 13 November 2014 21:51, Neil Young <forevern...@googlemail.com> wrote:

Too bad. I don't think this is really a complex issue. I hesitate a bit to double my model definitions just for this...

Do you know a good site to place this as feature request?

[Neil Young]

Yes thanks. Have left a note in the project.

Thanks.

[Ted Epstein]

Ron, Neil,

It sounds like the readOnly property might be what you're looking for.  From the Swagger 2.0 spec:

Relevant only for Schema "properties" definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but MUST NOT be sent as part of the request. Properties marked as readOnly being true SHOULD NOT be in the required list of the defined schema. Default value is false.

Hope this helps.

Ted Epstein |   |      skype:ted.epstein

[Ron]

That's right, Ted, thanks for bringing it up.

As a side note, I doubt any of the tooling supports this yet as well.

--

[Neil Young]

Thanks all for the follow ups. As Ron anticipated, it is as well not recognized in swagger-ui

Regards

[W. Trevor King]

On Thu, Nov 13, 2014 at 09:32:46PM +0200, Ron wrote:
> Yup, it's possible. The way to describe it would be:
>
> {
> "definitions": {
> "Request": {
> "properties": {
> "name": {
> "type": "string"
> }
> }
> },
> "Response": {
> "allOf": [
> {
> "$ref": "#/definitions/Request"
> },
> {
> "properties": {
> "id": {
> "type": "string"
> }
> }
> }
> ]
> }
> }
> }

I'm looking into this today, and I'm not sure how this scales with
required properties. The Swagger 2 examples have [1]:

…
"pet": {
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "integer",
"format": "int64"
},
"name": {
"type": "string"
},
"tag": {
"type": "string"
}
}
},
"newPet": {
"allOf": [
{
"$ref": "pet"
},
{
"required": [
"name"
],
"properties": {
"id": {
"type": "integer",
"format": "int64"
}
}
}
]
},
…

Is that even valid? The second schema in the allOf requires ‘name’
but only defines ‘id’? I suppose it doesn't set additionalProperties
to false, so it's saying, “you have to have a ‘name’ field which can
be whatever you want, and if you have an ‘id’ field it should be an
int64”. Why specify ‘id’ there at all?

In any case, since allOf validates each schema in isolation [2], the
initial ‘pet’ schema (the first entry in the allOf) is *still
requiring an ‘id’ parameter*. Isn't it? I think what we need is
something like this:

…
"identifiableObject": {
"properties": {
"id": {
"type": "integer",
"format": "int64"
}
},
"required": [
"id"
]
},
"newPet": {

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

"tag": {
"type": "string"
}
},
"required": [
"name"
]
},
"pet": {
"allOf": [
{
"$ref": "newPet"
},
{
"$ref": "identifiableObject"
}
]
},
…

That should (I think ;) add the required ‘id’ parameter to ‘pet’ that
doesn't apply to ‘newPet’. However, ‘id’ would still be a valid
parameter because we weren't disabling additionalProperties.
Unfortunately, disabling additionalProperties does not work well with
composable schemas [3,4]. You can get around that by making ‘_pet’
the base schema, with a ‘pet’ schema that also requires an ‘id’ and a
‘newPet’ schema that also limits additional properties (but doesn't
specify the property values):

…
"identifiableObject": {
"properties": {
"id": {
"type": "integer",
"format": "int64"
}
},
"required": [
"id"
]
},
"_pet": {

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

"tag": {
"type": "string"
}
},
"required": [
"name"
]
},
"pet": {
"allOf": [
{
"$ref": "_pet"
},
{
"$ref": "identifiableObject"
}
]
},
"newPet": {
"allOf": [
{
"$ref": "_pet"
},
{
"properties": {
"name": {},
"tag": {}
},
"additionalProperties": false
}
]
},
…

Where I've used the ‘{}’ free-form schema supported by blaze_compiler
(which also supports ‘{type: "any"}’ for free-form schemas [5] as does
Jsonary [6]). I couldn't find an explicit syntax for free-form
schemas in the JSON Schema spec [7,8]. The ‘any’ type is not
supported by the JSON Schema validation schema [9]. If the
empty-schema syntax isn't valid, you can create a free-form schema
locally with an ugly hack with ‘not’ [10]:

"unspecified": {
"anyOf": [
{
"type": null,
},
{
"not": {
"type": null,
}
}
]
}

to use in the ‘newPet’ definition. That's a lot of work to get a
‘pet’ type that explicitly requires an ‘id’ field and a ‘newPet’
version of that type that explicitly forbids an ‘id’ field. Am I
missing something obvious?

Thanks,
Trevor

[1]: https://github.com/swagger-api/swagger-spec/blob/264e87e4666ee1cdb1441b17c2d1744c451dc8f7/examples/v2.0/json/petstore-expanded.json#L175
[2]: http://spacetelescope.github.io/understanding-json-schema/reference/combining.html#allof
[3]: https://github.com/json-schema/json-schema/issues/116
[4]: https://groups.google.com/d/topic/json-schema/plynujOa75o/discussion
[5]: https://www.npmjs.com/package/blaze_compiler
[6]: http://jsonary.com/documentation/json-schema/?section=keywords/General%20keywords#keywords/General%20keywords/02%20-%20type
[7]: http://json-schema.org/latest/json-schema-core.html#anchor8
[8]: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#data-types
[9]: http://json-schema.org/schema
[10]: http://spacetelescope.github.io/understanding-json-schema/reference/combining.html#not

--
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[Ron]

Hi Trevor,

Sorry for the delayed response.

I'll start off by saying the composition sample in the swagger-spec repository is completely messed up, as you noted yourself. It's on my todo list to rewrite it into something that makes more sense.

While writing the json-schema for Swagger 2.0, I had great "pleasure" working with 'allOf'.

As you said, validation indeed works on each schema in isolation and there's no actual merge (yeah, there's a $merge proposal for draft 5).

And that leads to pure hell when using additionalProperties.

I think the real question is how we interpret additionalProperties in Swagger. By default, its value is true, but for Swagger, to me it makes sense that by default its value is false.

That works great until we get to the point of model composition, because as you stated, allOf and addiitonalProperties: false don't play kindly together.
I would theoretically suggest that we assume additionalProperties: false as a whole to the top-level unified model (even though it doesn't really exist because of the schema isolation), but that is even more non-standard than just assuming the default value of additionalProperties is false.
Another option, in some validators, is to not allow additional properties by default in general. That would apply well to the composition as well (I think), but it's a configuration rather than an actual restriction.

By the way, free-form schemas are indeed just { }.

Unfortunately, it feels JSON Schema is very javascript oriented, even though JSON is pretty much a general-purpose standard now.

[W. Trevor King]

On Thu, Jan 08, 2015 at 05:56:15PM +0200, Ron wrote:
> I would theoretically suggest that we assume additionalProperties:
> false as a whole to the top-level unified model (even though it
> doesn't really exist because of the schema isolation), but that is
> even more non-standard than just assuming the default value of
> additionalProperties is false. Another option, in some validators,
> is to not allow additional properties by default in general. That
> would apply well to the composition as well (I think), but it's a
> configuration rather than an actual restriction.

Are those two separate options? They both sound like “ban unknown
properties mode” [1,2]. I agree with Francis that bundling this
configuration into the validator (or swagger) isn't a good idea [3],
but I don't know of any other static-schema solution except
duplicating the shared model in both pet and newPet. Something that
could work would be to work “ban unknown properties mode” into the
JSON Schema spec:

{
"type": "array",
"items": {
"type": "object",
"banUnknownProperties": true,
"oneOf": [
{
"properties": {
"propA": {"type": "string"}
}
},
{
"properties": {
"propB": {"type": "number"}
}
}
]
}
}

Then it could be defined in the spec at per-schema-union granularity.
I'll post to json-schema/json-schema#116 with this suggestion.

Cheers,
Trevor

[1]: https://github.com/json-schema/json-schema/issues/116#issuecomment-34861191
[2]: https://github.com/json-schema/json-schema/wiki/ban-unknown-properties-mode-%28v5-proposal%29
[3]: https://github.com/json-schema/json-schema/issues/116#issuecomment-34902804

[W. Trevor King]

On Thu, Jan 08, 2015 at 09:22:44AM -0800, W. Trevor King wrote:
> Something that could work would be to work “ban unknown properties
> mode” into the JSON Schema spec:

> …

> I'll post to json-schema/json-schema#116 with this suggestion.

Never mind, I like ‘propertiesFrom’ better [1] ;).

Cheers,
Trevor

[1]: https://github.com/json-schema/json-schema/issues/116#issuecomment-35074013

[Ron]

Future versions of JSON Schema are irrelevant at the moment, since we conform to draft 4, structure wise.

Interpretation wise, we can theoretically do whatever we want.

[W. Trevor King]

On Thu, Jan 08, 2015 at 07:32:36PM +0200, Ron wrote:
> Future versions of JSON Schema are irrelevant at the moment, since
> we conform to draft 4, structure wise. Interpretation wise, we can
> theoretically do whatever we want.

Right, but if we deviate from the spec it makes it hard for folks
using a Swagger-defined API to use an out-of-the-box validator.
Presumably Swagger will move along with JSON Schema as it continues to
evolve (modulo a few JSON Schema → Schema Object substitutions [1])?
That seems easier than developing a parallel ecosystem with
Swagger-only tools.

Cheers,
Trevor

[1]: https://github.com/swagger-api/swagger-spec/blob/master/versions/2.0.md#schemaObject

[Ron]

Well, we do have our own extensions to the schema, but generally I agree. I'd rather keep it the same as the proper json schema.

I guess I'm more annoyed by the current interpretation of it, but that's my problem ;)

As for moving along with JSON Schema, I imagine we will, but that would only be in a newly published version of Swagger.

I think the idea is to keep things as best as possible and deal with the limitations with the available workarounds.
If composition/inheritance doesn't work, one could always define a model as a whole. It does mean that the relationship is lost, and more complex data structures would be impossible to define, but we can't really solve the problems with JSON Schema here.

[W. Trevor King]

On Thu, Jan 08, 2015 at 08:39:23PM +0200, Ron wrote:
> If composition/inheritance doesn't work, one could always define a

> model as a whole. It *does* mean that the relationship is lost, and

> more complex data structures would be impossible to define, but we
> can't really solve the problems with JSON Schema here.

Yeah, that sounds like the best approach with JSON Schema v4. I'll
survive with a bit of duplication ;). Maybe I can use $ref for
properties entries, which would at least let me avoid duplicating
them.

Cheers,
Trevor