swagger.yaml

# Copyright 2017, tranSMART Foundation, Inc.

swagger: '2.0'

info:
  version: 2.2-dev
  title: Transmart
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  description: |
    
    # OAuth2
    All calls need an Authorization header. https://wiki.transmartfoundation.org/display/transmartwiki/RESTful+API
    ```
    Authorization:Bearer {token}
    ```
    
    # Constraints
    Constraints are used to build queries and are required in the `v2` API. They consist of a `Type` and that type's specific arguments. The implementation is in [Constraint.groovy](../transmart-core-db/src/main/groovy/org/transmartproject/db/multidimquery/query/Constraint.groovy).

    ## Combinations (And/Or)
    Most often a combination of constraints is needed to get the right result. This can be done by the constraints with type "and" and "or".
    They take a list `args` with constraints. All args will be evaluated together on each observation. So an 'and' operator with a `patient_set` and a `concept` will return all observations for the given concept linked to the patient set.
    However an `and` constraint with two ConceptConstraints will evaluate to an empty result, as no observation can have two concepts. This is also true even if nested with a different combination because constraints do not know scope.
    (There is also a constraint with type "combination" on which the And and Or constraints are built. It does not provide any functionality not provided by And and Or constraints, and it should be considered deprecated for direct usage.)
    
    Example:
    ```json
    {"type": "and",
     "args": [
        {"type": "patient_set", "patientIds": -62},
        {"type": "concept", "path":" \\Public Studies\\EHR\\Vital Signs\\Heart Rate\\"}
        ]
    }
    ```

    ```json
    {"type": "or",
     "args": [
        {"type": "concept", "path":" \\Public Studies\\EHR\\Vital Signs\\Blood Pressure\\"}
        {"type": "concept", "path":" \\Public Studies\\EHR\\Vital Signs\\Heart Rate\\"}
        ]
    }
    ```

    ## StudyName
    Evaluate if an observation is part of a particular study
    
    Example:
    ```json
    {
      "type": "study_name",
      "studyId": "EHR"
    }
    ```
    
    ## Concept
    Evaluate if an observation is of a particular Concept. Either by `path` or `conceptCode`.
    
    ```json
    {
      "type": "concept",
      "path": "\\Public Studies\\EHR\\Vital Signs\\Heart Rate\\",
      "conceptCode": "HR"
    }
    ```
    
    ## Value
    Evaluate if the value of an observation is within the given parameters. It needs a `valueType`, `operator` and `value`.
      `valueType`: [\"NUMERIC\", \"STRING\"]
      `operator`: [<, >, =, !=, <=, >=, in, like, contains]
    
    Example:
    ```json
    {
      "type": "value",
      "valueType": "NUMERIC",
      "operator": "=", "value": 176
    }
    ```
    
    ## Field
    Evaluate if a specific field of an observation is within the given parameters. it needs a `field`, `operator` and `value`.
      `operator`: [<, >, =, !=, <=, >=, in, like, contains]
    
    Example:
    ```json
    {
      "type": "field",
      "field": {
          "dimension": "patient",
          "fieldName": "age",
          "type": "NUMERIC"
          },
      "operator": "!=",
      "value": 100
    }
    ```
    
    ## Time
    Evaluate if an observation is within the specified time period. It needs a `field` the type of which needs to be `DATE`. It needs a time relevant `operator` and a list of `values`.
    The list must hold one date for the before(<-) and after(->) operator. It must hold two dates for the between(<-->) operator. If the given date field for an observation is empty, the observation will be ignored.
    `operator`: ["&lt;-", "-&gt;", "&lt;--&gt;"]
    
    Example:
    ```json
    {
      "type": "time",
      "field": {
          "dimension": "start time",
          "fieldName": "startDate",
          "type": "DATE"
          },
      "operator": "->",
      "values": ["2016-01-01T00:00:00Z"]
    }
    ```
    
    ## PatientSet
    Evaluate if an observation is liked to a patient in the set. You have to provide one of three: a `patientSetId`, a list of `patientIds` or a list of `subjectIds`.
    
    Examples:
    By specifying a patient set id.
    ```json
    {
        "type": "patient_set",
        "patientSetId": 28820
    }
    ```
    By specifying a list of patient identifiers.
    ```json
    {
        "type": "patient_set",
        "patientIds": [-62, -63]
    }
    ```
    And by specifying a list of subject identifiers (aka external identifiers).
    ```json
    {
        "type": "patient_set",
        "subjectIds": ["4543AB", "4543AC"]
    }
    ```

    ## SubSelection
    Create a subselection of patients, visits, or another dimension element, and then select all observations for these dimension elements.

    Example: Select all observations for patients who have a certain diagnosis.
    ```json
    {
        "type": "subselection",
        "dimension": "patient",
        "constraint": {
            "type": "and",
            "args": [{
                    "type": "concept",
                    "path": "\\Public Studies\\EHR\\Diagnosis\\",
                    "conceptCode": "DIAG"
                }, {
                    "type": "value",
                    "valueType": "STRING",
                    "operator": "=",
                    "value": "My eye hurts"
                }]
        }
    }
    ```
    
    ## Temporal
    Evaluate if an observation happened before or after an event. It needs an `operator` and an `event`. Any constraint can be used as an event. Most likely a combination.
    `operator`: ["&lt;-", "-&gt;", "exists"]
    
    Example:
    ```json
    {
        "type": "temporal",
        "operator": "exists",
        "event": {
              "type": "value",
              "valueType": "NUMERIC",
              "operator": "=",
              "value": 60
              }
    }
    ```
    
    ## Null
    Evaluate if an specific field of an observation is null. It needs a field.
    
    Example:
    ```json
    {
        "type": "null",
        "field":{
            "dimension": "end time",
            "fieldName": "endDate",
            "type": "DATE"
            }
    }
    ```
    
    ## Modifier
    Evaluate if an observation is linked to the specified modifier. Optionally if that modifier has the specific value. It must have a `path`, `dimensionName` or `modifierCode` and may have `values` in the form of a ValueConstraint.

    Example:
    ```json
    {
        "type": "modifier",
        "modifierCode": "TNS:SMPL",
        "path": "\\Public Studies\\TUMOR_NORMAL_SAMPLES\\Sample Type\\",
        "dimensionName": "sample_type",
        "values": {
            "type": "value",
            "valueType": "STRING",
            "operator": "=",
            "value": "Tumor"
            }
    }
    ```
    
    ## Negation
    Evaluate if for an observation the given `arg` is false. `arg` is a constraint.
    
    Example:
    ```json
    {
        "type": "negation",
        "arg": {
            "type": "patient_set",
            "patientIds": [-62,-52,-42]
            }
    }
    ```
    returns all observations not linked to patient with id -62, -52 or -42
    
    ## Biomarker
    Used to filter high dimensional observations. It needs a 'biomarkerType' and a 'params' object. It can only be used
    when retrieving high dimensional data, and if so needs to be specified in a separate url parameter
    `biomarker_constraint`.
    `biomarkerType`: `["transcripts", "genes"]`.
    
    Example:
    ```json
    {
        "type": "biomarker",
        "biomarkerType": "genes",
        "params": {
            "names": ["TP53"]
            }
    }
    ```
    
    ## True
    **!!WARNING!!** Use mainly for testing.  
    The most basic of constraints. Evaluates to true for all observations. This returns all observations the requesting user has access to.
    
    Example:
    ```json
    {
        "type": "true"
    }
    ```

    ## Relation
    Pedigree relations constraints.
    `relationTypeLabel` is mandatory and specifies code of relation. e.g. PAR (Parent-Child)
    `relatedSubjectsConstraint` is optional and specifies a constraint to apply to the related subjects.
    `biological` is optional field to restrict whether relation biological or not. If not specified, no filtering on this flag applied.
    `shareHousehold` is optional field to restrict whether subjects share the same address or not. If not specified, no filtering on this flag applied.

    Below is example of selecting subjects that are parents (`relationTypeLabel=PAR`) of subjects with ids `-62`, `-52` and `-42`.
    ```json
    {
        "type": "relation",
        "relatedSubjectsConstraint": {
           "type": "patient_set",
           "patientIds": [-62,-52,-42]
        }
        "relationTypeLabel": "PAR",
        "biological": true,
        "shareHousehold": true
    }
    ```
    
    # Response types
    #### application/json
    All calls support json. however this might not always be the best option. You will find schemas for the responses in this documentation.
    
    #### `application/hal+json`
    Only the tree_node endpoint supports the application/hal+json format.
    
    #### `application/x-protobuf`
    Calls that return observations support protobuf as a more efficient binary format. The description of the protobuf object can be found in [observations.proto](../transmart-rest-api/src/protobuf/v2/observations.proto). Information on [google protobuf](https://developers.google.com/protocol-buffers/).

schemes:
  - http
  - https
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  oauth:
    type: oauth2
    flow: implicit
    authorizationUrl: '/oauth/authorize'
    scopes:
      basic: to be able to interact with transmart REST-API

security:
  - oauth:
    - basic
paths:
  /versions:
    get:
      description: |
        Gets all available API versions and prefixes. The API version is separate from the version of transmart itself.

        The API version follows semantic versioning: major versions can be incompatible, but minor version upgrades should be compatible with previous versions within the same major version. Patch versions are not used at the moment. The rest api can support multiple major versions at the same time using different prefixes.

        The default settings expose this endpoint without any authentication requirements, as the version info may be needed to select an authentication method, however clients should be prepared to only be able to see the supported major versions without authentication. In that case the innermost dictionary in the response json will only contain "id", "prefix" and "major" keys.

        Development and preview releases may also contain version tags, e.g. the version leading up to the development of 2.1 can be called 2.1-dev. Such tagged releases also support separate feature revisions. See `transmart-rest-api/grails-app/controllers/org/transmartproject/rest/VersionController.groovy` for details about that.
      responses:
        200:
          description: |
            Successful response. Example:
            `{ "versions": {
                "v2": {
                    "id": "v2",
                    "prefix": "/v2",
                    "version: "2.1",
                    "major": 2,
                    "minor": 1
                }
            } }`'
          schema:
            type: object
            properties:
              versions:
                type: object
                properties:
                  version ids:
                    $ref: "#/definitions/version"

  /versions/{id}:
    get:
      description: |
        Gets information about the version if available. This returns the same information as `/versions`, but only for a single version.
      parameters:
        - name: id
          in: path
          description: |
            id of the version to fetch. Example: `GET /versions/v1`.
          required: true
          type: string
      responses:
        200:
          description: Successful response.
          schema:
            $ref: "#/definitions/version"

        404:
          description: Version not available.
  /v1/studies:
    get:
      description: |
        Gets all `Study` objects.
      tags:
        - v1
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              studies:
                type: array
                items: 
                  $ref: "#/definitions/jsonStudy"
  /v1/studies (hal+json):
    get:
      description: |
        Gets all `Study` objects.
      produces:
        - application/hal+json
      tags:
        - v1
      responses:
        200:
          description: Successful response
          schema:
            $ref: "#/definitions/hal+jsonStudies"
  /v1/studies/{studyid}:
    get:
      description: |
        Gets a `Study` objects.
      tags:
        - v1
      parameters:
        - name: studyid
          in: path
          description: studyid to fetch
          required: true
          type: string
      responses:
        200:
          description: Successful response
          schema:
            $ref: "#/definitions/jsonStudy"
  /v1/studies/{studyid}/concepts:
    get:
      parameters:
        - name: studyid
          in: path
          description: Study ID of the study for which concepts will be fetched
          required: true
          type: string
      description: |
        Gets all `concepts`  for a study.
      tags:
        - v1
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              ontology_terms:
                type: array
                items: 
                  $ref: "#/definitions/ontologyTerm"
  /v1/studies/{studyid}/concepts/{conceptPath}:
    get:
      parameters:
              - name: studyid
                in: path
                description: Study ID of the study for which concepts will be fetched
                required: true
                type: string
              - name: conceptPath
                in: path
                description: Concept path for which info will be fetched
                required: true
                type: string
      description: |
        Gets a `concept` objects.
      tags:
        - v1
      responses:
        200:
          description: Successful response
          schema:
            $ref: "#/definitions/ontologyTerm"
  /v1/studies/{studyid}/subjects:
    get:
      parameters:
              - name: studyid
                in: path
                description: Study ID of the study for which concepts will be fetched
                required: true
                type: string
      description: |
        Gets all `subjects` for a study.
      tags:
        - v1
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              subjects:
                type: array
                items:
                  $ref: '#/definitions/patient'
  /v1/studies/{studyid}/subjects/{subjectid}:
    get:
      parameters:
        - name: studyid
          in: path
          description: Study ID of the study for which concepts will be fetched
          required: true
          type: string
        - name: subjectid
          in: path
          description: Subject ID of the subject which will be fetched
          required: true
          type: string
      description: |
        Gets a `subject` objects.
      tags:
        - v1
      responses:
        200:
          description: Successful response
          schema:
            $ref: '#/definitions/patient'
  /v1/studies/{studyid}/concepts/{conceptPath}/subjects:
    get:
      parameters:
        - name: studyid
          in: path
          description: Study ID of the study for which concepts will be fetched
          required: true
          type: string
        - name: conceptPath
          in: path
          description: Concept path for which info will be fetched
          required: true
          type: string
      description: |
        Gets all `subjects` for a given study and concept.
      tags:
        - v1
      responses:
        200:
          description: Successful response
          schema:
            type: object
            properties:
              subjects:
                type: array
                items:
                  $ref: '#/definitions/patient'
  /v1/studies/{studyid}/observations:
    get:
      parameters:
        - name: studyid
          in: path
          description: Study ID of the study for which concepts will be fetched. 
          required: true
          type: string
      description: |
        Gets all `observations` for a study.
      tags:
        - v1
      responses:
        200:
          description: Successful response
          schema:
            type: array
            items:
              $ref: '#/definitions/v1observation'
  /v1/observations:
    get:
      tags:
        - v1
      responses:
        200:
          description: Successful response
          schema:
            type: array
            items:
              $ref: '#/definitions/v1observation'
  /v1/studies/{studyId}/concepts/{conceptPath}/observations:
    get:
      parameters:
        - name: studyId
          in: path
          description: Study ID of the study for which concepts will be fetched
          required: true
          type: string
        - name: conceptPath
          in: path
          description: Concept path
          required: true
          type: string
      tags:
        - v1
      responses:
        200:
          description: Successful response
          schema:
            type: array
            items:
              $ref: '#/definitions/v1observation'
  /v1/patient_sets/:
    post:
      parameters:
        - name: i2b2query_xml
          in: body
          description: 'Body should be a query definition in a subset of the i2b2 XML schema.'
          required: true
          schema:
            type: string
      tags:
        - v1
      responses:
        201:
          description: Successful response
    get:
      tags:
        - v1
      responses:
        200:
          description: Successfull response
  /v1/patient_sets/{resultInstanceId}:
    get:
      parameters:
        - name: resultInstanceId
          in: path
          description: ID of the patient set, called resultInstance ID because internally it refers to the result of a query
          required: true
          type: string
      tags:
        - v1
      responses:
        200:
          description: Successfull response
  /v1/studies/{studyId}/concepts/{conceptPath}/highdim:
    get:
      parameters:
        - name: studyId
          in: path
          description: Study ID of the study for which concepts will be fetched
          required: true
          type: string
        - name: conceptPath
          in: path
          description: Concept path
          required: true
          type: string
        - name: dataType
          in: query
          description: Data Type constraint
          required: false
          type: string
        - name: projection
          in: query
          description: Projection applied to the HDD
          required: false
          type: string
        - name: assayConstraints
          in: query
          description: Assay Constraints
          required: false
          type: string
        - name: dataConstraints
          in: query
          description: Data constraint
          required: false
          type: string
      tags:
        - v1
      responses:
        200:
          description: Successful response
          
  /v2/studies:
    get:
      description: |
        Gets all studies accessible by the user.
      tags:
        - v2
      produces:
        - application/json
      responses:
        200:
          description: |
            Returns a list of studies
          schema:
            type: object
            properties:
              studies:
                type: array
                items:
                  $ref: '#/definitions/v2Study'
  /v2/studies/{id}:
    get:
      description: |
        Gets the study with id `id`.
      tags:
        - v2
      parameters:
        - name: id
          in: path
          description: id of the study to fetch
          required: true
          type: string
      responses:
        200:
          description: |
            Returns one study
          schema:
            $ref: "#/definitions/v2Study"
        404:
          description: |
            Study not found or no access
  /v2/studies/studyId/{studyId}:
    get:
      description: |
        Gets the study with study id `studyId`.
      tags:
        - v2
      parameters:
        - name: studyId
          in: path
          description: the study id of the study to fetch
          required: true
          type: string
      responses:
        200:
          description: |
            Returns one study
          schema:
            $ref: "#/definitions/v2Study"
        404:
          description: |
            Study not found or no access
  /v2/studies/studyIds:
    get:
      description: |
        Gets the studies with study ids `studyIds`.
      tags:
        - v2
      parameters:
        - name: studyIds
          in: query
          description: 'Json list of strings, with each string being a study name. Example: `/v2/studies/studyIds?studyIds=["GSE8581", "EHR"]`'
          required: true
          type: string
      responses:
        200:
          description: |
            Returns a list of studies
          schema:
            type: object
            properties:
              studies:
                type: array
                items:
                  $ref: '#/definitions/v2Study'
        404:
          description: |
            Study not found or no access
  /v2/supported_fields:
    get:
      description: |
        Gets all supported dimension fields. These are the fields that can be used in field constraints.
      tags:
        - v2
      responses:
        200:
          description: |
            Returns a list of supported fields
          schema:
            type: array
            items:
              type: object
              properties:
                dimension:
                  type: string
                fieldName:
                  type: string
                type:
                  type: string
  /v2/observations:
    get:
      description: |
        Gets all observations that satisfy the given constaint. Only observations the calling user has access to are returned. Empty and null values are returned but have no value property
      tags:
        - v2
      produces:
        - application/json
        - application/x-protobuf
      parameters:
        - name: type
          required: true
          in: query
          description: 'specifies the type of the data you want to retrieve. For clinical data specify `clinical`,
          for high dimensional data specify the data type or use `autodetect`. If you use `autodetect` the
          constraints must be such that only a single type of high dimensional data matches.'
          type: string
        - name: constraint
          required: true
          in: query
          description: 'json that specifies the constraint. Example: `{"type":"study_name", "studyId":"EHR"}` or
          `{"type":"concept","path":"\\Public Studies\\CLINICAL_TRIAL_HIGHDIM\\High Dimensional data\\Expression Lung\\"}`.'
          type: string
        - name: sort
          required: false
          in: query
          type: string
          description: >
              json string that specifies the sort order of the observations. Sorting can be done on multiple
              dimensions. `["patient"]` sorts the observations on the patient dimension, `["patient", "concept"]`
              sorts the observations first on the patient, and then on concept. The sort order is on the 'key'
              field of the chosen dimension, sorting on arbitrary fields is not yet supported. For patients, this is
              the `id`, for concepts the `conceptCode`.

              It is also possible to specify the sort order to be ascending or descending. Use `[['patient', 'asc'],
              ['concept', 'desc']]` for that to sort the observations on patients first, ascending, and then on
              concepts descending.

              When requesting modifier dimensions, the supported sortings is very limited due to implementation
              constraints. Sorting support is limited to those dimensions that make up the primary key columns in the
              `i2b2demodata.observation_fact` table, and a few other supported dimensions. If you request a sort
              order that is not supported you will receive an HTTP 400 Bad Request error code.
        - name: biomarker_constraint
          required: false
          in: query
          description: 'json that describes the biomarker. The only valid type is the ''biomarker'' constraint Example:
          `{"type":"biomarker", "biomarkerType":"genes","params":{"names":["TP53"]}}`.'
          type: string
        - name: projection
          required: false
          in: query
          description: 'The projection. Only used with high dimensional data Example: `all_data`, `zscore`,
          `log_intensity`. Default: `all_data`.'
          type: string
      responses:
        200:
          description: |
            Dimensions are described in the `header`. The order in which they appear in the header, determines the order in which they appear in the `cells` and footer. The value in the `dimensionIndexes` corresponds to the values in the `footer`.
          schema:
            $ref: '#/definitions/observations'
    post:
          description: |
            Works the same as GET, but with support for longer constraints. Use this, if the total length of the URL may be longer than the maximum length.
          tags:
            - v2
          consumes:
            - application/json
          produces:
            - application/json
            - application/x-protobuf
          parameters:
            - name: body
              required: true
              in: body
              description: The parameters
              schema:
                type: object
                properties:
                  type:
                    type: string
                    description: see GET parameters
                  constraint:
                    type: string
                    description: see GET parameters
                  biomarker_constraint:
                    type: string
                    description: see GET parameters
                  projection:
                    type: string
                    description: see GET parameters
                  sort:
                    type: string
                    description: see GET parameters
                required: [ "type", "constraint" ]
          responses:
            200:
              description: |
                Dimensions are described in the `header`. The order in which they appear in the header, determines the order in which they appear in the `cells` and footer. The value in the `dimensionIndexes` corresponds to the values in the `footer`.
              schema:
                $ref: '#/definitions/observations'
  /v2/observations/aggregates_per_concept:
    get:
      description: |
        Calculates and returns an aggregates for both types of concepts, categorical and numerical.
      tags:
        - v2
      parameters:
        - name: constraint
          required: true
          in: query
          description: 'json that specifies the constraint. Example: `{"type":"concept","path":"\\Public Studies\\EHR\\Vital Signs\\Heart Rate\\"}`.'
          type: string
      responses:
        200:
          description: 'return the result in a json object. Example: `{min: 56}`.'
          schema:
            type: object
            properties:
              aggregatesPerConcept:
                $ref: '#/definitions/AggregatesMap'
    post:
      description: |
        Works the same as GET, but with support for longer constraints. Use this, if the total length of the URL may be longer than the maximum length.
      tags:
        - v2
      consumes:
        - application/json
      parameters:
        - name: body
          in: body
          schema:
            type: object
            properties:
              constraint:
                type: string
                description: see GET parameters
            required: [ "constraint" ]
      responses:
        200:
          description: 'return the result in a json object. Example: `{"aggregatesPerConcept": "GENDER": { "categoricalValueAggregatesPerConcept": { "valueCounts": { "Female": 323, "Male": 312} } }}`.'
          schema:
            type: object
            properties:
              aggregatesPerConcept:
                $ref: '#/definitions/AggregatesMap'
  /v2/observations/counts:
    get:
      description: |
        Counts the number of observations that satisfy the given constraint and the number of associated patients.
      tags:
        - v2
      parameters:
        - name: constraint
          required: true
          in: query
          description: 'json that specifies the constraint. Example: `{"type":"concept","path":"\\Public Studies\\EHR\\Vital Signs\\Heart Rate\\"}`.'
          type: string
      responses:
        200:
          description: 'Return the result as a json object. Example: `{observationCount: 56, patientCount: 12}`.'
          schema:
            $ref: '#/definitions/Counts'
    post:
          description: |
            Works the same as GET, but with support for longer constraints. Use this, if the total length of the URL may be longer than the maximum length.
          tags:
            - v2
          consumes:
            - application/json
          parameters:
            - name: body
              required: true
              in: body
              schema:
                type: object
                properties:
                  constraint:
                    type: string
                    description: see GET parameters
                required: [ "constraint" ]
          responses:
            200:
              description: 'Return the result as a json object. Example: `{observationCount: 56, patientCount: 12}`.'
              schema:
                $ref: '#/definitions/Counts'
  /v2/observations/counts_per_study:
    get:
      description: |
        Counts the number of observations and patients that satisfy the given constraint and groups them by study.
      tags:
        - v2
      parameters:
        - name: constraint
          required: true
          in: query
          description: 'json that specifies the constraint. Example: `{"type":"concept","path":"\\Vital Signs\\Heart Rate\\"}`.'
          type: string
      responses:
        200:
          description: 'The result as a json object with a map from study id to counts. Example: `{countsPerStudy: {SHARED_A: 2, SHARED_B: 3}}`.'
          schema:
            type: object
            properties:
              countsPerStudy:
                $ref: '#/definitions/CountsMap'
    post:
      description: |
        Works the same as GET, but with support for longer constraints. Use this, if the total length of the URL may be longer than the maximum length.
      tags:
        - v2
      consumes:
        - application/json
      parameters:
        - name: body
          required: true
          in: body
          schema:
            type: object
            properties:
              constraint:
                type: string
                description: see GET parameters
            required: [ "constraint" ]
      responses:
        200:
          description: 'The result as a json object with a map from study id to counts. Example: `{countsPerStudy: {SHARED_A: 2, SHARED_B: 3}}`.'
          schema:
            type: object
            properties:
              countsPerStudy:
                $ref: '#/definitions/CountsMap'

  /v2/observations/counts_per_concept:
    get:
      description: |
        Counts the number of observations and patients that satisfy the given constraint and groups them by concept.
      tags:
        - v2
      parameters:
        - name: constraint
          required: true
          in: query
          description: 'json that specifies the constraint. Example: `{"type":"concept","path":"\\Vital Signs\\Heart Rate\\"}`.'
          type: string
      responses:
        200:
          description: 'The result as a json object with a map from concept code to counts. Example: `{countsPerConcept: {"DEM:AGE": 2, "HR": 3}}`.'
          schema:
            type: object
            properties:
              countsPerConcept:
                $ref: '#/definitions/CountsMap'
    post:
      description: |
        Works the same as GET, but with support for longer constraints. Use this, if the total length of the URL may be longer than the maximum length.
      tags:
        - v2
      consumes:
        - application/json
      parameters:
        - name: body
          required: true
          in: body
          schema:
            type: object
            properties:
              constraint:
                type: string
                description: see GET parameters
            required: [ "constraint" ]
      responses:
        200:
          description: 'The result as a json object with a map from concept code to counts. Example: `{countsPerConcept: {"DEM:AGE": 2, "HR": 3}}`.'
          schema:
            type: object
            properties:
              countsPerConcept:
                $ref: '#/definitions/CountsMap'

  /v2/observations/counts_per_study_and_concept:
    get:
      description: |
        Counts the number of observations and patients that satisfy the given constraint and groups them by study and concept.
      tags:
        - v2
      parameters:
        - name: constraint
          required: true
          in: query
          description: 'json that specifies the constraint. Example: `{"type":"concept","path":"\\Vital Signs\\Heart Rate\\"}`.'
          type: string
      responses:
        200:
          description: |
            The result as a json object with a map from study id to a map from concept code to counts.
            Example: `{countsPerStudy: {"SHARED_A": {"DEM:AGE": 2, "HR": 3}, "SHARED_B": {"DEM:AGE": 1}}}`.
          schema:
            type: object
            properties:
              countsPerStudy:
                $ref: '#/definitions/CountsMapMap'
    post:
      description: |
        Works the same as GET, but with support for longer constraints. Use this, if the total length of the URL may be longer than the maximum length.
      tags:
        - v2
      consumes:
        - application/json
      parameters:
        - name: body
          required: true
          in: body
          schema:
            type: object
            properties:
              constraint:
                type: string
                description: see GET parameters
            required: [ "constraint" ]
      responses:
        200:
          description: |
            The result as a json object with a map from study id to a map from concept code to counts.
            Example: `{countsPerStudy: {"SHARED_A": {"DEM:AGE": 2, "HR": 3}, "SHARED_B": {"DEM:AGE": 1}}}`.
          schema:
            type: object
            properties:
              countsPerStudy:
                $ref: '#/definitions/CountsMapMap'

  /v2/observations/table:
    get:
      description: |
        Returns a tabular view of observations, as a table using specified dimensions for rows and columns
      tags:
        - v2
      parameters:
        - name: type
          required: true
          in: query
          type: string
          description: |
            The type of data to retrieve. At the moment only 'clinical' is supported. High dimensional
            data is not supported.
        - name: constraint
          required: true
          in: query
          type: string
          description: |
            JSON-encoded constraint specification. Example: `{"type":"concept","path":"\\Public Studies\\EHR\\Vital
            Signs\\Heart Rate\\"}`.
        - name: rowDimensions
          required: true
          in: query
          type: string
          description: |
            Json list of strings, with each string being a dimension name. This specifies the dimensions
            that form the vertical axis of the table (in order). Example: `['study', 'patient']`
        - name: columnDimensions
          required: true
          in: query
          type: string
          description: The same as `rowDimensions`, but with the dimensions that specify the horizontal axis of the table
        - name: rowSort
          required: false
          in: query
          type: string
          description: |
            Json list of sort specifications for the row dimensions. A sort specification is
            an element `{dimension: <dimension>, sortOrder: <direction>}` where `<dimension>` is the name of a
            dimension and `<direction>` is either `'asc'` or `'desc'`. The dimension must be a dimension that is
            part of the `rowDimensions` parameter. This defaults to the order specified in `rowDimensions`.
            Example: `[{dimension: 'study', sortOrder: 'desc'}, {dimension: 'patient', sortOrder:'asc'}]`
        - name: columnSort
          required: false
          in: query
          type: string
          description: Analogous to `rowSort`, but for the column dimensions.
        - name: limit
          required: true
          in: query
          type: integer
          description: The maximum number of rows to return. This determines the size of the result.
        - name: offset
          required: false
          in: query
          type: integer
          description: |
            The number of rows to skip before the first returned row. If the dataset does not contain at least
            limit+offset number of rows, the returned result will contain the `limit` last rows of the dataset. (The
            result also includes the actual offset of the returned rows.)
      responses:
        200:
          $ref: '#/definitions/DataTable'
    post:
      description: |
        The same as the `get` call, but with parameters specified as a JSON object in the request body. Useful if the
        parameters don't fit in a single request. 
        
        See the `get` version for additional documentation.
      tags:
        - v2
      parameters:
        - name: type
          required: true
          in: body
          type: string
        - name: constraint
          required: true
          in: body
          type: string
        - name: rowDimensions
          required: true
          in: body
          type: string
        - name: columnDimensions
          required: true
          in: body
          type: string
        - name: rowSort
          required: false
          in: body
          type: string
        - name: columnSort
          required: false
          in: body
          type: string
        - name: limit
          required: true
          in: body
          type: integer
        - name: offset
          required: false
          in: body
          type: integer
      responses:
        200:
          $ref: '#/definitions/DataTable'
  /v2/observations/crosstable:
    get:
      description: |
        Returns a tabular view of subject counts, using specified constraints for rows and columns.
        Each cell represents a number of subjects computed as an intersection of column set, row set
        and selected subject set that is specified by subject constraint.
      tags:
        - v2
      parameters:
        - name: rowConstraints
          required: true
          in: query
          type: array
          description: |
            List of JSON-encoded constraint specifications. Each constraint is a row header and specifies a row set
            part of the final set computed for a cell.
            Example: `[{"type":"concept","path":"\\Public Studies\\EHR\\Vital Signs\\Heart Rate\\"},
            {"type":"concept","conceptCode":"height"}]`.
          items:
            type: string
        - name: columnConstraints
          required: true
          in: query
          type: array
          items:
            type: string
        - name: subjectConstraint
          required: true
          in: query
          type: string
          description: |
            Json that specifies the constraint for a subject set. In particular, subjectConstraint can be
            of type `patient_set` in order to explicitly specify the id of a set of patients.
            Example: `{“type”:“patient_set”, “patientSetId”: 12345}`.
      responses:
        200:
          $ref: '#/definitions/CrossTable'
    post:
      description: |
        The same as the `get` call, but with parameters specified as a JSON object in the request body. Useful if the
        parameters don't fit in a single request.

        See the `get` version for additional documentation.
      tags:
        - v2
      parameters:
        - name: rowConstraints
          required: true
          in: body
          type: array
          items:
            type: string
        - name: columnConstraints
          required: true
          in: body
          type: array
          items:
            type: string
        - name: subjectConstraint
          required: true
          in: query
          type: string
      responses:
        200:
          $ref: '#/definitions/CrossTable'

    
  /v2/patients:
    get:
      description: |
        Gets all patients that have an observation that satisfy the given constaint. Only patients that the calling user has access to are returned.
      tags:
        - v2
      parameters:
        - name: constraint
          required: true
          in: query
          description: 'json that specifies the constraint. Example: `{"type":"study_name","studyId":"EHR"}`.'
          type: string
      responses:
        200:
          description: OK
          schema:
            type: object
            properties:
              patients:
                type: array
                items:
                  $ref: '#/definitions/patient'
    post:
          description: |
            Works the same as GET, but with support for longer constraints. Use this, if the total length of the URL may be longer than the maximum length.
          tags:
            - v2
          consumes:
            - application/json
          parameters:
            - name: body
              required: true
              in: body
              schema:
                type: object
                properties:
                  constraint:
                    type: string
                    description: see GET parameters
                required: [ "constraint" ]
          responses:
            200:
              description: OK
              schema:
                type: object
                properties:
                  patients:
                    type: array
                    items:
                      $ref: '#/definitions/patient'
  /v2/patients/{id}:
    get:
      description: |
        Gets one patient object.
      tags:
        - v2
      parameters:
        - name: id
          in: path
          description: id to fetch
          required: true
          type: string
      responses:
        200:
          description: |
            Returns one patient
          schema:
            $ref: '#/definitions/patient'
  /v2/patient_sets:
    get:
      tags:
        - v2
      responses:
        200:
          description: |
            Gets all patient_sets accessible by the user.
          schema:
            $ref: '#/definitions/patient_set'
    post:
      description: |
        creates a patient set with all patients that have an observation that satisfies the constaint given in the body. The set will only have patients the calling user access to. The constraint used to create the set will be stored in a database.
      tags:
        - v2
      parameters:
        - name: name
          required: true
          in: query
          type: string
        - name: constraint
          description: 'json that specifies the constraint. Example: `{"type":"study_name","studyId":"EHR"}`.'
          in: body
          required: true
          schema:
            type: string
      responses:
        200:
          description: |
            an object with the created patient_set or error.
          schema:
            $ref: '#/definitions/patient_set'
  /v2/patient_sets/{resultInstanceId}:
    get:
      parameters:
        - name: resultInstanceId
          in: path
          description: |
            ID of the patient set, called resultInstance ID because internally it refers to the result of a query
          required: true
          type: string
      tags:
        - v2
      responses:
        200:
          description: |
            Returns one patient_set.
          schema:
            $ref: '#/definitions/patient_set'
  /v2/concepts:
    get:
      description: |
        Gets all concepts the user has access to.
        Similar to `/v2/dimensions/concept/elements` without any constraint.
      tags:
        - v2
      responses:
        200:
          description: |
            Returns the concepts that the user has access to.
          schema:
            type: object
            properties:
              concepts:
                type: array
                items:
                  $ref: '#/definitions/concept'

  /v2/concepts/{conceptCode}:
    get:
      description: |
        Gets the concepts with the provided concept code if it exists and the user has access to it.
      tags:
        - v2
      parameters:
        - name: conceptCode
          required: true
          in: path
          description: 'Concept code of the concept.'
          type: string
      responses:
        200:
          description: |
            Returns the concept if it exists and the user has access to it.
          schema:
            $ref: '#/definitions/concept'
        404:
          description: |
            No concept exists with the concept code, or the user does not have access to the concept.

  /v2/tree_nodes:
    get:
      description: |
        Gets all tree nodes. Number of nodes can be limited by changing the `root` path and max `depth`. `counts` and `tags` are omitted if not requested.
      produces:
        - application/json
        - application/hal+json
      tags:
        - v2
      parameters:
        - name: root
          in: query
          type: string
          description: 'The node the requested tree starts from. Example: `\Public Studies\SHARED_CONCEPTS_STUDY_A\`.'
        - name: depth
          in: query
          type: integer
          description: 'The max node depth returned'
        - name: constraints
          in: query
          type: boolean
          description: 'Flag if the constraints should be included in the result (always false for hal, defaults to true for json)'
        - name: counts
          in: query
          type: boolean
          description: 'Patient and observation counts will be in the response if set to true.'
        - name: tags
          in: query
          type: boolean
          description: 'Metadata tags will be in the response if set to true.'
      responses:
        200:
          description: |
            A forest stucture if there are several root nodes. For example when there are Public Studies, Private Studies and shared concepts.
          schema:
            type: object
            properties:
              tree_nodes:
                type: array
                items:
                  $ref: '#/definitions/treeNode'
  /v2/tree_nodes/clear_cache:
    get:
      description: |
        Clears tree node and counts caches.
        Only for administrators.
      tags:
        - v2
      responses:
        200:
          description: |
            The cache has been cleared.
  /v2/tree_nodes/rebuild_cache:
    get:
      description: |
        Clears tree node and counts caches and rebuilds the tree node cache per user.
        Only for administrators.
      tags:
        - v2
      responses:
        200:
          description: |
            Clearing and rebuilding the cache has been started.
        503:
          description: |
            A rebuild operation is already in progress.
  /v2/system/after_data_loading_update:
    get:
      description: |
        This endpoint should be called after loading, deleting or updating data in the database. Clears tree nodes, counts caches, patient sets and bitsets. Updates data for subscribed user queries.
        Only for administrators.
      tags:
        - v2
      responses:
        200:
          description: |
            The cache and patient sets have been cleared. The data for subscribed user queries is updated.
  /v2/storage:
    get:
      description: |
        Gets a list of all storage systems.
      tags:
        - v2
      responses:
        200:
          description: |
            an object that contains an array with all storage systems.
          schema:
            type: object
            properties:
              storageSystems:
                type: array
                items:
                  $ref: '#/definitions/storageSystem'
    post:
      description: |
        Adds a new storage system with the properties provided in the body. Calling user must have `admin` permissions.
      tags:
        - v2
      parameters:
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
              systemType:
                type: string
              url:
                type: string
              systemVersion:
                type: string
              singleFileCollections:
                type: boolean
      responses:
        201:
          description: |
            returns the added storage system object.
          schema:
            $ref: '#/definitions/storageSystem'
  /v2/storage/{id}:
    get:
      description: |
        Gets the storage system with the given `id`
      tags:
        - v2
      parameters:
        - name: id
          in: path
          required: true
          type: integer
      responses:
        200:
          description: |
            returns the storage system object.
          schema:
            $ref: '#/definitions/storageSystem'
    put:
      description: |
        Updates the storage system with given id with the values in the body. Calling user must have `admin` permissions.
      tags:
        - v2
      parameters:
        - name: id
          in: path
          required: true
          type: integer
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
              systemType:
                type: string
              url:
                type: string
              systemVersion:
                type: string
              singleFileCollections:
                type: boolean
      responses:
        200:
          description: |
            returns the updated storage system object.
          schema:
            $ref: '#/definitions/storageSystem'
    delete:
      description: |
        Deletes the storage system with the given id.
      tags:
        - v2
      parameters:
        - name: id
          in: path
          required: true
          type: integer
      responses:
        204:
          description: 'returns null'
  /v2/files:
    get:
      description: |
        Gets a list of all file links.
      tags:
        - v2
      responses:
        200:
          description: |
            an object that contains an array with all file links.
          schema:
            type: object
            properties:
              files:
                type: array
                items:
                  $ref: '#/definitions/fileLink'
    post:
      description: |
        Adds a new file link with the properties provided in the body. Calling user must have `admin` permissions.
      tags:
        - v2
      parameters:
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
              sourceSystem:
                type: integer
              study:
                type: string
              uuid:
                type: string
      responses:
        201:
          description: |
            returns the added file link object.
          schema:
            $ref: '#/definitions/fileLink'
  /v2/files/{id}:
    get:
      description: |
        Gets the file link  with the given `id`.
      tags:
        - v2
      parameters:
        - name: id
          in: path
          required: true
          type: integer
      responses:
        200:
          description: |
            returns the file link object.
          schema:
            $ref: '#/definitions/fileLink'
    put:
      description: |
        Updates the file link  with given id with the values provided in the body. Calling user must have `admin` permissions.
      tags:
        - v2
      parameters:
        - name: id
          in: path
          required: true
          type: integer
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
              sourceSystem:
                type: integer
              study:
                type: string
              uuid:
                type: string
      responses:
        200:
          description: |
            returns the updated file link object.
          schema:
            $ref: '#/definitions/fileLink'
    delete:
      description: |
        Deletes the file link with the given id.
      tags:
        - v2
      parameters:
        - name: id
          in: path
          required: true
          type: integer
      responses:
        204:
          description: 'returns null'
  /v2/studies/{studyId}/files:
    get:
      description: |
        Gets a list of all file links related to a study.
      tags:
        - v2
      parameters:
        - name: studyId
          in: path
          required: true
          type: integer
      responses:
        200:
          description: |
            an object that contains an array with all file links related to a study.
          schema:
            type: object
            properties:
              files:
                type: array
                items:
                  $ref: '#/definitions/fileLink'
  /v2/arvados/workflows:
    get:
      description: |
        Gets a list of all supported workflows.
      tags:
        - v2
        - arvados
      responses:
        200:
          description: |
            an object that contains an array with all supported workflows.
          schema:
            type: object
            properties:
              supportedWorkflows:
                type: array
                items:
                  $ref: '#/definitions/supportedWorkflow'
    post:
      description: |
        Adds a new supported Workflow with the properties provided in the body. Calling user must have `admin` permissions.
      tags:
        - v2
        - arvados
      parameters:
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
              arvadosInstanceUrl:
                type: string
              uuid:
                type: string
              description:
                type: string
              arvadosVersion:
                type: string
              defaultParams:
                description: 'a map of key value pairs'
                type: object
      responses:
        201:
          description: |
            returns the created supported workflow object.
          schema:
            $ref: '#/definitions/supportedWorkflow'
  /v2/arvados/workflows/{id}:
    get:
      description: |
        Gets the supported workflow with the given `id`.
      tags:
        - v2
        - arvados
      parameters:
        - name: id
          in: path
          required: true
          type: integer
      responses:
        200:
          description: |
            returns the supported workflow object.
          schema:
            $ref: '#/definitions/supportedWorkflow'
    put:
      description: |
        Updates the supported workflow with given id with the values in the body. Calling user must have `admin` permissions.
      tags:
        - v2
        - arvados
      parameters:
        - name: id
          in: path
          required: true
          type: integer
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
              arvadosInstanceUrl:
                type: string
              uuid:
                type: string
              description:
                type: string
              arvadosVersion:
                type: string
              defaultParams:
                description: 'a map of key value pairs'
                type: object
      responses:
        200:
          description: |
            returns the modified supported workflow object.
          schema:
            $ref: '#/definitions/supportedWorkflow'
    delete:
      description: |
        Deletes the supported workflow with the given id.
      tags:
        - v2
        - arvados
      parameters:
        - name: id
          in: path
          required: true
          type: integer
      responses:
        204:
          description: 'returns null'
  /v2/dimensions/{dimensionName}/elements:
    get:
      description: |
        Gets all elements from a dimension of given name that satisfy the constaint if given.
      tags:
        - v2
      parameters:
        - name: dimensionName
          in: path
          required: true
          type: string
        - name: constraint
          required: false
          in: query
          description: 'json that specifies the constraint. Example: `{"type":"concept","path":"\\Public Studies\\EHR\\Vital Signs\\Heart Rate\\"}`.'
          type: string
      responses:
        200:
          description: |
            Returns list of all elements from the given dimension that user has access to.
          schema:
            $ref: '#/definitions/dimensionElements'
    post:
      description: |
        Works the same as GET, but with support for longer constraints. Use this, if the total length of the URL may be longer than the maximum length.
      tags:
        - v2
      consumes:
        - application/json
      parameters:
        - name: dimensionName
          in: path
          required: true
          type: string
        - name: constraint
          required: false
          in: body
          description: 'json that specifies the constraint. Example: `{"type":"concept","path":"\\Public Studies\\EHR\\Vital Signs\\Heart Rate\\"}`.'
          type: string
      responses:
        200:
          description: |
            Returns list of all elements from the given dimension that user has access to.
          schema:
            $ref: '#/definitions/dimensionElements'
  /v2/export/job:
    post:
      description: |
        Creates a new asynchronous data export job.
      tags:
        - v2
      parameters:
        - name: name
          required: false
          in: query
          description: '(optional) name of the export job (has to be unique for the user). If it is not specified, a default name will be created.'
          type: string
      responses:
        200:
          description:  |
            an object with the created export job or error.
          schema:
            $ref: '#/definitions/export_job'
  /v2/export/{jobId}/run:
    post:
      description: |
        Runs the specified data export job asynchronously. Creates a hypercube for each element from {elements} with PatientSetsConstraint for given `id`
        and serialises it to specified `fileFormat`. Output stream is saved on the server as .zip file.
      tags:
        - v2
      parameters:
        - name: jobId
          required: true
          in: path
          description: 'id of the export job. The job has to have a status `Created`.'
          type: string
        - name: body
          required: true
          in: body
          description: 'contains json object to initialize export job.'
          schema:
            type: object
            properties:
              id:
                type: array
                description: 'result instance ids. To specify more than one value, multiple parameter
                instances format is required instead of multiple values for a single instance. Example: `id=3425&id=98532&id=...`.'
                items:
                  type: integer
              constraint:
                type: string
                description: 'observations that meet this constraint get exported. Note: whether id or constraint has to be supplied, not both. Example: `constraint={"type": "study_name", "studyId": "EHR"}`.'
              includeMeasurementDateColumns:
                type: boolean
                description: 'Flag specifies whether to include measurement date columns.'
              elements:
                type: string
                description: |
                    json that specifies the list of pairs: `[{dataType:${dataType}, format:${fileFormat}, dataView:${dataView}]`,
                    where `dataType` is a type of the data you want to retrieve, either `clinical` for clinical data,
                    or one of the supported high dimensional data types and `format` is one of the supported file formats
                    you want to export current data type to. The tabular flag (optional, false by default) specifies whether
                    represent hypercube data as wide filer format where patients are rows and columns are variables.
                    Example: `[{"dataType":clinical, "format":TSV, "tabular":true},{"dataType":rnaseq_transcript, "format":TSV}]`.

                    `dataView` is optional, it can be `"surveyTable"` or `"dataTable"`, resulting in either a survey
                    table or a data table export. When not set the export will default to a plain hypercube export.
              tableConfig:
                type: string
                description: |
                    `tableConfig` is only used for data table exports. It must be a JSON map containing the
                    keys `rowDimensions`, `columnDimensions`, `rowSort` and `columnSort`, with
                    the same meanings and optionality as in the `/v2/observations/table` call.
            required: [ "id", "elements" ]
      responses:
        200:
          description:  |
            an object with the run export job with status 'Started' or 'Error'.
          schema:
            $ref: '#/definitions/export_job'
  /v2/export/{jobId}/download:
    get:
      description: |
        Gets zipped file with exported data, created by specified job.
      tags:
        - v2
      parameters:
        - name: jobId
          required: true
          in: path
          description: 'id of the export job. The job has to have a status `Completed`.'
          type: string
      responses:
        200:
          description:  |
            Zip file stream with expoted data.
          schema:
            type: file
  /v2/export/{jobId}/status:
    get:
      description: |
        Gets a status of specified data export job. Deprecated. Use /v2/export/{jobId} instead.
      tags:
        - v2
      parameters:
        - name: jobId
          required: true
          in: path
          description: 'Id of the export job.'
          type: string
      responses:
        200:
          description: |
            an object with the export job, including its status.
          schema:
            $ref: '#/definitions/export_job'
  /v2/export/{jobId}:
      get:
        description: |
          Gets an export job.
        tags:
          - v2
        parameters:
          - name: jobId
            required: true
            in: path
            description: 'Id of the export job.'
            type: string
        responses:
          200:
            description: |
              an object with the export job.
            schema:
              $ref: '#/definitions/export_job'
      delete:
        description: |
          Deletes an export job.
        tags:
          - v2
        parameters:
          - name: jobId
            required: true
            in: path
            description: 'Id of the export job.'
            type: string
        responses:
          200:
            description: |
              200 http status when job has been deleted.
  /v2/export/{jobId}/cancel:
    post:
      description: |
        Cancels an export job.
      tags:
        - v2
      parameters:
        - name: jobId
          required: true
          in: path
          description: 'Id of the export job.'
          type: string
      responses:
        200:
          description: |
            200 http status when job has been cancelled.
  /v2/export/jobs:
    get:
      description: |
        Gets all export jobs accessible by the user.
      tags:
        - v2
      produces:
        - application/json
      responses:
        200:
          description: |
            Returns a list of export jobs
          schema:
            type: array
            items:
              $ref: '#/definitions/export_job'
  /v2/export/data_formats:
    post:
      description: |
        Analyses the constraint and gets result data formats, including `clinical` type and high dimensional types.
      tags:
        - v2
      parameters:
        - name: constraint
          required: true
          in: body
          description: 'json that specifies the constraint. Example: `{"type":"study_name","studyId":"EHR"}`.'
          type: object
      responses:
        200:
          description:  |
            Returns a list of known data formats for specified sets.
            Example: `{ "dataFormats": ["clinical", "mrna", "rnaseq_transcript"] }`
          schema:
            type: object
            properties:
              dataFormats:
                type: array
                items:
                  type: string
  /v2/export/file_formats:
    get:
      description: |
        Gets supported export file formats.
      tags:
        - v2
      parameters:
        - name: dataView
          required: false
          in: query
          description: 'Data view.'
          type: string
      produces:
        - application/json
      responses:
        200:
          description: |
            Returns a list of file formats that data can be exported to. Example: `{ "fileFormats": ["TSV"] }`
          schema:
            type: object
            properties:
              supportedFileFormats:
                type: array
                items:
                  type: string

  /v2/queries:
      get:
        description: |
          Gets a list of all queries for current user.
        tags:
          - v2
        responses:
          200:
            description: |
              an object that contains an array with all queries for current user.
            schema:
              type: object
              properties:
                queries:
                  type: array
                  items:
                    $ref: '#/definitions/userQuery'
      post:
        description: |
          Adds a new user query with the properties provided in the body.
        tags:
          - v2
        parameters:
          - name: body
            in: body
            required: true
            schema:
              type: object
              properties:
                name:
                  type: string
                patientsQuery:
                  type: object
                observationsQuery:
                  type: object
                bookmarked:
                  type: boolean
                subscribed:
                  type: boolean
                subscriptionFreq:
                  type: string
                queryBlob:
                  type: object
        responses:
          201:
            description: |
              returns the added user query object.
            schema:
              $ref: '#/definitions/userQuery'
  /v2/queries/{id}:
    get:
      description: |
        Gets the user query with the given `id`
      tags:
        - v2
      parameters:
        - name: id
          in: path
          required: true
          type: integer
      responses:
        200:
          description: |
            returns the user query object.
          schema:
            $ref: '#/definitions/userQuery'
    put:
      description: |
        Updates the user query with given id with the values in the body.
      tags:
        - v2
      parameters:
        - name: id
          in: path
          required: true
          type: integer
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              name:
                type: string
              bookmarked:
                type: boolean
              subscribed:
                type: boolean
              subscriptionFreq:
                type: string
      responses:
        204:
          description: 'replies with the 204 http status if the update finished successfully.'
    delete:
      description: |
        Deletes the user query with the given id.
      tags:
        - v2
      parameters:
        - name: id
          in: path
          required: true
          type: integer
      responses:
        204:
          description: 'returns null'
  /v2/pedigree/relation_types:
    get:
      description: |
        Gets the list of the relation types.
      tags:
        - v2
      responses:
        200:
          description: |
            returns the list of the relation types.
          schema:
            type: array
            items:
              $ref: '#/definitions/relation_type'
  /v2/queries/{queryId}/sets:
      get:
        description: |
          Gets a list of query result change entries by query id.
          History of data changes for specific query.
        tags:
          - v2
        parameters:
          - name: queryId
            required: true
            in: path
            description: 'Id of a user query.'
            type: integer
        responses:
          200:
            description: |
              an object that contains an array of all querySets related to the query with a set change history.
            schema:
              type: object
              properties:
                querySets:
                  type: array
                  items:
                    $ref: '#/definitions/userQuerySet'
  /v2/queries/sets/scan:
      post:
        description: |
          Scans for changes in results of the stored user queries and updates stored sets.
          Only for administrators.
        tags:
          - v2
        responses:
          201:
            description: Successful response
            schema:
              type: object
              properties:
                numberOfUpdatedSets:
                  type: integer

definitions:
  version:
    type: object
    properties:
      id: { type: string }
      prefix: { type: string, description: the url prefix where this api can be found }
      version: { type: string, description: the full version string }
      major: { type: integer }
      minor: { type: integer }
      patch: { type: integer }
      tag: { type: string }
      features:
        type: object
        properties:
          features:
            type: integer
            description: string keys and numeric values that indicate features and their revision level. These are only present for -dev versions.
    required: [ "id", "prefix", "major" ]

  v1observation:
    type: object
    properties:
      subject:
        $ref: '#/definitions/patient'
      label:
        type: string
      value:
        type: string

  ontologyTerm:
    type: object
    properties:
      name:
        type: string
      key:
        type: string
      fullName:
        type: string
      type:
        type: string

  jsonStudy:
    type: object
    properties:
      id:
        type: string
      ontologyTerm:
        type: object
        properties:
          name:
            type: string
          key:
            type: string
          fullName:
            type: string
          type:
            type: string

  hal+jsonStudy:
    type: object
    properties:
      id:
        type: string
      _links:
        type: object
        properties:
          self:
            type: object
            properties:
              href:
                type: string
      _embedded:
        type: object
        properties:
          ontologyTerm:
            type: object
            properties:
              name:
                type: string
              key:
                type: string
              fullName:
                type: string
              type:
                type: string
                default: 'STUDY'
              _links:
                type: object
                properties:
                  self:
                    type: object
                    properties:
                      href:
                        type: string
                  observations:
                    type: object
                    properties:
                      href:
                        type: string
                  children:
                    type: array
                    items:
                      type: object
                      properties:
                        href:
                          type: string
                        title:
                          type: string

  hal+jsonStudies:
    type: object
    properties:
      _links:
        type: object
        properties:
          self:
            type: object
            properties:
              href:
                type: string
      _embedded:
        type: object
        properties:
          studies:
            type: array
            items:
              $ref: '#/definitions/hal+jsonStudy'
              
  storageSystem:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      systemType:
        type: string
      url:
        type: string
      systemVersion:
        type: string
      singleFileCollections:
        type: boolean
  
  fileLink:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      sourceSystem:
        description: 'sourceSystem field is an integer ID representing #storage_system from `/v2/storage`'
        type: integer
      study:
        description: 'Short case insensitive String identifying tranSMART study, usually study name, given during ETL, can be retrieved by `/v2/studies`.'
        type: string
      uuid:
        type: string
  
  supportedWorkflow:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      arvadosInstanceUrl:
        type: string
      uuid:
        type: string
      description:
        type: string
      arvadosVersion:
        type: string
      defaultParams:
        description: 'a map of key value pairs'
        type: object
  
  treeNode:
    type: object
    properties:
      children:
        type: array
        description: 'A list of treeNodes if there are any children. '
        items:
          type: object
      fullName:
        type: string
        description: 'Example: `\Public Studies\SHARED_CONCEPTS_STUDY_A\`'
      name:
        type: string
        description: 'Example: SHARED_CONCEPTS_STUDY_A'
      type:
        description: 'Example: STUDY'
        type: string
      visualAttributes:
        type: array
        items:
          description: 'Example: [FOLDER, ACTIVE, STUDY]'
          type: string
      observationCount:
        description: 'only available on concept nodes'
        type: integer
      patientCount:
        description: 'only available on concept nodes'
        type: integer
      constraint:
        description: 'only available on concept nodes; not available for HAL.'
        type: object
        properties:
          type:
            description: 'Example: `concept`'
            type: string
          conceptCode:
            description: 'Example: `age`'
            type: string
  
  v2Study:
    type: object
    properties:
      id:
        type: integer
      studyID:
        type: string
      bioExperimentId:
        type: integer
      dimensions:
        type: array
        items:
          type: string
      metadata:
        $ref: '#/definitions/StudyMetadata'

  StudyMetadata:
    type: object
    properties:
      conceptToVariableName:
        description: 'a map from concept code to variable name in the study.'
        type: object
        properties:
          '<conceptCode>':
            type: string
        additionalProperties:
          type: string


  patient:
    type: object
    properties:
      age:
        type: integer
      birthDate:
        type: string
        format: date
      deathDate:
        type: string
        format: date
      id:
        type: integer
      inTrialId:
        type: integer
      maritalStatus:
        type: string
      race:
        type: string
      religion:
        type: string
      sex:
        type: string
      trial:
        type: string
  
  patient_set:
    type: object
    properties:
      description:
        type: string
      errorMessage:
        type: string
      id:
        type: integer
      setSize:
        type: integer
      status:
        type: string
      username:
        type: string
      requestConstraints:
        type: string
      apiVersion:
        type: string  

  concept:
    type: object
    properties:
      conceptCode:
        type: string
      conceptPath:
        type: string
      name:
        type: string
      metadata:
        $ref: '#/definitions/VariableMetadata'

  VariableMetadata:
    type: object
    properties:
      type:
        description: NUMERIC, DATE, STRING
        type: string
      measure:
        description: NOMINAL, ORDINAL, SCALE
        type: string
      description:
        type: string
      width:
        type: integer
      decimals:
        type: integer
      columns:
        type: integer
      valueLabels:
        description: a map from value (of type integer) to label (of type string)
        type: object
        properties:
          '<value>':
            type: string
        additionalProperties:
          type: string
      missingValues:
        type: array
        items:
          type: integer

  Counts:
    type: object
    properties:
      observationCount:
        type: integer
      patientCount:
        type: integer

  CountsMap:
    description: a map from string to Counts.
    properties:
      '<key>':
        $ref: '#/definitions/Counts'
    additionalProperties:
      $ref: '#/definitions/Counts'

  CountsMapMap:
    description: a map from string to a map from string to Counts.
    properties:
      '<key>':
        $ref: '#/definitions/CountsMap'
    additionalProperties:
      $ref: '#/definitions/CountsMap'

  DataTable:
    description: |
      A JSON object that represents the dataset in a tabular form. The actual row data can be found in
      `rows*.row`, with the headers and other metadata available in other keys.
    schema:
      type: object
      properties:
        column_headers:
          description: |
            This property describes the top header of the table. The header can contain multiple rows, each row is
            found in the `keys` or `elements` property of an item. If the `keys` property is set, it contains
            references to dimension elements that are further elaborated in the `column_dimensions` property.
          type: array
          items:
            type: object
            properties:
              dimension:
                type: string
                description: the name of a column dimension
              keys:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: number
                description: |
                  A list of column headers for one dimension. This list has the same size as the number of columns in
                  the table (unless no column dimensions were specified, in which case this list is empty). The items
                  describe a dimension element, they refer to keys in the
                  `row_dimensions*.elements` dictionary for the given dimension. Further properties of this dimension
                  element can be found there.

                  This property is mutually exclusive with the `elements` property.
              elements:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: number
                description: |
                  A list of column headers for one dimension, but in this property the items do not refer to a
                  further description, the dimension element is just a single string or number. The string may also
                  be a formatted date.

                  The size of this list is equal to the number of columns in the table, or empty if no column
                  dimensions were specified.

                  This property is mutually exclusive with the `keys` property.
            required: [dimension]

        rows:
          description: |
            This property contains the row data and the left table header. The row data is found in the `row`
            property, the left header cells in the `dimensions` property.
          type: array
          items:
            type: object
            properties:
              dimensions:
                description: |
                  The left header cells for this row. Each cell contains the element or a reference to the element of
                  one row dimension. There is one item for each row dimension in this list, in order.
                type: array
                items:
                  type: object
                  properties:
                    dimension:
                      type: string
                      description: The name of this row dimension
                    key:
                      type:
                        oneOf:
                          - type: string
                          - type: number
                      description: |
                        Analogous to `column_headers*.keys`. The value is a reference to a dimension element
                        specified in `row_dimensions*.elements` for the specified dimension.

                        This property is mutually exclusive with the `element` property.
                    element:
                      type:
                        oneOf:
                          - type: string
                          - type: number
                      description: |
                        Analogous to `column_headers*.elements`. This is a single dimension element if that dimension
                        element is a single string, number or date. A date is represented as a formatted string.

                        This property is mutually exclusive with the `key` property.
                  required: [dimension]
              row:
                type: array
                items:
                  oneOf:
                    - type: string
                    - type: number
                    - type: array
                      items:
                        oneOf:
                          - type: string
                          - type: number
                description: |
                  The row data for a single table row. The items are strings or numbers or dates (represented as a
                  formatted string). The length of each row is the same, and is the same as the size of the
                  `column_headers*.keys` and `column_headers*.elements` lists.

                  The item can also be an array of strings, numbers or dates. This happens if multiple values fall
                  into the same table cell.

        row_dimensions:
          description: |
            This property contains a description of the row dimensions. It is a list of objects, with each object
            describing one dimension. If the dimension has its elements inlined the description here will only
            contain the dimension name. If the headers contain keys the full dimension elements can be found in the
            `elements` map. This map is indexed by the key found in the headers. The elements themselves are a
            free-form maps with the properties depending on the dimension type, but every element has at least a
            `label` property (which is often the same as the key, though not always).
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: the dimension name
              elements:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    label:
                      type: string
                  additionalProperties: true
                  description: |
                    A dimension element, the available properties depend on the dimension, but 'label' is always
                    included.
                description: |
                  The dimension elements, indexed by the key used in the header. This property is only present if the
                  dimension elements are compound and referenced by keys, simple elements will be inlined in the header.
            required: [name]

        column_dimensions:
          description: |
            The same as `row_dimensions`, but for the column dimensions.
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: the dimension name
              elements:
                type: object
                additionalProperties:
                  type: object
                  properties:
                    label:
                      type: string
                  additionalProperties: true
            required: [name]

        sort:
          description: |
            This property lists the sort order that was used in creating the dataset. This will generally include all
            the dimensions that were specified as row or column dimensions. This property includes both the row
            and column dimensions, with row dimensions first and column dimensions followed by that.
          type: array
          items:
            type: object
            properties:
              dimension:
                type: string
                description: the name of a dimension
              sortOrder:
                type: string
                description: |
                  'asc' or 'desc', describing if sorting is ascending or descending.
              user_requested:
                type: boolean
                description: |
                  Whether sorting on this dimension was explicitly requested by the client, i.e. set to
                  true if this dimension was part of the `rowSort` or `columnSort` request parameter.

                  This parameter is optional, the default is `false`.
            required: [dimension, order]

        offset:
          type: integer
          description: the offset of the first returned row in the full dataset
        row count:
          type: integer
          description: |
            The total number of rows available. This property is only set if the total is known, which is
            generally only the case if the last row is part of this result.
      required: [column_headers, rows, row_dimensions, sorting, offset]

  CrossTable:
    description: |
      A JSON object that represents the subject counts in a tabular form. List of rows, each of which contains
      a list with numbers of subjects for each cell.
    schema:
      type: object
      properties:
        rows:
          description: |
            This property contains the row data. Items are cells, each cell is a number of subject, computed as a result
            of an intersection of constraints specified for a row, for a column and for a selected subject set.
          type: array
          items:
            type: number
      required: [rows]

  observation:
    type: object
    properties:
      conceptCode:
        type: string
      encounterNum:
        type: integer
      endDate:
        type: string
        format: datetime
      instanceNum:
        type: integer
      locationCd:
        type: string
      modifierCd:
        type: string
      numberValue:
        type: integer
      patient:
        type: object
        properties:
          id:
            type: integer
      providerId:
        type: string
      sourcesystemCd:
        type: string
      startDate:
        type: string
        format: datetime
      textValue:
        type: string
      trialVisit:
        type: object
        properties:
          id:
            type: integer
      valueFlag:
        type: string
      valueType:
        type: string
            
  observations:
    type: object
    properties:
      header:
        type: object
        properties:
          dimensionDeclarations:
            type: array
            items:
              $ref: '#/definitions/dimensionDeclaration'
          sort:
            type: object
            properties:
              dimensionIndex:
                type: number
                description: >
                    An index into the dimensionDeclarations list, indicating the dimension on which the
                    result is sorted.
              sortOrder:
                type: string
                enum: [asc, desc]
                description: "'asc' or 'desc', indicating the sort order."
              field:
                type: number
                description: >
                    always 0. A non-zero value indicates that a different sorting is used that this version
                    of the api does not know about. This only applies to the protobuf representation, in JSON this
                    property is omitted.
      cells:
        type: array
        items:
          $ref: '#/definitions/cell'
      footer:
        type: object
        properties:
          dimensions:
            type: array
            items:
              type: array
              items:
                $ref: '#/definitions/dimensionValue'
  
  dimensionDeclaration:
    type: object
    properties:
      inline:
        description: 'If true, this dimension will be inlined in the cell. Only present if true.'
        type: boolean
      fields:
        description: 'Fields is omitted if the dimension consists of one field.'
        type: array
        items:
          $ref: '#/definitions/field'
      name:
        type: string
      type:
        description: 'STRING, INTEGER, DATE, OBJECT'
        type: string
    
  field:
    type: object
    properties:
      name:
        type: string
      type:
        description: 'STRING, INTEGER, DATE'
        type: string
        
  cell:
    type: object
    description: 'numericValue or stringValue, never both.'
    properties:
      dimensionIndexes:
        description: 'The index in the array is equal to the index of the dimension in the dimensions array in the footer. The number is the index of the dimensionValue in the dimension.'
        type: array
        items:
          type: integer
      inlineDimensions:
        type: array
        items:
          $ref: '#/definitions/dimensionValue'
      numericValue:
        type: number
      stringValue:
        type: string
        
  dimensionValue:
    type: object
    description: 'The structure of this value is described in the header. The order of the dimensionValues is determined by the order of the dimensionDeclaration in the header.'

  dimensionElements:
    type: object
    properties:
      apiVersion:
        type: string
      elements:
        description: 'List of dimension elements with properties specific to a given dimension.'
        type: array
        items:
          type: object

  export_job:
    type: object
    properties:
      id:
        type: integer
      jobName:
        type: string
      jobStatus:
        type: string
      jobStatusTime:
        type: string
        format: datetime
      userId:
        type: string
      viewerURL:
        type: string

  userQuery:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
      patientsQuery:
        type: object
      observationsQuery:
        type: object
      apiVersion:
        type: string
      bookmarked:
        type: boolean
      subscribed:
        type: boolean
      subscriptionFreq:
        type: string
      createDate:
        type: string
        format: 'date-time'
      updateDate:
        type: string
        format: 'date-time'
      queryBlob:
        type: object

  userQuerySet:
    type: object
    properties:
      id:
        type: integer
      queryId:
        type: integer
      queryName:
        type: string
      setSize:
        type: integer
      setTyp:
        type: string
      createDate:
        type: string
        format: 'date-time'
      objectsAdded:
        type: array
        items:
          type: integer
      objectsRemoved:
        type: array
        items:
          type: integer

  AggregatesMap:
    type: object
    description: 'Map from string to aggregates.'
    properties:
      '<conceptCode>':
        $ref: '#/definitions/Aggregates'
    additionalProperties:
      $ref: '#/definitions/Aggregates'

  Aggregates:
    description: Object for numerical aggregates or categorical value counts. Only the value of the requested aggregate type will be present.
    type: object
    properties:
      numericalValueAggregatesPerConcept:
        type: object
        properties:
          min:
            type: number
          max:
            type: number
          average:
            type: number
          count:
            type: number
          std_dev:
            type: number
      categoricalValueAggregatesPerConcept:
        type: object
        properties:
          valueCounts:
            description: map from value to count
            type: object
            properties:
              '<value>':
                type: number
            additionalProperties:
              type: number
          nullValueCounts:
            description: count of null values
            type: number

  relation_type:
      type: object
      properties:
        id:
          type: integer
        label:
          type: string
        description:
          type: string
        symmetrical:
          type: boolean
        biological:
          type: boolean