swagger.yml

swagger.yml

swagger: '2.0'
info:
  title: Assess Authoring Service API (implemented)
  description: The current development state of the Assess Authoring Service API
  version: "0.0.1"
schemes:
  - https
basePath: /v1
produces:
  - application/json
tags:
  - name: assessments
  - name: forms
  - name: items
  - name: section_pools
  - name: assets
  - name: banks
securityDefinitions:
   # Authorization: Bearer abcdef12345
   Bearer:
     description: |
       All requests require a valid JWT token through the 'Authorization' header.

       A valid token must be obtained from idm.

       The header key will be 'Authorization' and the value will look like 'Bearer <token_from_idm>'
     type: apiKey
     in: header
     name: Authorization
security:
  - Bearer: []
paths:
  /assessments:
    post:
      tags:
        - assessments
      description: Create a new assessment
      parameters:
        - name: autocreate
          in: path
          description: If set to `form` it will automatically create a form and associate it to 
                       the assessment. If set to `section` it will automatically create a form 
                       and a section and propertly associate the whole graph.
          required: false
          schema: 
            type: string
            enum:
              - form
              - section

        - name: assessment_data
          in: body
          description: Data for new assessment
          required: true
          schema:
            type: object
            required:
              - details
              - scoring_rules
              - metadata
            properties:
              identifier:
                $ref: '#/definitions/Identifier'
              details:
                $ref: '#/definitions/AssessmentDetails'
              scoring_rules:
                $ref: '#/definitions/ScoringRules'
              metadata:
                $ref: '#/definitions/Metadata'
              extensions:
                $ref: '#/definitions/Extensions'
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/Assessment'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /assessments/{assessment_uuid}:
    get:
      tags:
        - assessments
      description: Returns an assessment based on a UUID
      parameters:
        - name: assessment_uuid
          in: path
          description: UUID of assessment
          required: true
          type: string
        - name: version
          in: query
          description: Version of assessment (returns max for UUID if not provided)
          required: false
          type: integer
        - name: full_assessment
          in: query
          description: Whether to return the full assessment graph or just references to related data
          required: false
          type: boolean
          default: false
        - name: format
          in: query
          description: Format of an assessment to be returned. Assessment definitions for v1 format (AIR) can be found here in the following url. http://assessdocs.mheducation.com/air/
          required: false
          type: string
          enum:
          - v1
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/Assessment'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      tags:
        - assessments
      description: Update an existing assessment
      parameters:
        - name: assessment_uuid
          in: path
          description: UUID of assessment
          required: true
          type: string
        - name: assessment_data
          in: body
          description: Data to update existing assessment with
          required: true
          schema:
            type: object
            required:
              - details
              - scoring_rules
              - metadata
            properties:
              details:
                $ref: '#/definitions/AssessmentDetails'
              policy:
                $ref: '#/definitions/Policy'
              scoring_rules:
                $ref: '#/definitions/ScoringRules'
              metadata:
                $ref: '#/definitions/Metadata'
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/Assessment'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /assessments/search:
    post:
      tags:
        - assessments
        - search
      description: Retrieves assessments based on filters
      parameters:
        - name: search_data
          in: body
          description: Logic and tags on which to filter
          required: true
          schema:
            $ref: '#/definitions/Filter'
      responses:
        "200":
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/SearchResponse'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /forms:
    post:
      tags:
        - forms
      description: Create a new form for an assessment containing the given section(s) or  section pool(s). The form will be scored based upon the supplied rules. An identifier block is currently requied but it can be an empty object. This requirement will be removed in a future version.
      parameters:
        - name: form_data
          in: body
          description: Data for new form
          required: true
          schema:
            $ref: '#/definitions/FormRequestBody'
      responses:
        "201":
          description: A Form response containing the supplied information with an additional identifier for the created form.
          schema:
            $ref: '#/definitions/Form'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /forms/{form_uuid}:
    get:
      tags:
        - forms
      description: Returns a Form based on given UUID with references to the section(s) or section_pool(s). The resonse will also contain the sequence of the section(s) and/or section pool(s).
      parameters:
        - name: form_uuid
          in: path
          description: UUID of form to return results for
          required: true
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        - name: version
          in: query
          description: Version of form (returns max for UUID if not provided) to return results for.
          required: false
          type: integer
        - name: sections
          in: query
          description: Whether to return the full section(s) the form contains or references to those section(s).
          required: false
          type: boolean
          default: false
        - name: section_pools
          in: query
          description: Whether to return the full section pool(s) the form contains or references to those section pool(s).
          required: false
          type: boolean
          default: false
      responses:
        "200":
          description: A Form response for the requested UUID and optional version. The response will contain full section(s) and/or section pool(s) if the corresponding query param is true
          schema:
            $ref: '#/definitions/FormFull'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      tags:
        - forms
      description: Update a form with the given UUID containing the given section(s) or section pool(s).
      parameters:
        - name: form_uuid
          in: path
          description: UUID of the form to update
          required: true
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        - name: form_data
          in: body
          description: The data to update the form with.
          required: true
          schema:
            $ref: '#/definitions/FormRequestBody'
      responses:
        "200":
          description: A Form response for the updated UUID.
          schema:
            $ref: '#/definitions/Form'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /items:
    post:
      tags:
        - items
      description: Create a new item. The details for an item will vary based upon item type. The definitions for the different item types can be found under `item_types`. An identifier block is currently requied but it can be an empty object. This requirement will be removed in a future version.
      parameters:
        - name: item_data
          in: body
          description: Data for new item
          required: true
          schema:
            $ref: '#/definitions/ItemRequestBody'
      responses:
        "201":
          description: OK
          schema:
            $ref: '#/definitions/Item'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /items/{item_uuid}:
    get:
      tags:
        - items
      description: Returns an item based on the provided UUID. The details for an item will vary based upon item type. The definitions for the different item types can be found under `item_types`.
      parameters:
        - name: item_uuid
          in: path
          description: UUID of item to return results for
          required: true
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        - name: version
          in: query
          description: Version of item (returns max for UUID if not provided)
          required: false
          type: integer
        - name: format
          in: query
          description: Format of an item to be returned. Item definitions for v1 format (AIR) can be found here in the following url. http://assessdocs.mheducation.com/air/
          required: false
          type: string
          enum:
          - v1 
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/Item'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      tags:
        - items
      description: Update an item with the given details. The details for an item will vary based upon item type. The definitions for the different item types can be found under `item_types`. An identifier block is currently requied but it can be an empty object. This requirement will be removed in a future version.
      parameters:
        - name: item_uuid
          in: path
          description: UUID of item
          required: true
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        - name: item_data
          in: body
          description: Data for updated item
          required: true
          schema:
            $ref: '#/definitions/ItemRequestBody'
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/Item'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /sections:
    post:
      tags:
        - sections
      description: Create a new section
      parameters:
        - name: section_data
          in: body
          description: Data for new section
          required: true
          schema:
            type: object
            required:
              - details
              - policy
              - scoring_rules
              - metadata
            properties:
              identifier:
                $ref: '#/definitions/Identifier'
              details:
                $ref: '#/definitions/SectionDetails'
              policy:
                $ref: '#/definitions/Policy'
              scoring_rules:
                $ref: '#/definitions/ScoringRules'
              metadata:
                $ref: '#/definitions/Metadata'
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/Section'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /sections/{section_uuid}:
    get:
      tags:
        - sections
      description: Returns an section based on a UUID
      parameters:
        - name: section_uuid
          in: path
          description: UUID of section
          required: true
          type: string
        - name: version
          in: query
          description: Version of section (returns max for UUID if not provided)
          required: false
          type: integer
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/Section'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      tags:
        - sections
      description: Update an existing section
      parameters:
        - name: section_uuid
          in: path
          description: UUID of section to update
          required: true
          type: string
        - name: section_data
          in: body
          description: Data to update section with
          required: true
          schema:
            type: object
            required:
              - details
              - policy
              - scoring_rules
              - metadata
            properties:
              identifier:
                $ref: '#/definitions/Identifier'
              details:
                $ref: '#/definitions/SectionDetails'
              policy:
                $ref: '#/definitions/Policy'
              scoring_rules:
                $ref: '#/definitions/ScoringRules'
              metadata:
                $ref: '#/definitions/Metadata'
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/Section'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /section_pools:
    post:
      tags:
        - section_pools
      description: Create a new section pool containing the given section pool details. The form will be scored based upon the supplied rules. An identifier block is currently requied but it can be an empty object. This requirement will be removed in a future version.
      parameters:
        - name: section_pool_data
          in: body
          description: Data for new section pool
          required: true
          schema:
            $ref: '#/definitions/SectionPoolRequestBody'
      responses:
        "201":
          description: OK - Returns a `SectionPool` object that contains an identifier to the sections contained in the pool. A GET request must be made to `/section_pools/{section_pool_uuid}` retrieve the full contents of the sections associated to the section pool.
          schema:
            $ref: '#/definitions/SectionPool'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /section_pools/{section_pool_uuid}:
    get:
      tags:
        - section_pools
      description: Returns a Section Pool based on given UUID. If the querystring parameter `sections` is present full sections will be returned. The value of the `sections` querystring paramter has no bearing on the response returning full sections, only the presence of the parameter.
      parameters:
        - name: section_pool_uuid
          in: path
          description: UUID of section
          required: true
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        - name: version
          in: query
          description: Version of section pool (returns max for UUID if not provided)
          required: false
          type: integer
        - name: sections
          in: query
          description: Whether to return full definition of sections within section pool
          required: false
          type: boolean
          default: false
      responses:
        "200":
          description: OK - The response will contain full sections if the querystring paramter `sections` is present, else it will contain pointers to the contained sections.
          schema:
            $ref: '#/definitions/SectionPoolFull'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      tags:
        - section_pools
      description: Create a new version of a section pool containing the given section pool details. The pool will be scored based upon the supplied rules. An identifier block is currently requied but it can be an empty object. This requirement will be removed in a future version.
      parameters:
        - name: section_pool_uuid
          in: path
          description: UUID of section to update.
          required: true
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        - name: section_pool_data
          in: body
          description: Data for new version of the section pool
          required: true
          schema:
            $ref: '#/definitions/SectionPoolRequestBody'
      responses:
        "200":
          description: OK - Returns a `SectionPool` object that contains an identifier to the sections contained in the pool. A GET request must be made to `/section_pools/{section_pool_uuid}` retrieve the full contents of the sections associated to the section pool.
          schema:
            $ref: '#/definitions/SectionPool'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /assets:
    post:
      tags:
        - assets
      description: Create a new asset containing the given details and metadata. The `asset_details` property is defined based up on the `asset_type` property. The definitions of the possible `asset_details` can be found under the `asset_types` tag
      parameters:
        - name: asset_data
          in: body
          description: Data for new asset
          required: true
          schema:
            $ref: '#/definitions/AssetRequestBody'
      responses:
        "201":
          description: OK
          schema:
            $ref: '#/definitions/Asset'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /assets/{asset_uuid}:
    get:
      tags:
        - assets
      description: Returns an asset based on the provided  UUID
      parameters:
        - name: asset_uuid
          in: path
          description: UUID of asset
          required: true
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        - name: version
          in: query
          description: Version of asset (returns max for UUID if not provided)
          required: false
          type: integer
        - name: format
          in: query
          description: Format of an asset to be returned. Asset definitions for v1 format (AIR) can be found here in the following url. http://assessdocs.mheducation.com/air/
          required: false
          type: string
          enum:
          - v1
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/Asset'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      tags:
        - assets
      description: Updates and existing asset. The `asset_details` property is defined based up on the `asset_type` property. The definitions of the possible `asset_details` can be found under the `asset_types` tag
      parameters:
        - name: asset_uuid
          in: path
          description: UUID of asset
          required: true
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        - name: asset_data
          in: body
          description: Data to be updated on asset
          required: true
          schema:
            $ref: '#/definitions/AssetRequestBody'
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/Asset'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /banks:
    post:
      tags:
        - banks
      description: Create a new bank
      parameters:
        - name: bank_data
          in: body
          description: Data for new bank
          required: true
          schema:
            $ref: '#/definitions/BankRequestBody'
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/Bank'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /banks/{bank_uuid}:
    get:
      tags:
        - banks
      description: Returns a bank based on a UUID
      parameters:
        - name: bank_uuid
          in: path
          description: UUID of bank
          required: true
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        - name: version
          in: query
          description: Version of bank (returns max for UUID if not provided)
          required: false
          type: integer
        - name: contents
          in: query
          description: If `true` the response will contain the children entities full data, else will contain minimal information.
          required: false
          type: boolean
        - name: limit
          in: query
          description: Number of bank entities to return
          required: false
          type: integer
          default: 100
        - name: offset
          in: query
          description: Starting index of bank entities to return
          required: false
          type: integer
          default: 0
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/Bank'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
    put:
      tags:
        - banks
      description: Update a bank
      parameters:
        - name: bank_uuid
          in: path
          description: UUID of bank
          required: true
          type: string
          pattern: '^[a-fA-F0-9]{32}$'
        - name: bank_data
          in: body
          description: Data for updated bank
          required: true
          schema:
            $ref: '#/definitions/BankRequestBody'
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/Bank'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /banks/{bank_uuid}/hierarchy-validation:
    get:
      tags:
        - banks
      description: Check if a bank hierarchy is valid
      parameters:
        - name: bank_uuid
          in: path
          description: UUID of bank
          required: true
          type: string
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/Bank'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /banks/{bank_uuid}/children:
    post:
      tags:
        - banks
      description: Add entities to a bank
      parameters:
        - name: bank_uuid
          in: path
          description: UUID of bank
          required: true
          type: string
        - name: bank_entities
          in: body
          required: true
          schema:
            type: array
            minItems: 1
            uniqueItems: true
            items:
              $ref: '#/definitions/BankEntityIdentifier'
      responses:
        "200":
          description: OK
          schema:
            type: array
            minItems: 1
            uniqueItems: true
            items:
              $ref: '#/definitions/BankEntityIdentifier'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'
  /banks/search:
    post:
      tags:
        - banks
        - search
      description: Retrieves banks based on filters
      parameters:
        - name: search_data
          in: body
          description: Logic and tags on which to filter banks
          required: true
          schema:
            $ref: '#/definitions/Filter'
      responses:
        "200":
          description: OK
          schema:
            type: array
            items:
              $ref: '#/definitions/Bank'
        default:
          description: Unexpected error
          schema:
            $ref: '#/definitions/Error'

