Support for template schemas

[jmdacruz]

This is probably not a new question (it's been around for XML schemas as far as I know...), but couldn't find it anywhere on the open or closed issues, so here we go: Does Swagger support template schemas? I want the ability to define a partial or template schema that I can parameterize later. An application of such a feature would be a "Collection" schema which represents a collection of other objects (wrapping a plain array with metadata such as collection length, support for pagination, etc.)

GenericCollection:
    type: object
    required:
      - data
    properties:
      data:
        type: object
        required:
          - items
          - totalItems
        properties:
          currentItemCount:
            type: integer
          totalItems:
            type: integer
          items:
            type: array
            items:
              $ref: "#/definitions/AnObject"

On the above example, I want to be able to instantiate "GenericCollection" multiple times with different schemas for the "items" of the inner array structure, instead of having to define a new schema for each collection type by duplicating all the boilerplate (e.g., "PetCollection", "CarCollection").

Then, I could do something like this to reference and instantiate the template/partial schema:

$ref: "#/definitions/GenericCollection(#/definitions/AnObject)"
$ref: "#/definitions/GenericCollection(#/definitions/AnDifferentObject)"

This is something that may belong to the JSON schema spec (I think this would be the ideal scenario), or it may belong to a pre-processor feature in Swagger (one that simply transforms parameterized schemas into classic schemas, and yields an error when somebody tries to use an un-parameterized schema). MSON (the schema used by API Blueprint) supports this concept (see: https://github.com/apiaryio/mson/blob/master/MSON%20Specification.md#311-generic-named-declaration)

[webron]

@jmdacruz - this is more of a question to the spec and not swagger-core, which is one of many implementations. The short answer is that it is not supported, and that's because JSON Schema doesn't really allow it.

We are considering ways to over come this in the next version of the spec (for example, OAI/OpenAPI-Specification#555), and if you have any other input or suggestions, I'd urge you to either comment on existing tickets there or open new ones.

[jmdacruz]

Thanks, @webron! I'll check OAI/OpenAPI-Specification#555