oai / openapi-specification Goto Github PK

In the Operation Object, the type field (and other inherited type related fields), that signifes the return type of the operation, should be removed altogether in favor of the responseMessages that cover all kind of return types, whether erroneous or not.

Currently, we have some kind of a duplication that can also lead to conflicts in Swagger-UI, Codegen and other third party tools.

Since an HTTP operation always has to return an HTTP status code, this should not be an issue.

Issue by vlcinsky from Sunday Mar 02, 2014 at 23:40 GMT
Originally opened as https://github.com/wordnik/swagger-docs/issues/9

Having any sort of schema makes answering a question "is my document following these standards?" much simpler.

While accepting, all sorts of schemas have some limitations, it often allows at least quick detection of clear errors.

I would expect one schema for resource listing and another for resource definition.

https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md#523-operation-object

Type string

Declares this operation to be deprecated. Usage of the declared operation should be refrained.

A.) If the type string is correct:

• Does that mean there should be a note or explanation here? The spec doesn't explicitly state or hint at what should be provided.
• If a note or explanation should be provided, the pet store implementation has a flaw (see findPetsByTags -- ... deprecated: "true", ...).

B.) If the type string is incorrect, and the type should be boolean:

• The spec needs to be fixed.

I personally feel that B is the best route here. When an operation is deprecated, having a boolean flag makes it clearer for API clients to throw errors/notices (i.e., does an empty string still indicate deprecated).

Also, to reflect deprecated operations on Swagger UI*, it should be enough to add a "DEPRECATED" label, and/or strikeout (<del>...</del>) the operation label text.

(* currently not supported)

Issue by quasipedia from Sunday Mar 02, 2014 at 00:16 GMT
Originally opened as https://github.com/wordnik/swagger-docs/issues/2

While I understand the present specification is an attempt at documenting how swagger works today, I thought the following observations could be of some use at least for discussion / version 1.3.

number

The JSON schema specification says for this primitive:

Any JSON number. Number includes integer.

This possibly means that number should also have the int32 and int64 formats available (as they are valid), and that eventually the integer type could be killed altogether.

date & date-time

In my opinion these are not formats. A format would be ISO 8601 (which specifies both date and date-time), for example. Mixing date and date-time with int32 and int64 is however IMO mixing oranges and apples: the former define the semantics of the string, the latter their boundaries.

In general

I believe this section may be a candidate for review: since in JSON the number is encoded as its human-readable representation, there is no need to attach information about the number of bits or the signed/unsigned property.