definitions:

############# ItemType Definitions ###################

  #TODO: When polymorphic objects are supported by swagger UI we should removed the ItemDetails Namespace from all of the item types. Currently the discriminator is broken because of the namespace, but it renders ok in the UI and passes validation.
  ItemDetails.multiple_choice:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/multiple_choice.json'
  ItemDetails.multiple_choice_multi_select:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/multiple_choice_multi_select.json'
  ItemDetails.matching:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/matching.json'
  ItemDetails.short_answer:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/short_answer.json'
  ItemDetails.essay:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/essay.json'
  ItemDetails.fill_in_the_blank:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/fill_in_the_blank.json'
  ItemDetails.cloze:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/cloze.json'
  ItemDetails.file_upload:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/file_upload.json'
  ItemDetails.image_labels:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/image_labels.json'
  ItemDetails.draw_on_image:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/draw_on_image.json'
  ItemDetails.bucketing:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/bucketing.json'
  ItemDetails.ordering:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/ordering.json'
  ItemDetails.grid_in:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/grid_in.json'
  ItemDetails.graphing:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/graphing.json'
  ItemDetails.audio_recording:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/audio_recording.json'
  ItemDetails.select_text:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/select_text.json'
  ItemDetails.number_line:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/number_line.json'
  ItemDetails.equation_entry:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/equation_entry.json'
  ItemDetails.choice_matrix:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/choice_matrix.json'
  ItemDetails.accounting_worksheet:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/accounting_worksheet.json'
  ItemDetails.external:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - item_details
        properties:
          item_details:
            $ref: 'item_schemas/external.json'

