Polymorphism in Swagger produces strange error message on discriminator

Question

I'm writing a service with a GET that can return one of five different but closely related types. Since the user wants the option of searching through all five types at once, it has to be a single get call. I'm returning JSON, which can easily handle any type.

I'm trying to do this in Swagger, using their polymorphism feature, which I've never tried before. I'm doing it just like in the example, except under "definitions" instead of "components/schemas". But I'm getting a strange error message that I can't understand. The swagger file is below. The error says this:

Schema error at definitions['Event'].discriminator should be string

It gives this on line 49, which says discriminator:

So, my two questions are: How can I fix it? And will this even give me what I need?

swagger: '2.0'
info:
  description: RESTful API to retrieve Titles Metadata
  version: 1.0.0
  title: Swagger Mystery

schemes:
- https
paths:
  /event:
    get:
      operationId: getEvent
      summary: searches names
      description: |
        Search by names, across all types, or by a specific type.
      produces:
      - application/json
      parameters:
      - in: query
        name: title
        description: name to search for
        required: true
        type: string
      - in: query
        name: start
        required: false
        type: boolean
      - in: query
        name: type
        required: false
        type: string
        description: |
          May be "contest", "partner", "sponsor", or "dancer". If missing, will search for all types.
      responses:
        '200':
          description: search results
# I also don't know why I need to comment these out.
          # content:
          #   application/json:
          #     schema:
          #       type: array
          #       items:
          #         $ref: '#/definitions/Event'
        '400':
          description: bad input parameter
definitions:
  Event:
    type: object
    discriminator:
      propertyName: eventType
    properties:
      eventType:
        type: string
      id:
        type: integer
        format: int64
      name:
        type: string
      description:
        type: string
      contests:
        type: array
        items: 
          $ref: '#/definitions/Contest'
    required:
    - id
    - name
    - description
    - contests
    - eventType
  Contest:
    allOf:
    - $ref: '#/definitions/Event'
    - type: object
      properties:
        parentEvent:
          type: string
        venue:
          type: string
      required:
      - parentEvent
      - venue
  Dancer:
    allOf:
    - $ref: '#/definitions/Event'
    - type: object
      properties:
        eventInvitationDate:
          type: string
          format: date
        venue:
          type: string
      required:
      - eventInvitationDate
      - venue
  # Sponsor:
  #   allOf:
  #   - $ref: '#/definitions/Event'
  #   - type: object
  #     properties:
  #       invitationDate:
  #         type: string
  #         format: date
  #       parentEvent:
  #         type: string
  #       partners:
  #         type: array
  #         items:
  #           $ref: '#/definitions/Partner'
  Partner:
    allOf:
    - $ref: '#/definitions/Event'
    - type: object
      properties:
        invitationDate:
          type: string
          format: date
        parentEvent:
          type: string
        venue:
          type: string
      required:
      - invitationDate
      - parentEvent
      - venue
# two problems:
# 1. Schema error at definitions['Event'].discriminator
#    should be string on line 49 (discriminator:)
# 2. Resolver error:
#    e is undefined
#    (no line number)
#    (This error goes away when I comment out Sponsor.)

score 3 · Accepted Answer · answered Feb 14 '18 at 20:50

The error occurs because you are mixing OpenAPI 2.0 and 3.0 syntax.

Your spec is swagger: '2.0' but the following is 3.0 syntax:

discriminator:
  propertyName: eventType

In OpenAPI 2.0, the value of discriminator is the property name:

discriminator: eventType

Also, OpenAPI 2.0 assumes that the possible values of the discriminator property (in this case eventType) are exactly the same as the model names in definitions. That is:

If eventType can be event, partner etc. in lowercase, then the model names must also be in lowercase – event, not Event.
If eventType is some code like e, p, d etc., the model names must be e, p, d etc. instead of Event, Partner etc.

Check out questions for more examples of discriminator usage in OpenAPI 2.0:

So how do I use the OpenAPI 3.0 spec? The swagger editor doesn't allow anything higher than 2.0 for its version. — MiguelMunoz, Feb 15 '18 at 07:11
@MiguelMunoz It's `openapi: 3.0.0` (not `swagger: "3.0"`) and check out the guide at https://swagger.io/docs/specification/basic-structure/ because the 3.0 syntax is different from 2.0. — Helen, Feb 15 '18 at 10:31

Polymorphism in Swagger produces strange error message on discriminator

1 Answers1