If the thought was to provide the client with information about the boundaries of the values, this would be better achieved with explicit maximum and minimum fields (and possibly with a resolution one, telling what is the last significant digit of a result (a far more interesting/useful property to know, in math applications).

I'm looking for a way to provide metadata for a REST webservice, and swagger is currently my leading choice. The biggest missing feature (for me) is the ability to use xml schema to describe a model. i understand this is potentially a large feature. even if it may not be added anytime soon, it would be great if there was at least a rough "proposal" for a good way that the current spec could be modified to support xml schema.

hi.

Would be nice to have the date & date-time formats visible in the spec. Like in:
https://github.com/metosin/ring-swagger#supported-schema-elements

(are millis supported or not)

Sometime it is handy to have sample request or response example. Working with integration of larger project SUPERHUB, we go from API design over samples, validating them and finally implementing. Samples are key component in communication about API.

Option "tree": agreed tree structure with basePathExamples parameter

API declaration would get new attribute "basePathExamples".

Default value for basePathExamples could be <basePath>/_examples

Real examples would be available at url build from <basePathExamples>/<resourcePath>/<operationNickname>/request/<requestExampleName> and similarly <basePathExamples>/<resourcePath>/<operationNickname>/response/<responseExampleName>

Option "index": Index of sample files within agreed tree structure

Option "tree" has a disadvantage, that collecting all sample file names/urls might not be always easy or even possible. To resolve that, we would put into path <basePathExamples>/<resourcePath>/<operationNickname> a file called index.json. This would be an object with two properties requests and responses, each holding list of path names for sample request/responses. The path shall be relative to given directory with index.json file as it is easier to fill it in (e.g. using find) and also easy to check by using an editor (use gf in vim, standing for "go file" - you either succeed and see the sample file, or hit a problem, if the path is invalid). We could also completely relax from requirement to use names request or response for directories and leave it up to the developer.

Option "links": Explicit links from operation items to examples

We could reuse the concept of basePathExamples above plus allowing two new attributes within operation objects.

exampleRequests would be a list of urls, pointing to request examples.

exampleResponses would be a list of urls, pointing to response examples.

However, as such an option seems too intrusive to me, I will not detail on it.

How to start

Starting with agreed tree structure shall be rather easy, as in the simplest situation (using agreed default value for basePathExamples), there is no need to modify any of existing structures.

Allowing non-default values for basePathExamples sounds practical to me and relatively easy.

If we feel a need to extend it, I would prefer the "index" solution as it is much less intrusive comparing "links" option.

How to follow up

(this is out of scope of this ticket)

Swagger UI showing sample files

Swagger UI shall be able to show sample requests and responses.

Test suite for evaluating sample files

Having all the information proposed at hand, we shall be able writing a test suite, which would detect following problems:

• operation without sample request (if relevant) and sample response
• sample requests and responses being invalid with respect to data structures defined in API Declaration.

Under section 5.2 of the spec, it states that "If there are multiple authorization schemes described here, it means they're all applied." Is there a way to indicate that ANY instead of ALL authorization schemes are required?

Also, for the "apiKey" type, is there a way to indicate that multiple values are required? For example, 3Scale requires an app ID and app key, so you'd need two fields.

Currently isn't mentioned, and it is worth to do it, even though it is in a beta phase.
https://github.com/gettyimages/spray-swagger

Using the type File may conflict if there's a model called File in the generated spec, so we may want to come up with an alternative way to declare it.

If we make the changes in #32 - this issue becomes irrelevant (as the definition would be "type" : "File" and a reference to a File model will always be "$ref" : "File").

Hi,
We would love to use swagger for our API documentation, but there are 3 shortcomings that don't make this work:

• model objects can only be objects, not lists, so JavaScript [] cannot be represented, only {}
• requests cannot have type "json", so and API with the JSON encoded params in the POST body cannot be represented.
• swagger-ui doesn't display parent properties

We are ready to pay someone from the community to provide the following extensions and kindly ask for offers. Please provide the correct place for this request if you consider swagger-spec as an incorrect place.

Provide the following extensions to swagger and create pull requests on github:

• Extend the swagger-spec in chapter 5.2.7 so that a model object can contain a field "items" instead of "properties" and implement the extension. If a model has got items, it's JavaScript representation is [...] instead of {...}. This will allow the definition of array models and also nesting of array models. The implementation must also include an appropriate display format for array models in swagger-ui.
• Extend swagger-spec to allow a paramType "json" to describe request params that are encoded as JSON object in the request's POST body. Implement the param-type json so that the "Try it!" button from swagger-ui creates requesty with parameters encoded as JSON object in the request's POST body.
• Extend swagger-ui to display the properties of parent models. Models can be defined to have subTypes, but swagger-ui currently doesn't display the properties within the subTypes.

Some industry standards (such as GeoJSON) use nested arrays in their JSON models.

See:
Spec in English: http://www.geojson.org/geojson-spec.html
Spec in JSON: https://github.com/fge/sample-json-schemas/blob/master/geojson/geometry.json

A Geometry object has "type" property of "Point", "LineString", "Polygon", "MultiPoint", "MultiLineString", "MultiPolygon" or "GeometryCollection". It also has optional "coordinates" property (required for all values of "type" except "GeometryCollection") which would be an array of something (depending on the value of "type"). The other properties aren't relevant to this request.

A Point is a Geometry object with a "type" property of value "Point" and a "coordinates" property of an array of 2 or 3 doubles (lon/lat coordinates and optional elevation). So this one you can already handle (except for the min/max item count) as array[double].

A LineString is a Geometry object with a "type" property of value "LineString" and a "coordinates" property of an array of 2 or more connected Point coordinate arrays (so an array[array[double]]).

A MultiLineString is a Geometry object with a "type" property of value "MultiLineString" and a "coordinates" property of an array of 1 or more LineString coordinate arrays (so an array[array[array[double]]]).

We have other use cases for them but this particular case is an industry standard, so I thought it best to use that example here.

See also:
swagger-api/swagger-core#444
swagger-api/swagger-core#449

Right now this declaration is complex and there are some inconsistencies when declaring OAuth2 Grant flows.
For example, right now Implicit Grant looks like:

"implicit": {
  "loginEndpoint": {
    "url": "http://petstore.swagger.wordnik.com/oauth/dialog"
  },
  "tokenName": "access_token"
}

and authorization code looks like:

"authorization_code": {
  "tokenRequestEndpoint": {
    "url": "http://petstore.swagger.wordnik.com/oauth/requestToken",
    "clientIdName": "client_id",
     "clientSecretName": "client_secret"
  },
  "tokenEndpoint": {
    "url": "http://petstore.swagger.wordnik.com/oauth/token",
    "tokenName": "auth_code"
  }
}

You can see that for the Implicit, the tokenName field as at the base of the object, and in the Authorization Code it's at the Token Endpoint object.

I wrote a post about the possible changes that can be done in the google group, so I'm copying it here directly:

Looking at the the spec - http://tools.ietf.org/html/rfc6749 - and based on those blog posts, it seems that the whole definition can be simplified.

There are two type of endpoints involved in the OAuth2 process - the Authorization Endpoint and the Token Endpoint (http://tools.ietf.org/html/rfc6749#section-3).

These two endpoints are used in the 4 different grant flows (http://tools.ietf.org/html/rfc6749#section-4), but they're not always used.
So we have this:

• Authorization Code Grant - uses both.
• Implicit Grant - Only the Authorization Endpoint is used.
• Resource Owner Password Credentials Grant - Only the Token Endpoint is used.
• Client Credentials Grant - Only the Token Endpoint is used.

As far as I can tell, you can basically support all grant flows with those two endpoints. The difference between them will be with the parameters sent to them, and those are completely controlled by the client performing the authorization.

Currently, the swagger specification officially supports only the first two grant flows, but as you can see, we can easily modify it to support all four.

I would suggest it looks like:

"authorizations" : {
    "auth_name" : {
        "type" : "oauth2",
        "scopes" : ["scope1", "scope2", "..."],
        "authorizationEndpoint" : "https://....",
        "tokenEndpoint" : "https://....",
        "grantFlows" : ["Authorization Code", "Implicit", "Resource Owner Password Credentials", "Client Credentials"]
    }
}

If the server uses different authorization and token endpoints for different grant flows, then they could just create a different "auth_name" per set.

It's a good idea to keep the "scopes" there as this is metadata the developers may need to develop the app. In fact, we may want to expand on each scope giving an additional description to them so that the developer knows which scope means what.

One important difference between that and the current implementation is that it does not include the "tokenName", "clientIdName" and "clientSecretName" parameters. As far as I understand, those are meant to allow some flexibility in deciding what these parameters can be called. However, if I've read the oauth2 spec correctly, they are always "access_token", "client_id" and "client_secret" (respectively). In other words, the oauth2 spec doesn't allow flexibility in the naming convention and as such, we don't need to allow that in the swagger spec as well.

I have a case where I have an enumeration that can return different String values. The @ApiModelProperty's allowableValues is close, but I need to have metadata associated with each possible value. Something like this:

@ApiModelProperty(...., allowableValues={
@ApiModelPropertyValue( value="registered", description="Yada yada...", discriminator="PUT" ),
@ApiModelPropertyValue( value="active", description="Yada yada...", discriminator="PUT,POST" ),
@ApiModelPropertyValue( value="closed", description="Yada yada...", discriminator="POST" )
});

It seems like any time there is a value, you'd need to at least describe the possible values.

I took a rough first stab (definitely not complete) at creating a JSON Schema validator (like api-declaration-schema.json) for the new spec, is there any interest in having an official JSON schema, or do you want to keep swagger-spec primarily a textual reference?

https://github.com/silas/swagger-schema/tree/master/spec

The current format probably isn't acceptable for a published document.

This is an enhancement request, to allow optional authorizations. Not sure if this would be useful for others, but it would be for me.

In my case, you can access my APIs with no authorization, with OAuth, or with a set of two API keys. Depending on which you use, I may give you access to different data, but you still use the same APIs.

One way to handle this would be to allow a "required" boolean for each authorization in the API's Authorizations object.

If you did this, I could mark both of my oauth2 and apiKey authorizations as optional, which would allow you to select either or none of them. (It would also allow you to select both, but that's not really a problem.)

My case is also complicated by the fact that I need two parameters for my API key. If you wanted to treat this as a single Authorization, you'd have to allow multiple keynames for an apiKey. You could also treat it as two separate Authorizations, and just make them both optional. That's not ideal, since it wouldn't give you a way to indicate that they go together, but it would work.

It seems like the requirement for absolute base path for apis is very difficult for folks. I propose we still support it, but allow the spec & tooling to support relative paths.

The rule would be as follows:

if url starts with "http" it will be considered absolute. Otherwise, the scheme, host, and protocol will be derived from the location of the Api Declaration which is being served.

Since this is incremental, and still supports the absolute path that the spec requires, I believe it can be amended to the 1.2 spec w/o a revision.

Issue by quasipedia from Sunday Mar 02, 2014 at 00:44 GMT
Originally opened as https://github.com/wordnik/swagger-docs/issues/5

This has been extensively discussed here. But to make a quick summary, my proposal is:

1. deprecate type from the main body of the object.
2. rename responseMessages to responses.
3. have in each response code (the HTTP status, inclusive the ones in the 2xx family - if any), message (an informational message that the client can store and reuse for its GUI but that will not be transmitted at each response) and model (omitting this will be equivalent to "model": "void", i.e. a response without body).

I highlighted the reasons why I feel this is a better solution in the linked issue.

In the Operation Object, the nickname field is currently mandatory. I believe this should become optional for several reasons.

This field is not part of the documentation, which is what Swagger comes to serve. If I don't care about the code-gen, I shouldn't be forced to use it. More so, the fact that Swagger-UI requires it is a limitation of Swagger UI and shouldn't be imposed on the user (be it automatic or manual generation of it). In Swagger-Core, the user doesn't have to input the nickname, which means it's generated automatically as it is.

Also, different languages have different coding standards. AFAIK, javascript's standard is to use underscore between words rather than going camel case which is the Java standard. The code-gen should generate code that's more standard to the output language rather than conform to a predefined standard. Granted, more complicated but makes more sense.

Right now the deprecated field is of type string which makes no sense.
It should be changed to boolean.

This was also mentioned by @harrytruong in issue #19.

There is no standard for handling arrays as query parameters. We should be able to add a format structure to let the API server specify what it expects, and have swagger-js + codegen produce the correct structure.

Session cookies are one method of authentication available in Jira. See: https://docs.atlassian.com/jira/REST/6.2/#d2e4887

The process is that you visit a URL authenticating via some other method, and the response includes cookies that serve as your authentication for ongoing access.

A new Authorization Object type in 5.1.5 of "cookie" or "session-key" could work here, with "keyname" being required and specifying the cookie id used, and "login-url" giving a pointer to the API endpoint that needs to be accessed to set the cookie?

We've found some issues with resource listings that are static. The spec defines that the path attribute should be relative. However this produces a conflict when hosting the spec statically. It's solved in your examples by listing the full url to the path.

However, I think it would be appropriate to include a basePath attribute that would reference what you need to prepend to the resource object path to get to the rest of the listings. Having to try two URLs for the path attribute (fully qualified and relative) just doesn't feel clean, even if you check for http in the variable or something like that.

https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md#512-resource-object
https://github.com/wordnik/swagger-spec/blob/master/samples/helloworld/static/api-docs#L5

Issue by quasipedia from Saturday Mar 01, 2014 at 23:52 GMT
Originally opened as https://github.com/wordnik/swagger-docs/issues/1

The titles says it all, really. I might miss something obvious here, but why cannot an endpoint return a file in the response body (like an API serving songs or images)?

This is a long-time requested feature, and has many issues in the other repositories. All issues will be linked to here.

I'm not going into the solution at the moment. Feel free to open a discussion as to how you'd expect it to look in the spec (this should follow the JSON schema structure if there is one).

Related issues:

1. swagger-api/swagger-core#244
2. swagger-api/swagger-js#46
3. swagger-api/swagger-js#66
4. swagger-api/swagger-ui#241

https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md states in section 4.3.3 for "items"

Required. The type definition of the values in the container. A container MAY NOT be nested in another container.

MAY NOT is not listed in RFC 2119 and if we read it as negation of MAY, then it means the requirement is optional.

Better change it to MUST NOT (if it is realy required).

Not sure why there's the requirement of a preceding "/". This seems like a requirement to ease up on a the implementing libraries, but it doesn't make sense to be a requirement in the spec.

Many API providers are looking to add more vendor-specific metadata into the spec--one is adding information about SLAs, response time, request limits, etc.

In the Response Message Object, the responseModel should be converted to a type/$ref as it can also be a container or a primitive. It's also related to removing the type field from the Operation Object itself (#28).

Currently, there's no way for a 'general' API documentation. Even though REST API is supposed to be stateless, we don't live in a perfect world.

Maybe a Swagger user wants to give a description of a workflow, or several workflows.

Another possible use case for additional documentation - a way to describe changes between API versions.

The way we refer to model (complex) types is different between model (complex) type declarations, container declarations and Operation Object declarations. Normally, the field $ref is used, but in the case of Operation Object the field type is used. In Response Message Object the field responseModel is used. We should go with single variation for this, probably the $ref one to conform with JSON-Schema.

The apis field in the resource listing is mandatory but can be empty.

The proposed change is to make the apis field not mandatory. While this may not always make sense, as if there are no APIs there's no reason to have a resource listing, however this would be required in order to support operation filtering (which may end up with empty APIs).

Another option is to keep the field mandatory but enforce a non-empty array, however this would cause issues with the aforementioned use case.

I have a get operation that return two different classes (and it could be more) depending on a parameter input.
I could resolve it separating to multiple operations. One for each result class.
But it forces me to add a path for the GET.
Example: /persons/{id}/info=?
It returns PersonDto or EmployeeDto for BASIC or EMPLOYEE parameter.
The result are two classes totally different.
And I don't want to publish something like: /persons/{id}/full

models:

{
   UserKey: {
      id: 'User', 
      properties: {
          id: { type: 'integer', format: 'int64' }
      }
   },
   CollectionKey: {
      id: 'UsersCollection',
      properties: {
         items: { type: 'array', items: { $ref: 'UserKey' } }
      }
}

When displaying UsersCollection model swagger UI shows this:

UsersCollection {
   items (array[UserKey])
}
User {
   id (integer)
}

I think it should display items (array[User]) instead of items (array[UserKey]).
For me this is an issue because I declare many models with same id and different key to override model attributes for specific method - for example only email property for PUT /user and email and password for POST /user.

I posted this issue in swagger-ui repo but they redirected me here. I am little bit confused with current behaviour. In docs it states that $ref should refer to model id. In swagger ui it seems that they treat $ref as a model key. So who is right?

There's some confusion and repetitiveness when it comes to the allowMultiple properties (especially since it collides with the array type).

We need to either make better use of array or better clarify the uses for allowMultiple.

Currently, validation fields are not supported within arrays (whether list or set).

This means that fields like enum, minimum and so on cannot be used to validate/limit the values inside a container. This should be changed in a future version of the spec.

Link: https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md

• Section 3: a "fully qualified URL" can be defined as a "URI, as defined by [RFC 3986, section 3]; the scheme used by this URI MUST be http." file are also valid URLs after all ;)
• Section 4.1: should be completed with "unless otherwise specified, JSON objects defined by this specifications MUST NOT contain members [properties, fields, whatever] other than the ones defined in this specification".
• Also section 4.1: "JSON written for the swagger API MUST conform to the JSON grammar as defined in RFC 7159, section 2; security and interoperability considerations described in RFC 7159 also apply to the present specification".
• Section 4.3.3: little typo: "There currently two variations" (misses "are").

The parameters field in the Operation object is mandatory.

We should change it to optional if there are no parameters. There's no need to send an empty array in this case.

Swagger 1.2 lets you specify a discriminator and possible subtypes, but it doesn't relate the value of the discriminator and the model that should be instantiated. It would be convenient if this could be expressed in the spec.

Basically, should be a binary value encoded in base64.

Under "5.2 API Declaration", the "authorizations" field is listed as having the type "Authorizations Object". But from the description, it sounds like this is meant to just be a list of authorization names, and the actual Authorizations Object is only defined at the Resource Listing level.

Is this just supposed to be an array of strings? The example below it has "authorizations" set to an empty object.

Is there a way to use the Swagger Specification for WebSockets? It seems to be quite bound to HTTP.

Right now, the type for minimum and maximum fields is string. Besides the fact that this can lead to funny errors, we want to make sure we follow the JSON Schema definitions and convert the type to number.

This is a general issue for terminology changes in the specification.

There are a few words/phrases we use in the specification that we may either need to clarify or modify.

Examples:

1. Resource
2. Resource Listing
3. API
4. API declaration

The JSON Schema standard offers additional validation features such as minLength`maxLengthfor strings,exclusiveMinimum\exclusiveMaximum` for numbers and so on.

While we may not introduce all validation options at once, we should pick a set to add with each spec version.

Issue by quasipedia from Sunday Mar 02, 2014 at 00:38 GMT
Originally opened as https://github.com/wordnik/swagger-docs/issues/4

This is something I had some difficult myself when I first approach swagger as a newcomer a few weeks back. The word "API" is used liberally across documentation and specification keywords, often to refer to different things. Examples:

Swagger is a project used to describe and document RESTful APIs. The Swagger specification defines a set of files required to describe such an API

So, here "API" means what most programmers think an API is...

The API Declaration - This document describes a resource, including its API calls and models. There is one file per resource.

Here starts the tricky part: an "API" now becomes a set of resources, each one with "API" calls within it. So far the logic still holds, but it begins to get subtle (1 API → several API calls)

apis [ Resource Object ] Required. Lists the resources to be described by this specification implementation. They array can have 0 more elements.

Here starts the usage that I find erroneous: 1 API → several APIs, but most importantly, the contend of apis are indeed resources. (Why isn't the key called resources instead?)

apis [ API Object ] Required. A list of the APIs exposed on this resource. There MUST NOT be more than one API Object per path in the array.

Here the confusion increases: same key (apis) but radically different content. IMO the right term for this entry should be endpoints. WSDL - for example - defines an endpoint as:

the address or connection point to a Web service. It is typically represented by a simple HTTP URL string.

Which is precisely the same as swagger does with the 1:1 relationship with paths.

As requested in swagger-api/swagger-ui#444.

https://github.com/wordnik/swagger-spec/blob/master/versions/1.2.md#434-file

When using File, the consumes field MUST be "multipart/form-data", and the paramType MUST be "form".

But on Petstore reference demo (http://swagger.wordnik.com/#!//pet/uploadFile)
http://petstore.swagger.wordnik.com/api/api-docs/pet

    ...
    {
        "path": "/pet/uploadImage",
        "operations": [{
                        ...
            "parameters": [{
                ...
            },
            {
                "name": "file",
                "description": "file to upload",
                "required": false,
                "type": "File",
                "paramType": "body", // ?!
                "allowMultiple": false
            }]
        }]
    },
       ...

Just wondering why paramType is set to "body" instead of "form"? Am I reading this wrong?

Hi there,

I have some trouble describing one of our API outputs.

The output is something like this:
{"streams":{"id":1,"contacts":{"total":15,"Types":{"Followers":14,"Following":1},"Gender":{"Male":10,"Female":5}},"messages":{"total":20,"Types":{"DM":15,"Comments":5}}}}

(Or, in php:)

$data = array (
    'streams' => array (
        'id' => 1,
        'contacts' => array (
            'total' => 15,
            'Types' => array (
                'Followers' => 14,
                'Following' => 1
            ),
            'Gender' => array (
                'Male' => 10,
                'Female' => 5
            )
        ),
        'messages' => array (
            'total' => 20,
            'Types' => array (
                'DM' => 15,
                'Comments' => 5
            )
        )
    )
);

echo json_encode ($data);

Note that any of the groups (Types, Gender, etc) are not provided by the specs, but rather will be filled in according to available information.

Note also that the values of the groups can be random as well.

Any thoughts on how something like this could be described?

hi.

With clojure, it's possible to use Any as a field type. How should this be modeled for Swagger?

a pure clojure Schema looks like:

(def Pizza {:id    Long
            :name  String
            :meta  Any}

valid values for Pizza are for example:

{:id 1 :name "kikka" :meta 1}
{:id 2 :name "kukka" :meta nil}
{:id 3 :name "kakka" :meta {:more "stuff" :even {:more "here"}}}

for documentation purposes, it would be great to be able to say for return values "there will be something coming behind property :meta", but don't want to break the swagger-gen-clients if there is no way they can understand it.