############# AssetType Definitions ###################

  #TODO: When polymorphic objects are supported by swagger UI we should removed the AssetDetails Namespace from all of the asset types. Currently the discriminator is broken because of the namespace, but it renders ok in the UI and passes validation.
  AssetDetails.dataset:
    allOf:
      - $ref: '#/definitions/AssetDetails'
      - type: object
        required:
          - asset_details
        properties:
          asset_details:
            $ref: 'asset_schemas/asset_type_dataset.json'
  AssetDetails.rubric:
    allOf:
      - $ref: '#/definitions/AssetDetails'
      - type: object
        required:
          - asset_details
        properties:
          asset_details:
            $ref: 'asset_schemas/asset_type_rubric.json'
  AssetDetails.glossary:
    allOf:
      - $ref: '#/definitions/AssetDetails'
      - type: object
        required:
          - asset_details
        properties:
          asset_details:
            $ref: 'asset_schemas/asset_type_glossary.json'
  AssetDetails.media_file:
    allOf:
      - $ref: '#/definitions/AssetDetails'
      - type: object
        required:
          - asset_details
        properties:
          asset_details:
            $ref: 'asset_schemas/asset_type_media_file.json'
  AssetDetails.reference_sheet:
    allOf:
      - $ref: '#/definitions/AssetDetails'
      - type: object
        required:
          - asset_details
        properties:
          asset_details:
            $ref: 'asset_schemas/asset_type_reference_sheet.json'
  AssetDetails.example_response:
    allOf:
      - $ref: '#/definitions/AssetDetails'
      - type: object
        required:
          - asset_details
        properties:
          asset_details:
            $ref: 'asset_schemas/asset_type_example_response.json'
  AssetDetails.passage:
    allOf:
      - $ref: '#/definitions/AssetDetails'
      - type: object
        required:
          - asset_details
        properties:
          asset_details:
            $ref: 'asset_schemas/asset_type_passage.json'
  AssetDetails.hint:
    allOf:
      - $ref: '#/definitions/AssetDetails'
      - type: object
        required:
          - asset_details
        properties:
          asset_details:
            $ref: 'asset_schemas/asset_type_snippet.json'
  AssetDetails.explanation:
    allOf:
      - $ref: '#/definitions/AssetDetails'
      - type: object
        required:
          - asset_details
        properties:
          asset_details:
            $ref: 'asset_schemas/asset_type_snippet.json'
  AssetDetails.feedback:
    allOf:
      - $ref: '#/definitions/AssetDetails'
      - type: object
        required:
          - asset_details
        properties:
          asset_details:
            $ref: 'asset_schemas/asset_type_snippet.json'
  AssetDetails.instruction:
    allOf:
      - $ref: '#/definitions/AssetDetails'
      - type: object
        required:
          - asset_details
        properties:
          asset_details:
            $ref: 'asset_schemas/asset_type_snippet.json'

