Swagger: Reuse schema definition inside object property

Question

Problem: I want to reuse a definiton. Once directly and once inside an object. The following code works but the validator from http://editor.swagger.io/#/ is saying "Not a valid response definition" and pointing to the line "200".

Do I really have to define Account twice? Or is this an issue form the validator?

 *     responses:
 *       200: <---- ERROR POINTING HERE
 *         description: Updated account
 *         schema:
 *           type: object
 *           properties:
 *             data:
 *               type: object
 *               properties:
 *                 account:
 *                   schema:
 *                     $ref: '#/definitions/Account'

The definition itself:

 "Account" : {
    "type" : "object",
    "required": [
        "id", "username", "lastname", "firstname", "traderid", "customerid", "company", "validated"
    ],
    "properties": {
        "id": {
            "type": "string"
        },
        "username" : {
            "type": "string"
        },
        "lastname" : {
            "type": "string"
        },
        "firstname" : {
            "type": "string"
        },
        "traderid" : {
            "type": "string"
        },
        "customerid" : {
            "type": "string"
        },
        "company" : {
            "type": "string"
        },
        "validated" : {
            "type": "boolean"
        }
    },
    "example" : {
        "id": "57790fdde3fd3ed82681f39c",
        "username": "yuhucebafu",
        "validated": false,
        "customerid": "57790fdce3fd3ed82681f39a"
    }
},

Answer 1

The problem is with the use of schema in the account property.

200:
  description: Updated account
  schema:
   type: object
   properties:
     data:
       type: object
       properties:
         account:
           schema: # <-- Problem is here.
             $ref: '#/definitions/Account'

Here's the corrected response definition:

200:
  description: Updated account
  schema:
   type: object
   properties:
     data:
       type: object
       properties:
         account:
           $ref: '#/definitions/Account'

The property name "schema" is only used as a top-level property in Swagger's response object, or a parameter object where in is set to "body".

Once you've started specifying your schema, everything within that structure mostly follows standard JSON Schema, which is highly recursive. For example:

• Within an object schema, the value of each properties/[propertyName] is a schema.
• Within an array schema, the value of items is a schema.
• The value of each /definitions/[name] is a schema.
• The value of each array element within allOf, anyOf, or oneOf is a schema.
• The value of additionalProperties can be a schema (or a boolean value).
• ...

You get the idea. JSON Schema doesn't use the property name schema for all of these cases, because it would introduce a lot of noise in a language where practically "everything is a schema."