############# Assessment Definitions ###################

  AssessmentIdentifier:
    type: object
    required:
      - assessment_uuid
    properties:
      assessment_uuid:
        description: The UUID of the assesment.
        type: string
        pattern: '^[a-fA-F0-9]{32}$'
      assessment_version:
        description: The version of the assessment.
        type: integer
  AssessmentDetails:
    type: object
    required:
      - name
      - assessment_type
    properties:
      name:
        type: string
        description: Name of assessment
      assessment_type:
        type: string
        description: Type of assessment
        enum:
          - quiz
          - exam
          - practice
          - homework
      policy:
        type: object
        properties:
          student_tools:
            type: object
            properties:
              highlighter:
                type: boolean
              notepad:
                type: boolean
              magnifier:
                type: boolean
              line_reader:
                type: boolean
              protractor:
                type: boolean
              calculator:
                type: string
                enum:
                  - scientific
                  - simple
                  - graphing
      form_selection_algorithm:
        type: string
        enum:
          - Proportional Distribution
        description: Name of algorithm with which to override default form selection algorithm
      form_selection_algorithm_parameters:
        type: string
  Assessment:
    type: object
    required:
      - identifier
      - name
      - assessment_type
      - scoring_rules
      - publication_status
      - metadata
    properties:
      identifier:
        $ref: '#/definitions/Identifier'
      name:
        type: string
        description: Name of assessment
      assessment_type:
        type: string
        description: Type of assessment
        enum:
          - quiz
          - exam
          - practice
          - homework
      forms:
        type: array
        items:
          type: object
          properties:
            form_uuid:
              type: string
            form_version:
              type: integer
            form_name:
              type: string 
      # TODO: implement assets
      # assets:
      #   type: array
      #   items:
      #     allOf:
      #       - $ref: '#/definitions/AssetIdentifier'
      #       - type: object
      #         properties:
      #           sequence:
      #             type: integer
      #             description: Order in which to present asset (optional if only 1 asset, otherwise must be unique amongst assets within assessment)
      # full_assets:
      #   type: array
      #   items:
      #     $ref: '#/definitions/Asset'
      publication_status:
        $ref: '#/definitions/PublicationStatus'
      form_selection_algorithm:
        type: string
        enum:
          - Proportional Distribution
        description: Name of algorithm with which to override default form selection algorithm
      form_selection_algorithm_parameters:
        type: string
      policy:
        $ref: '#/definitions/Policy'
      scoring_rules:
        type: string
      metadata:
        $ref: '#/definitions/Metadata'
  SearchResponse:
    type: object
    required:
      - name
      - uuid
      - version
    properties:
      name:
        type: string
        description: Name of assessment.
      uuid:
        type: string
        description: Uuid of search item.
      version:
        type: integer 
        description: version of search item.
####### Form Definitions #############

  FormIdentifier:
    type: object
    required:
      - form_uuid
    properties:
      form_uuid:
        description: The UUID of the form.
        type: string
        pattern: '^[a-fA-F0-9]{32}$'
      form_version:
        description: The version of the form.
        type: integer
  FormSection:
    allOf:
      - $ref: '#/definitions/SectionIdentifier'
      - type: object
        required:
          - sequence
        properties:
          sequence:
            description: Order in which to present section. Must be unique amongst sections AND section pools for a form.
            type: integer
  FormSectionPool:
    allOf:
      - $ref: '#/definitions/SectionPoolIdentifier'
      - $ref: '#/definitions/SectionPoolSelectionAlgorithm'
      - type: object
        required:
          - sequence
        properties:
          sequence:
            description:  Order in which to present section pool. Must be unique amongst sections AND section pools for a form.
            type: integer
  FormDetails:
    type: object
    required:
      - name
    properties:
      name:
        type: string
      sections:
        type: array
        items:
          $ref: '#/definitions/FormSection'
      section_pools:
        type: array
        items:
          $ref: '#/definitions/FormSectionPool'
      assessment:
        $ref: '#/definitions/AssessmentIdentifier'
  Form:
    type: object
    required:
      - identifier
      - name
      - publication_status
      - scoring_rules
    properties:
      identifier:
        $ref: '#/definitions/Identifier'
      name:
        type: string
      sections:
        type: array
        items:
          $ref: '#/definitions/FormSection'
      section_pools:
        type: array
        items:
          $ref: '#/definitions/FormSectionPool'
      assessment:
        $ref: '#/definitions/AssessmentIdentifier'
      publication_status:
        $ref: '#/definitions/PublicationStatus'
      scoring_rules:
        type: string
  FormFull:
    allOf:
      - $ref: '#/definitions/Form'
      - type: object
        properties:
          full_sections:
            type: array
            items:
              $ref: '#/definitions/Section'
          full_section_pools:
            type: array
            items:
              $ref: '#/definitions/SectionPoolFull'
  FormRequestBody:
    type: object
    required:
      - identifier
      - details
      - scoring_rules
      - metadata
    properties:
      identifier:
        $ref: '#/definitions/Identifier'
      details:
        $ref: '#/definitions/FormDetails'
      scoring_rules:
        $ref: '#/definitions/ScoringRules'
      metadata:
        $ref: '#/definitions/Metadata'

########### Section Definitions ##############

  SectionIdentifier:
    type: object
    required:
      - section_uuid
    properties:
      section_uuid:
        description:  The UUID of the section
        type: string
        pattern: '^[a-fA-F0-9]{32}$'
      section_version:
        description: The version of the section
        type: integer
  SectionDetails:
    type: object
    required:
      - section_type
    properties:
      section_type:
        type: string
        enum:
          - section
          - compound_item
          - accounting_worksheet
          - display_group
      # assets:
      #   type: array
      #   items:
      #     type: object
      #     required:
      #       - asset_uuid
      #       - asset_version
      #     properties:
      #       asset_uuid:
      #         type: string
      #       asset_version:
      #         type: integer
      #       sequence:
      #         type: integer
      #         description: Order in which to present asset (optional if only 1 asset, otherwise must be unique amongst assets within section)
      items:
        type: array
        items:
          type: object
          required:
            - item_uuid
            - sequence
          properties:
            item_uuid:
              type: string
            item_version:
              type: integer
            sequence:
              type: integer
              description: Order of item within section. Must be unique for items, subsections, section pools AND item pools within section.
      item_pools:
        type: array
        items:
          type: object
          required:
            - item_pool_uuid
            - sequence
          properties:
            item_pool_uuid:
              type: string
            item_pool_version:
              type: integer
            sequence:
              type: integer
              description: Order of item pool within section. Must be unique for items, subsections, section pools AND item pools within section.
            item_pool_selection_algorithm:
              type: string
              description: Name of algorithm with which to override default item pool selection algorithm
            item_pool_selection_algorithm_parameters:
              type: string
      subsections:
        type: array
        items:
          type: object
          required:
            - section_uuid
            - sequence
          properties:
            section_uuid:
              type: string
            section_version:
              type: integer
            sequence:
              type: integer
              description: Order of sub-section within section. Must be unique for items, subsections, section pools AND item pools within section.
      section_pools:
        type: array
        items:
          type: object
          required:
            - section_pool_uuid
            - sequence
          properties:
            section_pool_uuid:
              type: string
            section_pool_version:
              type: integer
            sequence:
              type: integer
              description: Order of section pool within section. Must be unique for items, subsections, section pools AND item pools within section.
            section_pool_selection_algorithm:
              type: string
              description: Name of algorithm with which to override default section pool selection algorithm
            section_pool_selection_algorithm_parameters:
              type: string
  Section:
    type: object
    required:
      - identifier
      - section_type
      - publication_status
      - policy
      - scoring_rules
    properties:
      identifier:
        $ref: '#/definitions/Identifier'
      section_type:
        type: string
        enum:
          - section
          - compound_item
          - accounting_worksheet
          - display_group
      # assets:
      #   type: array
      #   items:
      #     allOf:
      #       - $ref: '#/definitions/AssetIdentifier'
      #       - type: object
      #         properties:
      #           sequence:
      #             type: integer
      #             description: Order in which to present asset (optional if only 1 asset, otherwise must be unique amongst assets within section)
      # full_assets:
      #   type: array
      #   items:
      #     $ref: '#/definitions/Asset'
      items:
        type: array
        items:
          allOf:
            - $ref: '#/definitions/ItemIdentifier'
            - type: object
              properties:
                sequence:
                  type: integer
                  description: Order of item within section. Must be unique for items, subsections, section pools AND item pools within section.
      item_pools:
        type: array
        items:
          allOf:
            - $ref: '#/definitions/ItemPoolIdentifier'
            - type: object
              required:
                - sequence
              properties:
                sequence:
                  type: integer
                  description: Order of item pool within section. Must be unique for items, subsections, section pools AND item pools within section.
                item_pool_selection_algorithm:
                  type: string
                item_pool_selection_algorithm_parameters:
                  type: string
      subsections:
        type: array
        items:
          allOf:
            - $ref: '#/definitions/SectionIdentifier'
            - type: object
              properties:
                sequence:
                  type: integer
                  description: Order of sub-section within section. Must be unique for items, subsections, section pools AND item pools within section.
      section_pools:
        type: array
        items:
          allOf:
            - $ref: '#/definitions/SectionIdentifier'
            - $ref: '#/definitions/SectionPoolSelectionAlgorithm'
            - type: object
              properties:
                sequence:
                  type: integer
                  description: Order of section pool within section. Must be unique for items, subsections, section pools AND item pools within section.
      policy:
        $ref: '#/definitions/Policy'
      publication_status:
        $ref: '#/definitions/PublicationStatus'
      scoring_rules:
        type: string

########### Item Definitions ##############

  ItemIdentifier:
    type: object
    required:
      - item_uuid
    properties:
      item_uuid:
        description:  The UUID of the item
        type: string
        pattern: '^[a-fA-F0-9]{32}$'
      item_version:
        description:  The version of the item
        type: integer
  ItemDetails:
    type: object
    description: A polymorphic object that is keyed from the item_type. All acceptable item_details definitions are listed in `Models` with a namespace of `ItemDetails`
    required:
      - item_details
      - item_type
    discriminator: item_type
    properties:
      item_details:
        type: object
        description: The definition of this object varies by the corresponding `item_type` property. All acceptable `item_details` definitions are listed in `Models` with a namespace of `ItemDetails`
      item_type:
        type: string
        description: The type of item that is being passed in the `item_details` property. This is the key that triggers the correct validation on the `item_details` properties.
        enum:
          - multiple_choice
          - multiple_choice_multi_select
          - matching
          - short_answer
          - essay
          - fill_in_the_blank
          - cloze
          - file_upload
          - image_labels
          - draw_on_image
          - bucketing
          - ordering
          - grid_in
          - graphing
          - audio_recording
          - select_text
          - number_line
          - equation_entry
          - choice_matrix
          - accounting_worksheet
          - external
      scoring_rules:
        type: object
        description: The item's scoring rules
        required:
          - type
          - points
        properties:
          type:
            type: string
            description: Type of scoring for this item. Each item type has an allowed list of scoring types
            enum:
              - perfect
              - manual
          points:
            type: float
            description: Point value of the item
      assets:
        description: A list of references to assets the item contains and the order (sequence) of the asset
        type: array
        items:
          $ref: '#/definitions/ItemAsset'
  ItemAsset:
    allOf:
      - $ref: '#/definitions/AssetIdentifier'
      - type: object
        properties:
          sequence:
            description: Order in which to present asset (optional if only 1 asset, otherwise must be unique amongst assets within item)
            type: integer
  ItemRequestBody:
    type: object
    required:
      - identifier
      - details
      - policy
      - metadata
    properties:
      identifier:
        description: This is required, but can be an empty object.
        $ref: '#/definitions/Identifier'
      details:
        $ref: '#/definitions/ItemDetails'
      policy:
        $ref: '#/definitions/Policy'
      metadata:
        $ref: '#/definitions/Metadata'
      extensions:
        $ref: '#/definitions/Extensions'
  Item:
    allOf:
      - $ref: '#/definitions/ItemDetails'
      - type: object
        required:
          - identifier
          - policy
          - publication_status
        properties:
          identifier:
            $ref: '#/definitions/Identifier'
    #      full_assets:
    #        type: array
    #        items:
    #          $ref: '#/definitions/Asset'
          policy:
            $ref: '#/definitions/Policy'
          publication_status:
            $ref: '#/definitions/PublicationStatus'

############# Bank Definitions ###################

  BankRequestBody:
    type: object
    required:
      - identifier
      - details
      - metadata
    properties:
      identifier:
        description: This is required, but can be an empty object.
        $ref: '#/definitions/Identifier'
      details:
        $ref: '#/definitions/BankDetails'
      metadata:
        $ref: '#/definitions/Metadata'
      hierarchy:
        $ref: '#/definitions/BankHierarchy'
      extensions:
        $ref: '#/definitions/Extensions'
  BankType:
    type: string
    description: Type of content within bank
    enum:
      - assessment
      - asset
      - dataset
      - glossary
      - media_file
      - passage
      - rubric
      - bank
      - item
      - item_pool
      - section
      - section_pool
  BankDetails:
    type: object
    required:
      - type
      - name
    properties:
      type:
        $ref: '#/definitions/BankType'
      name:
        type: string
  Bank:
    type: object
    required:
      - identifier
      - type
      - name
      - publication_status
    properties:
      identifier:
        $ref: '#/definitions/Identifier'
      type:
        $ref: '#/definitions/BankType'
      name:
        type: string
      entities:
        type: array
        items:
          $ref: '#/definitions/BankEntityIdentifier'
      publication_status:
        $ref: '#/definitions/PublicationStatus'
      metadata:
        $ref: '#/definitions/Metadata'
      hierarchy:
        $ref: '#/definitions/BankHierarchy'
      extensions:
        $ref: '#/definitions/Extensions'
  BankFull:
    type: object
    required:
      - identifier
      - type
      - name
      - publication_status
    properties:
      identifier:
        $ref: '#/definitions/Identifier'
      type:
        $ref: '#/definitions/BankType'
      name:
        type: string
      entities:
        type: array
        items:
          $ref: '#/definitions/BankEntityIdentifier'
      full_assessments:
        type: array
        items:
          $ref: '#/definitions/Assessment'
      full_assets:
        type: array
        items:
          $ref: '#/definitions/Asset'
      full_banks:
        type: array
        items:
          $ref: '#/definitions/Bank'
      full_items:
        type: array
        items:
          $ref: '#/definitions/Item'
      full_item_pools:
        type: array
        items:
          $ref: '#/definitions/ItemPool'
      full_sections:
        type: array
        items:
          $ref: '#/definitions/Section'
      full_section_pools:
        type: array
        items:
          $ref: '#/definitions/SectionPoolFull'
      publication_status:
        $ref: '#/definitions/PublicationStatus'
      metadata:
        $ref: '#/definitions/Metadata'
      hierarchy:
        $ref: '#/definitions/BankHierarchy'
      extensions:
        $ref: '#/definitions/Extensions'
  BankHierarchy:
    type: object
    title: 'Tree structure of a bank'
    description: 'Must have `folders` or `entities` but not both.'
    properties:
      folders:
        type: array
        items:
          $ref: '#/definitions/BankFolder'
      entities:
        type: array
        items:
          $ref: '#/definitions/BankEntity'
  BankFolder:
    type: object
    description: 'Must have `folders` or `entities` but not both.'
    properties:
      title:
        type: string
      folders:
        type: array
        items:
          $ref: '#/definitions/BankFolder'
      entities:
        type: array
        items:
          $ref: '#/definitions/BankEntity'
  BankEntity:
    allOf:
    - $ref: '#/definitions/BankEntityIdentifier'
    - type: object
      properties:
        title:
          type: string
  BankEntityIdentifier:
    type: object
    required:
      - uuid
    properties:
      uuid:
        type: string
        pattern: '^[a-fA-F0-9]{32}$'
      version:
        type: integer

  ############# ItemPool Definitions ###################

  ItemPoolIdentifier:
    type: object
    required:
      - item_pool_uuid
    properties:
      item_pool_uuid:
        description:  The UUID of the item pool
        type: string
        pattern: '^[a-fA-F0-9]{32}$'
      item_pool_version:
        description:  The version of the item pool
        type: integer
  ItemPoolDetails:
    type: object
    required:
      - name
      - items_to_choose
      - items
    properties:
      name:
        type: string
      item_pool_selection_algorithm:
        type: string
      item_pool_selection_algorithm_parameters:
        type: string
      items_to_choose:
        type: integer
        description: Number of items selected from the pool
      items:
        type: array
        items:
          allOf:
            - $ref: '#/definitions/ItemIdentifier'
            - type: object
              required:
                - sequence
              properties:
                sequence:
                  type: integer
                  description: Order of item within pool. Must be unique within pool.
  ItemPool:
    type: object
    required:
      - identifier
      - name
      - items_to_choose
      - items
      - publication_status
      - scoring_rules
    properties:
      identifier:
        $ref: '#/definitions/Identifier'
      name:
        type: string
      item_pool_selection_algorithm:
        type: string
      item_pool_selection_algorithm_parameters:
        type: string
      items_to_choose:
        type: integer
        description: Number of items selected from the pool
      items:
        type: array
        items:
          allOf:
            - $ref: '#/definitions/ItemIdentifier'
            - type: object
              required:
                - sequence
              properties:
                sequence:
                  type: integer
                  description: Order of item within pool. Must be unique within pool.
      full_items:
        type: array
        items:
          $ref: '#/definitions/Item'
      publication_status:
        $ref: '#/definitions/PublicationStatus'
      scoring_rules:
        type: string

  ############# SectionPool Definitions ###################

  SectionPoolIdentifier:
    type: object
    required:
      - section_pool_uuid
    properties:
      section_pool_uuid:
        description:  The UUID of the section pool added to the form
        type: string
        pattern: '^[a-fA-F0-9]{32}$'
      section_pool_version:
        description: The version of the section pool added to the form
        type: integer
  SectionPoolSelectionAlgorithm:
    type: object
    properties:
      section_pool_selection_algorithm:
        type: string
      section_pool_selection_algorithm_parameters:
        type: string
  SectionPoolSection:
    allOf:
      - $ref: '#/definitions/SectionIdentifier'
      - type: object
        required:
          - sequence
        properties:
          sequence:
            type: integer
            description: Order of section within pool. Must be unique within pool.
  SectionPoolDetails:
    type: object
    required:
      - name
      - section_pool_selection_algorithm
      - sections_to_choose
      - sections
    properties:
      name:
        type: string
      section_pool_selection_algorithm:
        type: string
      section_pool_selection_algorithm_parameters:
        type: string
      sections_to_choose:
        type: integer
        description: Number of sections to select from the pool
      sections:
        type: array
        items:
          $ref: '#/definitions/SectionPoolSection'
  SectionPoolFull:
    type: object
    required:
      - identifier
      - name
      - section_pool_selection_algorithm
      - sections_to_choose
      - sections
      - publication_status
      - scoring_rules
    properties:
      identifier:
        $ref: '#/definitions/Identifier'
      name:
        type: string
      section_pool_selection_algorithm:
        type: string
      section_pool_selection_algorithm_parameters:
        type: string
      sections_to_choose:
        type: integer
        description: Number of section selected from the pool
      sections:
        type: array
        items:
          $ref: '#/definitions/SectionPoolSection'
      publication_status:
        $ref: '#/definitions/PublicationStatus'
      scoring_rules:
        type: string
      full_sections:
        type: array
        items:
          $ref: '#/definitions/Section'
  SectionPoolRequestBody:
    type: object
    required:
      - identifier
      - details
      - scoring_rules
      - metadata
    properties:
      identifier:
        description: This field is required but it can be an empty object.
        $ref: '#/definitions/Identifier'
      details:
        $ref: '#/definitions/SectionPoolDetails'
      scoring_rules:
        $ref: '#/definitions/ScoringRules'
      metadata:
        $ref: '#/definitions/Metadata'
  SectionPool:
    type: object
    required:
      - identifier
      - name
      - section_pool_selection_algorithm
      - sections_to_choose
      - sections
      - publication_status
      - scoring_rules
    properties:
      identifier:
        $ref: '#/definitions/Identifier'
      name:
        type: string
      section_pool_selection_algorithm:
        type: string
      section_pool_selection_algorithm_parameters:
        type: string
      sections_to_choose:
        type: integer
        description: Number of section selected from the pool
      sections:
        type: array
        items:
          $ref: '#/definitions/SectionPoolSection'
      publication_status:
        $ref: '#/definitions/PublicationStatus'
      scoring_rules:
        type: string

  ############# Asset Definitions ###################

  AssetIdentifier:
    type: object
    required:
      - asset_uuid
    properties:
      asset_uuid:
        description:  The UUID of the asset
        type: string
        pattern: '^[a-fA-F0-9]{32}$'
      asset_version:
        description:  The version of the asset
        type: integer
  AssetRequestBody:
    type: object
    required:
      - identifier
      - details
      - metadata
    properties:
      identifier:
        description: This is required, but it can be an empty object.
        $ref: '#/definitions/Identifier'
      details:
        description: An object whose properties are defined by the `asset_type` property.
        $ref: '#/definitions/AssetDetails'
      metadata:
        $ref: '#/definitions/Metadata'
  AssetDetails:
    type: object
    description: A polymorphic object that is keyed from the asset_type. All acceptable asset_details definitions are listed in `Models` with a namespace of `AssetDetails`
    required:
      - asset_type
      - asset_details
    discriminator: asset_type
    properties:
      asset_type:
        type: string
        enum:
          - dataset
          - rubric
          - passage
          - hint
          - explanation
          - feedback
          - instruction
          - glossary
          - media_file
          - reference_sheet
          - example_response
      asset_details:
        type: object
        description: An asset details subobject
      subassets:
        type: array
        description: A list of references to subassets the asset contains and the order (sequence) of the subasset
        items:
          $ref: '#/definitions/AssetSubasset'
  AssetSubasset:
    allOf:
      - $ref: '#/definitions/AssetIdentifier'
      - type: object
        properties:
          sequence:
            description: Order in which to present subasset (optional if only 1 asset, otherwise must be unique amongst subassets within asset)
            type: integer
  Asset:
    type: object
    required:
      - identifier
      - asset_type
      - asset_details
      - publication_status
    properties:
      identifier:
        type: object
        $ref: '#/definitions/Identifier'
      asset_type:
        type: string
        enum:
          - dataset
          - rubric
          - passage
          - hint
          - explanation
          - feedback
          - instruction
          - glossary
          - media_file
          - reference_sheet
          - example_response
      asset_details:
        type: object
        description: An asset details subobject
      publication_status:
        $ref: '#/definitions/PublicationStatus'

  ############# Misc Definitions ###################

  Identifier:
    type: object
    properties:
      source_urn:
        type: string
        readOnly: true
      _type:
        type: string
        readOnly: true
        enum:
          - assessment
          - asset
          - form
          - section
          - item
          - bank
          - item_pool
          - section_pool
      _uuid:
        pattern: '^[a-fA-F0-9]{32}$'
        type: string
      _version:
        type: integer
  Extensions:
    type: object
    description:
      Extensions are key-value pairs where keys are the names of the extensions
      and values can be an object with at least one property
      or an array with at least one item.
    additionalProperties:
      type: object
      minProperties: 1
  Policy:
    type: object
    description: Reference to policy for entity
    required:
      - policy_uuid
    properties:
      policy_uuid:
        type: string
        pattern: '^[a-fA-F0-9]{32}$'
      policy_version:
        type: string
  Error:
    type: object
    required:
      - code
      - message
      - fields
    properties:
      code:
        type: integer
        format: int32
      message:
        type: string
      fields:
        type: string
  PublicationStatus:
    type: string
    description: Status of entity
    enum:
      - published
      - not_published
      - active
      - archived
  ScoringRules:
    type: string
    description: Base-64 encoded JSON string of scoring rules for entity
  StatusModification:
    type: object
    required:
      - publication_status
    properties:
      publication_status:
        $ref: '#/definitions/PublicationStatus'
      version:
        type: integer
        description: Version of entity to change. Modifies max version if not provided.
  Metadata:
    type: object
    description: Metadata is stil being fleshed out. An empty object is required in requests.
  Filter:
    type: object
    required:
      - filterQuery
    properties:
      filterQuery:
        type: string
        description: The filter query to pass into Bento. See more documentation at http://bentoservices.mheducation.com/services/search-api/