From 32723edbf839dbdecd8a74d783da9fa943c77213 Mon Sep 17 00:00:00 2001 From: dexamundsen Date: Wed, 28 Aug 2024 16:55:05 -0700 Subject: [PATCH 1/4] Split openAPI files by tag --- .../src/main/resources/api/activityLog.yaml | 167 + .../src/main/resources/api/annotations.yaml | 235 ++ service/src/main/resources/api/cohorts.yaml | 257 ++ service/src/main/resources/api/common.yaml | 188 ++ .../src/main/resources/api/conceptSets.yaml | 202 ++ service/src/main/resources/api/export.yaml | 288 ++ service/src/main/resources/api/reviews.yaml | 326 ++ .../main/resources/api/service_openapi.yaml | 2950 +---------------- service/src/main/resources/api/studies.yaml | 259 ++ service/src/main/resources/api/test.yaml | 30 + service/src/main/resources/api/underlays.yaml | 132 + .../main/resources/api/underlays_entity.yaml | 808 +++++ service/src/main/resources/api/users.yaml | 30 + 13 files changed, 3008 insertions(+), 2864 deletions(-) create mode 100644 service/src/main/resources/api/activityLog.yaml create mode 100644 service/src/main/resources/api/annotations.yaml create mode 100644 service/src/main/resources/api/cohorts.yaml create mode 100644 service/src/main/resources/api/common.yaml create mode 100644 service/src/main/resources/api/conceptSets.yaml create mode 100644 service/src/main/resources/api/export.yaml create mode 100644 service/src/main/resources/api/reviews.yaml create mode 100644 service/src/main/resources/api/studies.yaml create mode 100644 service/src/main/resources/api/test.yaml create mode 100644 service/src/main/resources/api/underlays.yaml create mode 100644 service/src/main/resources/api/underlays_entity.yaml create mode 100644 service/src/main/resources/api/users.yaml diff --git a/service/src/main/resources/api/activityLog.yaml b/service/src/main/resources/api/activityLog.yaml new file mode 100644 index 000000000..8b1293cc1 --- /dev/null +++ b/service/src/main/resources/api/activityLog.yaml @@ -0,0 +1,167 @@ +# Activity Log APIs, parameters & schema objects + +paths: + /listActivityLogEntries: + parameters: + - $ref: '#/components/parameters/ActivityLogFilterUserEmail' + - $ref: '#/components/parameters/ActivityLogFilterExactMatch' + - $ref: '#/components/parameters/ActivityLogFilterResourceType' + - $ref: '#/components/parameters/ActivityLogFilterActivityType' + - $ref: './common.yaml#/components/parameters/Offset' + - $ref: './common.yaml#/components/parameters/Limit' + get: + description: List the activity log entries + operationId: listActivityLogEntries + tags: [ ActivityLog ] + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ActivityLogEntryList' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 401: + $ref: './common.yaml#/components/responses/Unauthorized' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /getActivityLogEntry: + parameters: + - $ref: '#/components/parameters/ActivityLogEntryId' + get: + description: Get an activity log entry + operationId: getActivityLogEntry + tags: [ ActivityLog ] + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ActivityLogEntry' + 401: + $ref: './common.yaml#/components/responses/Unauthorized' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + +components: + parameters: + ActivityLogEntryId: + description: ID of the activity log entry + name: activityLogEntryId + in: path + required: true + schema: + type: string + + ActivityLogFilterUserEmail: + description: Text search on the activity log entry user email + name: userEmail + in: query + required: false + schema: + type: string + + ActivityLogFilterExactMatch: + description: True if the user email filter should check for an exact match + name: exactMatch + in: query + required: false + schema: + type: boolean + default: false + + ActivityLogFilterResourceType: + description: Filter on the activity log entry resource type + name: resourceType + in: query + required: false + schema: + $ref: '#/components/schemas/ResourceType' + + ActivityLogFilterActivityType: + name: activityType + in: query + description: Filter on the activity log entry activity type + required: false + schema: + $ref: '#/components/schemas/ActivityType' + + schemas: + ActivityLogEntryList: + type: array + items: + $ref: '#/components/schemas/ActivityLogEntry' + + ActivityLogEntry: + type: object + required: [ id, userEmail, logged, systemVersion, activityType ] + properties: + id: + type: string + nullable: false + userEmail: + type: string + nullable: false + logged: + type: string + format: date-time + nullable: false + systemVersion: + $ref: './common.yaml#/components/schemas/SystemVersion' + activityType: + $ref: '#/components/schemas/ActivityType' + resources: + type: array + items: + $ref: '#/components/schemas/ResourceObject' + additionalInfo: + description: Additional information for specific activity types + type: object + properties: + exportModel: + description: (EXPORT_COHORT) Name of the export model used + type: string + nullable: true + recordsCount: + description: (EXPORT_COHORT, CREATE_REVIEW) Number of primary + entity records involved + type: integer + format: int64 + nullable: true + + ActivityType: + type: string + enum: [ 'CREATE_STUDY', 'DELETE_STUDY', 'CREATE_COHORT', 'DELETE_COHORT', + 'EXPORT_COHORT', 'CREATE_REVIEW', 'DELETE_REVIEW' ] + + ResourceObject: + type: object + required: [ type, studyId ] + properties: + type: + $ref: '#/components/schemas/ResourceType' + studyId: + $ref: './studies.yaml#/components/schemas/StudyId' + studyDisplayName: + $ref: './studies.yaml#/components/schemas/StudyDisplayName' + studyProperties: + $ref: './common.yaml#/components/schemas/Properties' + cohortId: + $ref: './cohorts.yaml#/components/schemas/CohortId' + cohortDisplayName: + $ref: './cohorts.yaml#/components/schemas/CohortDisplayName' + cohortRevisionId: + $ref: './cohorts.yaml#/components/schemas/CohortRevisionId' + reviewId: + $ref: './reviews.yaml#/components/schemas/ReviewId' + reviewDisplayName: + $ref: './reviews.yaml#/components/schemas/ReviewDisplayName' + + ResourceType: + type: string + enum: [ 'STUDY', 'COHORT', 'REVIEW' ] diff --git a/service/src/main/resources/api/annotations.yaml b/service/src/main/resources/api/annotations.yaml new file mode 100644 index 000000000..f370c8707 --- /dev/null +++ b/service/src/main/resources/api/annotations.yaml @@ -0,0 +1,235 @@ +# Study-Cohort-Annotation APIs, parameters & schema objects + +paths: + /createListAnnotationKey: + parameters: + - $ref: './studies.yaml#/components/parameters/StudyId' + - $ref: './cohorts.yaml#/components/parameters/CohortId' + get: + description: List all annotation keys for a cohort + operationId: listAnnotationKeys + tags: [ Annotations ] + parameters: + - $ref: './common.yaml#/components/parameters/Offset' + - $ref: './common.yaml#/components/parameters/Limit' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/AnnotationList' + 500: + $ref: './common.yaml#/components/responses/ServerError' + post: + description: Create a new annotation key + operationId: createAnnotationKey + tags: [ Annotations ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AnnotationCreateInfo' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Annotation' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /getUpdateDeleteAnnotationKey: + parameters: + - $ref: './studies.yaml#/components/parameters/StudyId' + - $ref: './cohorts.yaml#/components/parameters/CohortId' + - $ref: '#/components/parameters/AnnotationId' + get: + description: Get an existing annotation key + operationId: getAnnotationKey + tags: [ Annotations ] + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Annotation' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + patch: + description: Update an existing annotation key + operationId: updateAnnotationKey + tags: [ Annotations ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AnnotationUpdateInfo' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Annotation' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + delete: + description: Delete a annotation key + operationId: deleteAnnotationKey + tags: [ Annotations ] + responses: + 204: + $ref: './common.yaml#/components/responses/NoContent' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /createDeleteAnnotationValue: + parameters: + - $ref: './studies.yaml#/components/parameters/StudyId' + - $ref: './cohorts.yaml#/components/parameters/CohortId' + - $ref: '#/components/parameters/AnnotationId' + - $ref: './reviews.yaml#/components/parameters/ReviewId' + - $ref: './underlays_entity.yaml#/components/parameters/PrimaryEntityInstanceId' + post: + description: Create or update an annotation value + operationId: updateAnnotationValue + tags: [ Annotations ] + requestBody: + required: true + content: + application/json: + schema: + $ref: './common.yaml#/components/schemas/Literal' + responses: + 200: + $ref: './common.yaml#/components/responses/OK' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + delete: + description: Delete a annotation value + operationId: deleteAnnotationValues + tags: [ Annotations ] + responses: + 204: + $ref: './common.yaml#/components/responses/NoContent' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + +components: + parameters: + AnnotationId: + description: ID of the annotation + name: annotationId + in: path + required: true + schema: + type: string + + + + schemas: + AnnotationList: + type: array + items: + $ref: '#/components/schemas/Annotation' + + Annotation: + type: object + required: [ id, displayName, dataType ] + properties: + id: + description: ID of the annotation, immutable + type: string + displayName: + $ref: '#/components/schemas/AnnotationDisplayName' + description: + $ref: '#/components/schemas/AnnotationDescription' + dataType: + $ref: './common.yaml#/components/schemas/DataType' + enumVals: + description: May only be set if dataType=STRING. Annotation value + must be one of enumVals + type: array + items: + type: string + + AnnotationDisplayName: + description: Human readable name of the annotation + type: string + maxLength: 35 + + AnnotationDescription: + description: Description of the annotation + type: string + + AnnotationCreateInfo: + type: object + required: [ displayName, dataType ] + properties: + displayName: + $ref: '#/components/schemas/AnnotationDisplayName' + description: + $ref: '#/components/schemas/AnnotationDescription' + dataType: + $ref: './common.yaml#/components/schemas/DataType' + enumVals: + description: May only be set if dataType=STRING. Annotation value + must be one of enumVals + type: array + items: + type: string + + AnnotationUpdateInfo: + type: object + properties: + displayName: + $ref: '#/components/schemas/AnnotationDisplayName' + description: + $ref: '#/components/schemas/AnnotationDescription' + + AnnotationFilter: + description: Filter on an annotation value (e.g. reviewStatus=complete) + type: object + properties: + annotation: + type: string + operator: + type: string + enum: [ 'EQUALS', 'NOT_EQUALS', 'LESS_THAN', 'GREATER_THAN' ] + value: + $ref: './common.yaml#/components/schemas/Literal' + + AnnotationValue: + type: object + required: [ instanceId, value, isMostRecent, isPartOfSelectedReview ] + properties: + instanceId: + description: ID of the annotation value, immutable + type: string + value: + $ref: './common.yaml#/components/schemas/Literal' + isMostRecent: + type: boolean + isPartOfSelectedReview: + type: boolean diff --git a/service/src/main/resources/api/cohorts.yaml b/service/src/main/resources/api/cohorts.yaml new file mode 100644 index 000000000..0a00a1abe --- /dev/null +++ b/service/src/main/resources/api/cohorts.yaml @@ -0,0 +1,257 @@ +# Study-Cohort APIs, parameters & schema objects + +paths: + /createListCohort: + parameters: + - $ref: './studies.yaml#/components/parameters/StudyId' + get: + description: List all cohorts in a study + operationId: listCohorts + tags: [ Cohorts ] + parameters: + - $ref: './common.yaml#/components/parameters/Offset' + - $ref: './common.yaml#/components/parameters/Limit' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/CohortList' + 500: + $ref: './common.yaml#/components/responses/ServerError' + post: + description: Create a new cohort + operationId: createCohort + tags: [ Cohorts ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CohortCreateInfo' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Cohort' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /getUpdateDeleteCohort: + parameters: + - $ref: './studies.yaml#/components/parameters/StudyId' + - $ref: '#/components/parameters/CohortId' + - $ref: '#/components/parameters/CohortRevisionId' + get: + description: Get an existing cohort + operationId: getCohort + tags: [ Cohorts ] + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Cohort' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + patch: + description: Update an existing cohort + operationId: updateCohort + tags: [ Cohorts ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CohortUpdateInfo' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Cohort' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + delete: + description: Delete a cohort + operationId: deleteCohort + tags: [ Cohorts ] + responses: + 204: + $ref: './common.yaml#/components/responses/NoContent' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /queryCohortCounts: + parameters: + - $ref: './studies.yaml#/components/parameters/StudyId' + - $ref: '#/components/parameters/CohortId' + post: + description: Run a count query for a cohort + operationId: queryCohortCounts + tags: [ Cohorts ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CohortCountQuery' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: './underlays_entity.yaml#/components/schemas/InstanceCountList' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + +components: + parameters: + CohortId: + description: ID of the cohort + name: cohortId + in: path + required: true + schema: + type: string + + CohortRevisionId: + description: ID of the cohort revision + name: cohortRevisionId + in: query + required: false + schema: + type: string + + schemas: + CohortList: + type: array + items: + $ref: '#/components/schemas/Cohort' + + Cohort: + type: object + required: [ id, underlayName, displayName, criteriaGroups, created, + createdBy, lastModified ] + properties: + id: + $ref: '#/components/schemas/CohortId' + revisionId: + $ref: '#/components/schemas/CohortRevisionId' + underlayName: + $ref: './underlays.yaml#/components/schemas/UnderlayName' + displayName: + $ref: '#/components/schemas/CohortDisplayName' + description: + $ref: '#/components/schemas/CohortDescription' + criteriaGroupSections: + description: Criteria group sections that define the entity filter + type: array + items: + $ref: './underlays_entity.yaml#/components/schemas/CriteriaGroupSection' + created: + description: Timestamp of when the cohort was created + type: string + format: date-time + createdBy: + description: Email of user who created cohort + type: string + lastModified: + description: Timestamp of when the cohort was last modified + type: string + format: date-time + isDeleted: + type: boolean + + CohortId: + description: ID of the cohort, immutable + type: string + + CohortRevisionId: + description: ID of a frozen cohort revision, immutable + type: string + + CohortDisplayName: + description: Human readable name of the cohort + type: string + + CohortDescription: + description: Description of the cohort + type: string + + CohortCreateInfo: + type: object + properties: + underlayName: + $ref: './underlays.yaml#/components/schemas/UnderlayName' + displayName: + $ref: '#/components/schemas/CohortDisplayName' + description: + $ref: '#/components/schemas/CohortDescription' + + CohortUpdateInfo: + type: object + properties: + displayName: + $ref: '#/components/schemas/CohortDisplayName' + description: + $ref: '#/components/schemas/CohortDescription' + criteriaGroupSections: + description: Criteria group sections that define the entity filter + type: array + items: + $ref: './underlays_entity.yaml#/components/schemas/CriteriaGroupSection' + + CohortCountQuery: + description: Count output entity instances for a cohort filter + type: object + required: [ groupByAttributes ] + properties: + criteriaGroupSectionId: + type: string + criteriaGroupId: + type: string + entity: + description: Entity to count. Defaults to primary entity + type: string + countDistinctAttribute: + description: Attribute to count (e.g. person_id will return counts + for the number of distinct person_ids per group by combination). + Defaults to id attribute + type: string + groupByAttributes: + description: Attributes to group by. One count will be returned for + each possible combination of attribute values (e.g. [gender, + hair_color] will return counts for man+red, man+black, woman+red, + woman+black) + type: array + items: + type: string + orderByDirection: + $ref: './common.yaml#/components/schemas/OrderByDirection' + limit: + $ref: './common.yaml#/components/schemas/Limit' + pageSize: + $ref: './common.yaml#/components/schemas/PageSize' + pageMarker: + $ref: './common.yaml#/components/schemas/PageMarker' diff --git a/service/src/main/resources/api/common.yaml b/service/src/main/resources/api/common.yaml new file mode 100644 index 000000000..334ebcc9a --- /dev/null +++ b/service/src/main/resources/api/common.yaml @@ -0,0 +1,188 @@ +# Common schema and response definitions + +components: + parameters: + # --------------- Pagination --------------- + + Offset: + description: The number of items to skip before starting to collect the + result set + name: offset + in: query + required: false + schema: + type: integer + minimum: 0 + default: 0 + + Limit: + description: The maximum number of items to return. Defaults to 50 + name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + default: 50 + + schemas: + # --------------- Application --------------- + + SystemVersion: + type: object + required: [ gitTag, gitHash, github, build ] + properties: + gitTag: + description: Git tag of currently deployed app + type: string + gitHash: + description: Git hash of currently deployed app + type: string + github: + description: Github link to currently deployed commit + type: string + build: + description: Version of the currently deployed app declared in + build.gradle. Client and server versions are linked + type: string + + OrderByDirection: + description: Defaults to ascending + type: string + enum: [ 'ASCENDING', 'DESCENDING' ] + + Limit: + description: Maximum number of results to return. Defaults to 250 + type: integer + default: 250 + + PageSize: + type: integer + + PageMarker: + type: string + + NumRowsAcrossAllPages: + type: integer + + Literal: + description: Union of references to each value type. Exactly one will be + populated based on the dataType + type: object + nullable: true + properties: + dataType: + $ref: '#/components/schemas/DataType' + valueUnion: + type: object + properties: + boolVal: + type: boolean + int64Val: + type: integer + format: int64 + stringVal: + type: string + dateVal: + description: Format YYYY-MM-DD + type: string + timestampVal: + description: Format YYYY-MM-DD hh:mm:ss + type: string + doubleVal: + type: number + format: double + + DataType: + type: string + enum: [ 'INT64', 'STRING', 'BOOLEAN', 'DATE', 'TIMESTAMP', 'DOUBLE' ] + + ValueDisplay: + description: Attribute value and optional display string + type: object + properties: + value: + $ref: '#/components/schemas/Literal' + display: + description: Optional display string + type: string + nullable: true + + # --------------- Errors --------------- + + ErrorReport: + type: object + required: [ message, statusCode, causes ] + properties: + message: + type: string + statusCode: + type: integer + causes: + type: array + items: + type: string + + # --------------- Properties --------------- + + PropertyKeyValue: + type: object + required: [ key, value ] + properties: + key: + description: String to identify the key. Keys must be 1-1024 + characters, using letters, numbers, dashes, and underscores and + must not start with a dash or underscore + type: string + value: + description: Arbitrary string value + type: string + + PropertyKeys: + description: List of property keys + type: array + items: + type: string + + Properties: + description: List of key-value pairs of strings + type: array + items: + $ref: '#/components/schemas/PropertyKeyValue' + + responses: + OK: # 200 + description: OK + + NoContent: # 204 + description: OK (No Content) + + # --------------- Errors --------------- + + BadRequest: # 400 + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorReport' + + Unauthorized: # 401 + description: Unauthorized + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorReport' + + NotFound: # 404 + description: Not found + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorReport' + + ServerError: # 500 + description: Internal Server Error + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorReport' diff --git a/service/src/main/resources/api/conceptSets.yaml b/service/src/main/resources/api/conceptSets.yaml new file mode 100644 index 000000000..ec667f123 --- /dev/null +++ b/service/src/main/resources/api/conceptSets.yaml @@ -0,0 +1,202 @@ +# Study-ConceptSet APIs, parameters & schema objects + +paths: + /createListConceptSet: + parameters: + - $ref: './studies.yaml#/components/parameters/StudyId' + get: + description: List all concept sets in a study + operationId: listConceptSets + tags: [ ConceptSets ] + parameters: + - $ref: './common.yaml#/components/parameters/Offset' + - $ref: './common.yaml#/components/parameters/Limit' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ConceptSetList' + 500: + $ref: './common.yaml#/components/responses/ServerError' + post: + description: Create a new concept set + operationId: createConceptSet + tags: [ ConceptSets ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ConceptSetCreateInfo' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ConceptSet' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /getUpdateDeleteConceptSet: + parameters: + - $ref: './studies.yaml#/components/parameters/StudyId' + - $ref: '#/components/parameters/ConceptSetId' + get: + description: Get an existing concept set + operationId: getConceptSet + tags: [ ConceptSets ] + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ConceptSet' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + patch: + description: Update an existing concept set + operationId: updateConceptSet + tags: [ ConceptSets ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ConceptSetUpdateInfo' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ConceptSet' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + delete: + description: Delete a concept set + operationId: deleteConceptSet + tags: [ ConceptSets ] + responses: + 204: + $ref: './common.yaml#/components/responses/NoContent' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + +components: + parameters: + ConceptSetId: + description: ID of the concept set + name: conceptSetId + in: path + required: true + schema: + type: string + + schemas: + ConceptSetList: + type: array + items: + $ref: '#/components/schemas/ConceptSet' + + ConceptSet: + type: object + required: [ id, underlayName, displayName, criteria, entityOutputs, + created, createdBy, lastModified ] + properties: + id: + $ref: '#/components/schemas/ConceptSetId' + underlayName: + $ref: './underlays.yaml#/components/schemas/UnderlayName' + displayName: + $ref: '#/components/schemas/ConceptSetDisplayName' + description: + $ref: '#/components/schemas/ConceptSetDescription' + criteria: + description: Criteria that define the entity filter + type: array + items: + $ref: './underlays_entity.yaml#/components/schemas/Criteria' + entityOutputs: + type: array + description: Outputs per entity + items: + $ref: '#/components/schemas/EntityOutput' + created: + description: Timestamp of when the concept set was created + type: string + format: date-time + createdBy: + description: Email of user who created the concept set + type: string + lastModified: + description: Timestamp of when the concept set was last modified + type: string + format: date-time + + ConceptSetId: + description: ID of the concept set, immutable + type: string + + ConceptSetDisplayName: + description: Human readable name of the concept set + type: string + + ConceptSetDescription: + description: Description of the concept set + type: string + + EntityOutput: + type: object + properties: + entity: + description: Entity name + type: string + excludeAttributes: + description: Names of attributes to exclude from output + type: array + items: + type: string + required: + - entity + + ConceptSetCreateInfo: + type: object + properties: + underlayName: + $ref: './underlays.yaml#/components/schemas/UnderlayName' + displayName: + $ref: '#/components/schemas/ConceptSetDisplayName' + description: + $ref: '#/components/schemas/ConceptSetDescription' + + ConceptSetUpdateInfo: + type: object + properties: + displayName: + $ref: '#/components/schemas/ConceptSetDisplayName' + description: + $ref: '#/components/schemas/ConceptSetDescription' + criteria: + description: Criteria that define the entity filter + type: array + items: + $ref: './underlays_entity.yaml#/components/schemas/Criteria' + entityOutputs: + description: Outputs per entity + type: array + items: + $ref: '#/components/schemas/EntityOutput' diff --git a/service/src/main/resources/api/export.yaml b/service/src/main/resources/api/export.yaml new file mode 100644 index 000000000..36ac15912 --- /dev/null +++ b/service/src/main/resources/api/export.yaml @@ -0,0 +1,288 @@ +# Underlay-Export APIs, parameters & schema objects + +paths: + /listExportModels: + parameters: + - $ref: './underlays.yaml#/components/parameters/UnderlayName' + get: + description: List the available export models + operationId: listExportModels + tags: [ Export ] + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ExportModelList' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /previewExportInstances: + parameters: + - $ref: './underlays.yaml#/components/parameters/UnderlayName' + - $ref: './underlays_entity.yaml#/components/parameters/EntityName' + get: + description: List entity instances that will be included in an export + operationId: previewExportInstances + tags: [ Export ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ExportPreviewRequest' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: './underlays_entity.yaml#/components/schemas/InstanceListResult' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /describeExport: + parameters: + - $ref: './underlays.yaml#/components/parameters/UnderlayName' + get: + description: Describe the entities and attributes that will be included + in an export + operationId: describeExport + tags: [ Export ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ExportPreviewRequest' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/EntityOutputPreviewList' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /exportInstancesAndAnnotations: + parameters: + - $ref: './underlays.yaml#/components/parameters/UnderlayName' + get: + description: Export entity instances and review annotations + operationId: exportInstancesAndAnnotations + tags: [ Export ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ExportRequest' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ExportResult' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + +components: + schemas: + ExportModelList: + type: array + items: + $ref: '#/components/schemas/ExportModel' + + ExportModel: + type: object + properties: + name: + type: string + nullable: false + displayName: + type: string + nullable: false + description: + type: string + nullable: true + numPrimaryEntityCap: + description: Maximum number of primary entity instances, across all + selected cohorts, that this model can export + type: integer + inputs: + description: Map of input parameter names to descriptions + type: object + additionalProperties: + type: string + nullable: true + outputs: + description: Map of output parameters names to descriptions + type: object + additionalProperties: + type: string + nullable: true + + ExportPreviewRequest: + type: object + required: [ study, cohorts, conceptSets ] + properties: + study: + type: string + cohorts: + description: List of cohort ids + type: array + items: + type: string + conceptSets: + description: List of concept set ids + type: array + items: + type: string + limit: + type: integer + includeAllAttributes: + description: When true, ignore the selected attributes in the data feature + set definitions and include all attributes for each output entity + type: boolean + default: false + + EntityOutputPreviewList: + type: object + required: [ entityOutputs ] + properties: + entityOutputs: + type: array + items: + $ref: '#/components/schemas/EntityOutputPreview' + + EntityOutputPreview: + type: object + required: [ entity, includedAttributes, criteria ] + properties: + entity: + description: Entity name + type: string + includedAttributes: + description: Names of attributes included in the output + type: array + items: + type: string + criteria: + type: array + items: + type: object + properties: + conceptSetId: + type: string + criteriaId: + type: string + required: + - conceptSetId + - criteriaId + indexSql: + description: SQL string against the index tables. This will be + populated if source queries are not configured for this entity + type: string + sourceSql: + description: SQL string against the source tables. This will be + populated if source queries are configured for this entity + type: string + + ExportRequest: + type: object + properties: + exportModel: + description: Name of the export model to use + type: string + inputs: + description: Key-value map of the export model inputs + (e.g. filenamePrefix=test) + type: object + additionalProperties: + type: string + nullable: true + redirectBackUrl: + type: string + nullable: true + study: + type: string + nullable: false + cohorts: + description: List of cohort ids + type: array + items: + type: string + conceptSets: + description: List of concept set ids + type: array + items: + type: string + includeAnnotations: + description: Include the annotation data when true + type: boolean + + ExportResult: + type: object + required: [ status, outputs, links ] + properties: + status: + type: string + enum: [ "SUCCEEDED", "FAILED" ] + redirectAwayUrl: + type: string + outputs: + # TODO: Remove this outputs property from the service API once the UI is using the links. + description: Key-value map of output data generated by the export model + type: object + additionalProperties: + type: string + links: + description: Output link results generated by the export model + type: array + items: + $ref: "#/components/schemas/ExportLinkResult" + error: + description: Error message if this export failed outside of individual + link generation + type: string + + ExportLinkResult: + type: object + required: [ tags ] + properties: + displayName: + type: string + url: + type: string + tags: + description: Ordered list of tags that indicate how this link result + should be displayed to the user. The first tag is the top-level + section, the second tag is a sub-section, etc. e.g. ["Annotations", + "Cohort 123"] means this link result will be displayed in the + Annotations section, Cohort 123 sub-section + type: array + items: + type: string + message: + description: Optional message (e.g. "No entity data. File not generated.") + type: string + error: + description: Error message if generating this link result failed + type: string diff --git a/service/src/main/resources/api/reviews.yaml b/service/src/main/resources/api/reviews.yaml new file mode 100644 index 000000000..befd2958a --- /dev/null +++ b/service/src/main/resources/api/reviews.yaml @@ -0,0 +1,326 @@ +# Study-Cohort-Review APIs, parameters & schema objects + +paths: + /createListReview: + parameters: + - $ref: './studies.yaml#/components/parameters/StudyId' + - $ref: './cohorts.yaml#/components/parameters/CohortId' + get: + description: List all reviews for a cohort + operationId: listReviews + tags: [ Reviews ] + parameters: + - $ref: './common.yaml#/components/parameters/Offset' + - $ref: './common.yaml#/components/parameters/Limit' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ReviewList' + 500: + $ref: './common.yaml#/components/responses/ServerError' + post: + description: Create a new review + operationId: createReview + tags: [ Reviews ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ReviewCreateInfo' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Review' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /getUpdateDeleteReview: + parameters: + - $ref: './studies.yaml#/components/parameters/StudyId' + - $ref: './cohorts.yaml#/components/parameters/CohortId' + - $ref: '#/components/parameters/ReviewId' + get: + description: Get an existing review + operationId: getReview + tags: [ Reviews ] + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Review' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + patch: + description: Update an existing review + operationId: updateReview + tags: [ Reviews ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ReviewUpdateInfo' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Review' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + delete: + description: Delete a review + operationId: deleteReview + tags: [ Reviews ] + responses: + 204: + $ref: './common.yaml#/components/responses/NoContent' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + + /listReviewInstancesAndAnnotations: + parameters: + - $ref: './studies.yaml#/components/parameters/StudyId' + - $ref: './cohorts.yaml#/components/parameters/CohortId' + - $ref: '#/components/parameters/ReviewId' + post: + description: List primary entity instances in a review and any associated + annotation values + operationId: listReviewInstancesAndAnnotations + tags: [ Reviews ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ReviewQuery' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/ReviewInstanceListResult' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /countReviewInstances: + parameters: + - $ref: './studies.yaml#/components/parameters/StudyId' + - $ref: './cohorts.yaml#/components/parameters/CohortId' + - $ref: '#/components/parameters/ReviewId' + post: + description: Count primary entity instances in a review + operationId: countReviewInstances + tags: [ Reviews ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ReviewCountQuery' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: './underlays_entity.yaml#/components/schemas/InstanceCountList' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 500: + $ref: './common.yaml#/components/responses/ServerError' + +components: + parameters: + ReviewId: + description: ID of the review + name: reviewId + in: path + required: true + schema: + type: string + + schemas: + ReviewList: + type: array + items: + $ref: '#/components/schemas/Review' + + Review: + type: object + properties: + id: + $ref: '#/components/schemas/ReviewId' + displayName: + $ref: '#/components/schemas/ReviewDisplayName' + description: + $ref: '#/components/schemas/ReviewDescription' + size: + $ref: '#/components/schemas/ReviewSize' + cohort: + $ref: './cohorts.yaml#/components/schemas/Cohort' + created: + description: Timestamp of when the review was created + type: string + format: date-time + createdBy: + description: Email of user who created the review + type: string + lastModified: + description: Timestamp of when the review was last modified + type: string + format: date-time + required: + - id + - displayName + - size + - cohortRevision + - created + - createdBy + - lastModified + + ReviewId: + description: ID of the review, immutable + type: string + + ReviewDisplayName: + description: Human readable name of the review + type: string + + ReviewDescription: + description: Description of the review + type: string + + ReviewSize: + description: Number of primary entity instances included in the review + type: integer + + ReviewCreateInfo: + type: object + properties: + displayName: + $ref: '#/components/schemas/ReviewDisplayName' + description: + $ref: '#/components/schemas/ReviewDescription' + size: + $ref: '#/components/schemas/ReviewSize' + required: + - displayName + - size + + ReviewUpdateInfo: + type: object + properties: + displayName: + $ref: '#/components/schemas/ReviewDisplayName' + description: + $ref: '#/components/schemas/ReviewDescription' + + ReviewQuery: + type: object + description: Query for review instances and annotations + properties: + includeAttributes: + description: Attributes to include in the returned instances + type: array + items: + type: string + entityFilter: + $ref: './underlays_entity.yaml#/components/schemas/Filter' + annotationFilter: + $ref: './annotations.yaml#/components/schemas/AnnotationFilter' + orderBys: + type: array + description: Attributes or annotations, and direction to order the results by + items: + type: object + description: Attribute or annotation and the direction + properties: + attribute: + type: string + description: Name of the attribute + annotation: + type: string + description: ID of the annotation + direction: + $ref: './common.yaml#/components/schemas/OrderByDirection' + limit: + $ref: './common.yaml#/components/schemas/Limit' + pageSize: + $ref: './common.yaml#/components/schemas/PageSize' + pageMarker: + $ref: './common.yaml#/components/schemas/PageMarker' + +#filter + + ReviewInstanceListResult: + type: object + description: List of instances + properties: + sql: + type: string + instances: + type: array + items: + $ref: '#/components/schemas/ReviewInstance' + pageMarker: + $ref: './common.yaml#/components/schemas/PageMarker' + + ReviewInstance: + type: object + properties: + stableIndex: + description: Index of the instance, unchanged when sorting + type: integer + attributes: + description: A map of entity attribute names to their value for this + instance. The id attribute will always be included + type: object + additionalProperties: + $ref: './common.yaml#/components/schemas/ValueDisplay' + annotations: + description: A map of annotation ids to their values for this instance + in this review + type: object + additionalProperties: + type: array + nullable: true + items: + $ref: './annotations.yaml#/components/schemas/AnnotationValue' + + ReviewCountQuery: + description: Count review instances + type: object + properties: + attributes: + description: Attributes to group by. One count will be returned for + each possible combination of attribute values (e.g. [gender, + hair_color] will return counts for man+red, man+black, woman+red, + woman+black) + type: array + items: + type: string \ No newline at end of file diff --git a/service/src/main/resources/api/service_openapi.yaml b/service/src/main/resources/api/service_openapi.yaml index 99d8bc458..55c3195c8 100644 --- a/service/src/main/resources/api/service_openapi.yaml +++ b/service/src/main/resources/api/service_openapi.yaml @@ -2,2941 +2,166 @@ openapi: 3.0.3 info: title: Tanagra Service API description: github.com/DataBiosphere/tanagra - version: 0.0.0 + version: 0.0.1 servers: - - url: / +- url: / security: - - bearerAuth: [] - - authorization: [openid, email, profile] +- bearerAuth: [] +- authorization: [ openid, email, profile ] paths: # --------------- Unauthenticated Paths --------------- - "/status": + /status: get: security: [ ] - summary: Returns the operational status of the service + description: Returns the operational status of the service operationId: serviceStatus - tags: [Unauthenticated] + tags: [ Unauthenticated ] responses: 200: description: Service can process requests 500: - description: | - Service cannot process requests. That might be because dependent services are - unavailable, or because there is a problem with the service itself. + description: Service cannot process requests. That might be because + dependent services are unavailable, or because there is a problem + with the service itself - "/version": + /version: get: security: [ ] - summary: Returns the deployed version of the service + description: Returns the deployed version of the service operationId: serviceVersion - tags: [Unauthenticated] + tags: [ Public ] responses: 200: description: Version properties content: application/json: schema: - $ref: "#/components/schemas/SystemVersion" - 500: - $ref: "#/components/responses/ServerError" + $ref: './common.yaml#/components/schemas/SystemVersion' # --------------- Users --------------- - "/v2/profile": - get: - description: Returns the current user's profile information - operationId: getMe - tags: [Users] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/UserProfile" - 500: - $ref: "#/components/responses/ServerError" + /v2/profile: + $ref: './users.yaml#/paths/~1getMe' # --------------- Underlays --------------- - "/v2/underlays": - get: - summary: List the underlay summaries - operationId: listUnderlaySummaries - tags: [Underlays] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/UnderlaySummaryList" - 500: - $ref: "#/components/responses/ServerError" + /v2/underlays: + $ref: './underlays.yaml#/paths/~1listUnderlaySummaries' - "/v2/underlays/{underlayName}": - parameters: - - $ref: "#/components/parameters/UnderlayName" - get: - summary: Get an underlay - operationId: getUnderlay - tags: [Underlays] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Underlay" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + /v2/underlays/{underlayName}: + $ref: './underlays.yaml#/paths/~1getUnderlay' - "/v2/underlays/{underlayName}/entities": - parameters: - - $ref: "#/components/parameters/UnderlayName" - get: - summary: List the entities in an underlay - operationId: listEntities - tags: [Underlays] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/EntityList" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + # --------------- Underlays - Entities --------------- - "/v2/underlays/{underlayName}/entities/{entityName}": - parameters: - - $ref: "#/components/parameters/UnderlayName" - - $ref: "#/components/parameters/EntityName" - get: - summary: Get an entity - operationId: getEntity - tags: [Underlays] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Entity" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + /v2/underlays/{underlayName}/entities: + $ref: './underlays_entity.yaml#/paths/~1listEntities' - "/v2/underlays/{underlayName}/entities/{entityName}/instances": - parameters: - - $ref: "#/components/parameters/UnderlayName" - - $ref: "#/components/parameters/EntityName" - post: - summary: List entity instances - operationId: listInstances - tags: [Underlays] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/Query" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/InstanceListResult" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + /v2/underlays/{underlayName}/entities/{entityName}: + $ref: './underlays_entity.yaml#/paths/~1getEntity' - "/v2/underlays/{underlayName}/entities/{entityName}/instancesForPrimaryEntity": - parameters: - - $ref: "#/components/parameters/UnderlayName" - - $ref: "#/components/parameters/EntityName" - post: - summary: List entity instances filtered for a single primary entity id - operationId: listInstancesForPrimaryEntity - tags: [Underlays] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/QueryFilterOnPrimaryEntity" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/InstanceListResult" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + /v2/underlays/{underlayName}/entities/{entityName}/instances: + $ref: './underlays_entity.yaml#/paths/~1listInstances' - "/v2/underlays/{underlayName}/entities/{entityName}/counts": - parameters: - - $ref: "#/components/parameters/UnderlayName" - - $ref: "#/components/parameters/EntityName" - post: - summary: Count entity instances - operationId: countInstances - tags: [Underlays] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CountQuery" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/InstanceCountList" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + /v2/underlays/{underlayName}/entities/{entityName}/instancesForPrimaryEntity: + $ref: './underlays_entity.yaml#/paths/~1listInstancesForPrimaryEntity' - "/v2/underlays/{underlayName}/entities/{entityName}/hints": - parameters: - - $ref: "#/components/parameters/UnderlayName" - - $ref: "#/components/parameters/EntityName" - post: - summary: Query entity display hints - operationId: queryHints - tags: [Underlays] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/HintQuery" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/DisplayHintList" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + /v2/underlays/{underlayName}/entities/{entityName}/counts: + $ref: './underlays_entity.yaml#/paths/~1countInstances' - # --------------- Studies --------------- + /v2/underlays/{underlayName}/entities/{entityName}/hints: + $ref: './underlays_entity.yaml#/paths/~1queryHints' - "/v2/studies": - get: - parameters: - - $ref: "#/components/parameters/StudyFilterDisplayName" - - $ref: "#/components/parameters/StudyFilterDescription" - - $ref: "#/components/parameters/StudyFilterCreatedBy" - - $ref: "#/components/parameters/StudyFilterIncludeDeleted" - - $ref: "#/components/parameters/StudyFilterProperties" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Limit" - summary: List all studies a user can read - operationId: listStudies - tags: [Studies] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/StudyList" - 500: - $ref: "#/components/responses/ServerError" - post: - summary: Create a new study - operationId: createStudy - tags: [Studies] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/StudyCreateInfo" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Study" - 500: - $ref: "#/components/responses/ServerError" + # --------------- Underlays: Export --------------- - "/v2/studies/{studyId}": - parameters: - - $ref: "#/components/parameters/StudyId" - get: - summary: Get an existing study - operationId: getStudy - tags: [Studies] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Study" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" - patch: - summary: Update an existing study - operationId: updateStudy - tags: [Studies] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/StudyUpdateInfo" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Study" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" - delete: - summary: Delete a study - operationId: deleteStudy - tags: [Studies] - responses: - 204: - description: OK - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + /v2/underlays/{underlayName}/exportModels": + $ref: './export.yaml#/paths/~1listExportModels' - "/v2/studies/{studyId}/properties": - parameters: - - $ref: "#/components/parameters/StudyId" - post: - summary: | - Update the properties in a study. Only properties with keys in request - are updated. Properties with keys not in request are not updated. - operationId: updateStudyProperties - tags: [Studies] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/Properties" - responses: - 204: - description: OK - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" - patch: - summary: | - Delete properties in a study. Only properties with keys in - request are deleted. Properties with keys not in request are not - deleted. - operationId: deleteStudyProperties - tags: [Studies] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/PropertyKeys" - responses: - 204: - description: OK - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + /v2/underlays/{underlayName}/entities/{entityName}/previewExport: + $ref: './export.yaml#/paths/~1previewExportInstances' - # --------------- Studies: Cohorts --------------- + /v2/underlays/{underlayName}/describeExport: + $ref: './export.yaml#/paths/~1describeExport' - "/v2/studies/{studyId}/cohorts": - parameters: - - $ref: "#/components/parameters/StudyId" - get: - parameters: - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Limit" - summary: List all cohorts in a study - operationId: listCohorts - tags: [Cohorts] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/CohortList" - 500: - $ref: "#/components/responses/ServerError" - post: - summary: Create a new cohort - operationId: createCohort - tags: [Cohorts] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CohortCreateInfo" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Cohort" - 500: - $ref: "#/components/responses/ServerError" + /v2/underlays/{underlayName}/export: + $ref: './export.yaml#/paths/~1exportInstancesAndAnnotations' - "/v2/studies/{studyId}/cohorts/{cohortId}": - parameters: - - $ref: "#/components/parameters/StudyId" - - $ref: "#/components/parameters/CohortId" - - $ref: "#/components/parameters/CohortRevisionId" - get: - summary: Get an existing cohort - operationId: getCohort - tags: [Cohorts] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Cohort" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" - patch: - summary: Update an existing cohort - operationId: updateCohort - tags: [Cohorts] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CohortUpdateInfo" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Cohort" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" - delete: - summary: Delete a cohort - operationId: deleteCohort - tags: [Cohorts] - responses: - 204: - description: OK - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + # --------------- Studies --------------- - "/v2/studies/{studyId}/cohorts/{cohortId}/counts": - parameters: - - $ref: "#/components/parameters/StudyId" - - $ref: "#/components/parameters/CohortId" - post: - summary: Run a count query for a cohort - operationId: queryCohortCounts - tags: [Cohorts] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/CohortCountQuery" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/InstanceCountList" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + /v2/studies: + $ref: './studies.yaml#/paths/~1createListStudy' - # --------------- Studies: Reviews --------------- + /v2/studies/{studyId}: + $ref: './studies.yaml#/paths/~1getUpdateDeleteStudy' - "/v2/studies/{studyId}/cohorts/{cohortId}/reviews": - parameters: - - $ref: "#/components/parameters/StudyId" - - $ref: "#/components/parameters/CohortId" - get: - parameters: - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Limit" - summary: List all reviews for a cohort - operationId: listReviews - tags: [Reviews] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ReviewList" - 500: - $ref: "#/components/responses/ServerError" - post: - summary: Create a new review - operationId: createReview - tags: [Reviews] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ReviewCreateInfo" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Review" - 500: - $ref: "#/components/responses/ServerError" + /v2/studies/{studyId}/properties: + $ref: './studies.yaml#/paths/~1updateDeleteStudyProperties' - "/v2/studies/{studyId}/cohorts/{cohortId}/reviews/{reviewId}": - parameters: - - $ref: "#/components/parameters/StudyId" - - $ref: "#/components/parameters/CohortId" - - $ref: "#/components/parameters/ReviewId" - get: - summary: Get an existing review - operationId: getReview - tags: [Reviews] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Review" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" - patch: - summary: Update an existing review - operationId: updateReview - tags: [Reviews] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ReviewUpdateInfo" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Review" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" - delete: - summary: Delete a review - operationId: deleteReview - tags: [Reviews] - responses: - 204: - description: OK - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + # --------------- Studies - Cohorts --------------- - "/v2/studies/{studyId}/cohorts/{cohortId}/reviews/{reviewId}/instances": - parameters: - - $ref: "#/components/parameters/StudyId" - - $ref: "#/components/parameters/CohortId" - - $ref: "#/components/parameters/ReviewId" - post: - summary: List primary entity instances in a review and any associated annotation values - operationId: listReviewInstancesAndAnnotations - tags: [Reviews] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ReviewQuery" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ReviewInstanceListResult" - 500: - $ref: "#/components/responses/ServerError" + /v2/studies/{studyId}/cohorts: + $ref: './cohorts.yaml#/paths/~1createListCohort' - "/v2/studies/{studyId}/cohorts/{cohortId}/reviews/{reviewId}/counts": - parameters: - - $ref: "#/components/parameters/StudyId" - - $ref: "#/components/parameters/CohortId" - - $ref: "#/components/parameters/ReviewId" - post: - summary: Count primary entity instances in a review - operationId: countReviewInstances - tags: [Reviews] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ReviewCountQuery" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/InstanceCountList" - 500: - $ref: "#/components/responses/ServerError" + /v2/studies/{studyId}/cohorts/{cohortId}: + $ref: './cohorts.yaml#/paths/~1getUpdateDeleteCohort' - # --------------- Studies: Annotations --------------- + /v2/studies/{studyId}/cohorts/{cohortId}/counts: + $ref: './cohorts.yaml#/paths/~1queryCohortCounts' - "/v2/studies/{studyId}/cohorts/{cohortId}/annotations": - parameters: - - $ref: "#/components/parameters/StudyId" - - $ref: "#/components/parameters/CohortId" - get: - parameters: - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Limit" - summary: List all annotation keys for a cohort - operationId: listAnnotationKeys - tags: [Annotations] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/AnnotationList" - 500: - $ref: "#/components/responses/ServerError" - post: - summary: Create a new annotation key - operationId: createAnnotationKey - tags: [Annotations] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/AnnotationCreateInfo" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Annotation" - 500: - $ref: "#/components/responses/ServerError" + # --------------- Studies - Cohorts - Reviews --------------- - "/v2/studies/{studyId}/cohorts/{cohortId}/annotations/{annotationId}": - parameters: - - $ref: "#/components/parameters/StudyId" - - $ref: "#/components/parameters/CohortId" - - $ref: "#/components/parameters/AnnotationId" - get: - summary: Get an existing annotation key - operationId: getAnnotationKey - tags: [Annotations] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Annotation" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" - patch: - summary: Update an existing annotation key - operationId: updateAnnotationKey - tags: [Annotations] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/AnnotationUpdateInfo" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Annotation" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" - delete: - summary: Delete an annotation key - operationId: deleteAnnotationKey - tags: [Annotations] - responses: - 204: - description: OK - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + /v2/studies/{studyId}/cohorts/{cohortId}/reviews: + $ref: './reviews.yaml#/paths/~1createListReview' - "/v2/studies/{studyId}/cohorts/{cohortId}/annotations/{annotationId}/reviews/{reviewId}/values/{instanceId}": - parameters: - - $ref: "#/components/parameters/StudyId" - - $ref: "#/components/parameters/CohortId" - - $ref: "#/components/parameters/AnnotationId" - - $ref: "#/components/parameters/ReviewId" - - $ref: "#/components/parameters/PrimaryEntityInstanceId" - post: - summary: Create or update an annotation value - operationId: updateAnnotationValue - tags: [Annotations] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/Literal" - responses: - 200: - description: OK - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" - delete: - summary: Delete an annotation value - operationId: deleteAnnotationValues - tags: [Annotations] - responses: - 204: - description: OK - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + /v2/studies/{studyId}/cohorts/{cohortId}/reviews/{reviewId}: + $ref: './reviews.yaml#/paths/~1getUpdateDeleteReview' - # --------------- Studies: ConceptSets --------------- + /v2/studies/{studyId}/cohorts/{cohortId}/reviews/{reviewId}/instances: + $ref: './reviews.yaml#/paths/~1listReviewInstancesAndAnnotations' - "/v2/studies/{studyId}/conceptSets": - parameters: - - $ref: "#/components/parameters/StudyId" - get: - parameters: - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Limit" - summary: List all concept sets in a study - operationId: listConceptSets - tags: [ConceptSets] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ConceptSetList" - 500: - $ref: "#/components/responses/ServerError" - post: - summary: Create a new concept set - operationId: createConceptSet - tags: [ConceptSets] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ConceptSetCreateInfo" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ConceptSet" - 500: - $ref: "#/components/responses/ServerError" + /v2/studies/{studyId}/cohorts/{cohortId}/reviews/{reviewId}/counts: + $ref: './reviews.yaml#/paths/~1countReviewInstances' - "/v2/studies/{studyId}/conceptSets/{conceptSetId}": - parameters: - - $ref: "#/components/parameters/StudyId" - - $ref: "#/components/parameters/ConceptSetId" - get: - summary: Get an existing concept set - operationId: getConceptSet - tags: [ConceptSets] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ConceptSet" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" - patch: - summary: Update an existing concept set - operationId: updateConceptSet - tags: [ConceptSets] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ConceptSetUpdateInfo" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ConceptSet" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" - delete: - summary: Delete a concept set - operationId: deleteConceptSet - tags: [ConceptSets] - responses: - 204: - description: OK - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + # --------------- Studies - Cohorts - Annotations --------------- - # --------------- Underlays: Export --------------- + /v2/studies/{studyId}/cohorts/{cohortId}/annotations: + $ref: './annotations.yaml#/paths/~1createListAnnotationKey' - "/v2/underlays/{underlayName}/exportModels": - parameters: - - $ref: "#/components/parameters/UnderlayName" - get: - summary: List the available export models - operationId: listExportModels - tags: [Export] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ExportModelList" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + /v2/studies/{studyId}/cohorts/{cohortId}/annotations/{annotationId}: + $ref: './annotations.yaml#/paths/~1getUpdateDeleteAnnotationKey' - "/v2/underlays/{underlayName}/entities/{entityName}/previewExport": - parameters: - - $ref: "#/components/parameters/UnderlayName" - - $ref: "#/components/parameters/EntityName" - post: - summary: List entity instances that will be included in an export - operationId: previewExportInstances - tags: [Export] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ExportPreviewRequest" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/InstanceListResult" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + /v2/studies/{studyId}/cohorts/{cohortId}/annotations/{annotationId}/reviews/{reviewId}/values/{instanceId}: + $ref: './annotations.yaml#/paths/~1createDeleteAnnotationValue' - "/v2/underlays/{underlayName}/describeExport": - parameters: - - $ref: "#/components/parameters/UnderlayName" - post: - summary: Describe the entities and attributes that will be included in an export - operationId: describeExport - tags: [Export] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ExportPreviewRequest" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/EntityOutputPreviewList" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + # --------------- Studies - ConceptSets --------------- - "/v2/underlays/{underlayName}/export": - parameters: - - $ref: "#/components/parameters/UnderlayName" - post: - summary: Export entity instances and review annotations - operationId: exportInstancesAndAnnotations - tags: [Export] - requestBody: - required: true - content: - application/json: - schema: - $ref: "#/components/schemas/ExportRequest" - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ExportResult" - 404: - $ref: "#/components/responses/NotFound" - 500: - $ref: "#/components/responses/ServerError" + /v2/studies/{studyId}/conceptSets: + $ref: './conceptSets.yaml#/paths/~1createListConceptSet' + + /v2/studies/{studyId}/cohorts/{conceptSetId}: + $ref: './conceptSets.yaml#/paths/~1getUpdateDeleteConceptSet' # --------------- Activity log --------------- - "/v2/activityLogEntries": - parameters: - - $ref: "#/components/parameters/ActivityLogFilterUserEmail" - - $ref: "#/components/parameters/ActivityLogFilterExactMatch" - - $ref: "#/components/parameters/ActivityLogFilterResourceType" - - $ref: "#/components/parameters/ActivityLogFilterActivityType" - - $ref: "#/components/parameters/Offset" - - $ref: "#/components/parameters/Limit" - get: - summary: List the activity log entries - operationId: listActivityLogEntries - tags: [ActivityLog] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ActivityLogEntryList" - 500: - $ref: "#/components/responses/ServerError" + /v2/activityLogEntries: + $ref: './activityLog.yaml#/paths/~1listActivityLogEntries' - "/v2/activityLogEntries/{activityLogEntryId}": - parameters: - - $ref: "#/components/parameters/ActivityLogEntryId" - get: - summary: Get an activity log entry - operationId: getActivityLogEntry - tags: [ActivityLog] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ActivityLogEntry" - 500: - $ref: "#/components/responses/ServerError" + /v2/activityLogEntries/{activityLogEntryId}: + $ref: './activityLog.yaml#/paths/~1getActivityLogEntry' # --------------- (Misc) Test --------------- /v2/vumc-admin-service-test: - get: - description: Temporary endpoint to test service-to-service communication with the VUMC admin service. - operationId: vumcAdminServiceTest - tags: [Test] - responses: - 200: - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/VumcAdminServiceTest" - 401: - description: Unauthorized - 500: - $ref: "#/components/responses/ServerError" + $ref: './test.yaml#/paths/~1vumcAdminServiceTest' components: - parameters: - UnderlayName: - name: underlayName - in: path - description: Name of the underlay - required: true - schema: - type: string - - EntityName: - name: entityName - in: path - description: Name of the entity - required: true - schema: - type: string - - StudyId: - name: studyId - in: path - description: ID of the study - required: true - schema: - type: string - - CohortId: - name: cohortId - in: path - description: ID of the cohort - required: true - schema: - type: string - - CohortRevisionId: - name: cohortRevisionId - in: query - description: ID of the cohort revision - required: false - schema: - type: string - - ConceptSetId: - name: conceptSetId - in: path - description: ID of the concept set - required: true - schema: - type: string - - ReviewId: - name: reviewId - in: path - description: ID of the review - required: true - schema: - type: string - - AnnotationId: - name: annotationId - in: path - description: ID of the annotation - required: true - schema: - type: string - - PrimaryEntityInstanceId: - name: instanceId - in: path - description: ID of the primary entity instance that the annotation value is associated with - required: true - schema: - type: string - - Offset: - name: offset - in: query - description: The number of items to skip before starting to collect the result set. - required: false - schema: - type: integer - minimum: 0 - default: 0 - - Limit: - name: limit - in: query - description: The maximum number of items to return. Defaults to 50. - required: false - schema: - type: integer - minimum: 1 - default: 50 - - StudyFilterDisplayName: - name: displayName - in: query - description: Text search on the study display name - required: false - schema: - type: string - - StudyFilterDescription: - name: description - in: query - description: Text search on the study description - required: false - schema: - type: string - - StudyFilterCreatedBy: - name: createdBy - in: query - description: Text search on the study created by email - required: false - schema: - type: string - - StudyFilterIncludeDeleted: - name: includeDeleted - in: query - description: True to include studies that have been deleted - required: false - schema: - type: boolean - - StudyFilterProperties: - name: properties - in: query - description: Text search on the study metadata properties. The list must alternate key1, value1, key2, value2. - required: false - schema: - type: array - items: - type: string - - ActivityLogFilterUserEmail: - name: userEmail - in: query - description: Text search on the activity log entry user email - required: false - schema: - type: string - - ActivityLogFilterExactMatch: - name: exactMatch - in: query - description: True if the user email filter should check for an exact match - required: false - schema: - type: boolean - default: false - - ActivityLogFilterResourceType: - name: resourceType - in: query - description: Filter on the activity log entry resource type - required: false - schema: - $ref: "#/components/schemas/ResourceType" - - ActivityLogFilterActivityType: - name: activityType - in: query - description: Filter on the activity log entry activity type - required: false - schema: - $ref: "#/components/schemas/ActivityType" - - ActivityLogEntryId: - name: activityLogEntryId - in: path - description: ID of the activity log entry - required: true - schema: - type: string - - responses: - NotFound: - description: Not found (or unauthorized) - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorReport" - - ServerError: - description: Server error - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorReport" - - schemas: - SystemVersion: - type: object - required: [gitTag, gitHash, github, build] - properties: - gitTag: - type: string - description: Git tag of currently deployed app. - gitHash: - type: string - description: Git hash of currently deployed app. - github: - type: string - description: Github link to currently deployed commit. - build: - type: string - description: Version of the currently deployed app declared in build.gradle. Client and server versions are linked. - - UserProfile: - type: object - description: User profile - properties: - email: - type: string - subjectId: - type: string - required: - - email - - subjectId - - UnderlaySummary: - type: object - description: Underlay summary - properties: - name: - description: Name - type: string - displayName: - description: Display name - type: string - description: - description: Description - type: string - primaryEntity: - description: Primary entity name - type: string - required: - - name - - displayName - - primaryEntity - - UnderlaySummaryList: - type: object - description: List of underlay summaries - properties: - underlays: - type: array - items: - $ref: "#/components/schemas/UnderlaySummary" - - UnderlaySerializedConfiguration: - type: object - description: Contents of the underlay config files - properties: - underlay: - description: Contents of the underlay.json file - type: string - entities: - description: Contents of the entity.json files - type: array - items: - type: string - groupItemsEntityGroups: - description: Contents of the group-items type entityGroup.json files - type: array - items: - type: string - criteriaOccurrenceEntityGroups: - description: Contents of the criteria-occurrence type entityGroup.json files - type: array - items: - type: string - criteriaSelectors: - description: Contents of the criteria selector json files - type: array - items: - type: string - prepackagedDataFeatures: - description: Contents of the prepackaged data feature json files - type: array - items: - type: string - visualizations: - description: Contents of the visualization json files - type: array - items: - type: string - required: - - underlay - - entities - - groupItemsEntityGroups - - criteriaOccurrenceEntityGroups - - Underlay: - type: object - description: Underlay - properties: - summary: - $ref: "#/components/schemas/UnderlaySummary" - serializedConfiguration: - $ref: "#/components/schemas/UnderlaySerializedConfiguration" - # TODO: Remove this uiConfiguration property from the service API once the UI config overhaul is done. - uiConfiguration: - description: UI configuration - type: string - required: - - summary - - serializedConfiguration - - uiConfiguration - - Entity: - type: object - description: Entity - properties: - name: - description: Name - type: string - idAttribute: - description: ID attribute name - type: string - attributes: - description: List of attributes - type: array - items: - $ref: "#/components/schemas/Attribute" - required: - - name - - idAttribute - - EntityList: - type: object - description: List of entities - properties: - entities: - type: array - items: - $ref: "#/components/schemas/Entity" - - Attribute: - type: object - description: Entity attribute - properties: - name: - description: Name - type: string - type: - description: Attribute type - type: string - enum: ["SIMPLE", "KEY_AND_DISPLAY"] - dataType: - $ref: "#/components/schemas/DataType" - - ValueDisplay: - type: object - description: Attribute value and optional display string - properties: - value: - $ref: "#/components/schemas/Literal" - display: - type: string - description: Optional display string - nullable: true - - Literal: - type: object - description: Union of references to each value type. Exactly one will be populated based on the dataType. - nullable: true - properties: - dataType: - $ref: "#/components/schemas/DataType" - valueUnion: - type: object - properties: - boolVal: - type: boolean - int64Val: - type: integer - format: int64 - stringVal: - type: string - dateVal: - type: string - description: Format YYYY-MM-DD - timestampVal: - type: string - description: Format YYYY-MM-DD hh:mm:ss - doubleVal: - type: number - format: double - - DataType: - type: string - enum: ["INT64", "STRING", "BOOLEAN", "DATE", "TIMESTAMP", "DOUBLE"] - - Query: - type: object - description: Query for entity instances - properties: - includeAttributes: - description: Attributes to include in the returned instances - type: array - items: - type: string - includeHierarchyFields: - description: Hierarchy fields to include in the returned instances. All fields will be returned for each hierarchy specified. - type: object - properties: - hierarchies: - type: array - description: Hierarchy names - items: - type: string - fields: - type: array - items: - type: string - enum: ["IS_MEMBER", "PATH", "NUM_CHILDREN", "IS_ROOT"] - includeRelationshipFields: - description: Relationship (count) fields to include in the returned instances. - type: array - items: - type: object - description: Related entity and optional hierarchies. Per-node rollups are always returned. - properties: - relatedEntity: - type: string - hierarchies: - type: array - description: Hierarchy names - items: - type: string - filter: - $ref: "#/components/schemas/Filter" - orderBys: - type: array - description: Attributes and direction to order the results by - items: - type: object - description: Attribute or relationship (count) field and the direction - properties: - attribute: - type: string - relationshipField: - type: object - properties: - relatedEntity: - type: string - hierarchy: - type: string - direction: - $ref: "#/components/schemas/OrderByDirection" - limit: - $ref: "#/components/schemas/Limit" - pageSize: - $ref: "#/components/schemas/PageSize" - pageMarker: - $ref: "#/components/schemas/PageMarker" - - QueryFilterOnPrimaryEntity: - type: object - description: Query for entity instances filtered for a single primary entity id - properties: - includeAttributes: - description: | - Attributes to include in the returned instances. - Empty array means to include all attributes. - type: array - items: - type: string - orderBys: - type: array - description: Attributes and direction to order the results by - items: - type: object - description: Attribute field and the direction - properties: - attribute: - type: string - direction: - $ref: "#/components/schemas/OrderByDirection" - primaryEntityId: - $ref: "#/components/schemas/Literal" - pageSize: - $ref: "#/components/schemas/PageSize" - pageMarker: - $ref: "#/components/schemas/PageMarker" - required: - - includeAttributes - - orderBys - - primaryEntityId - - CountQuery: - type: object - description: Count entity instances - properties: - attributes: - description: | - Attributes to group by. One count will be returned for each possible combination of attribute values - (e.g. [gender, hair_color] will return counts for man+red, man+black, woman+red, woman+black). - type: array - items: - type: string - filter: - $ref: "#/components/schemas/Filter" - pageSize: - $ref: "#/components/schemas/PageSize" - pageMarker: - $ref: "#/components/schemas/PageMarker" - - HintQuery: - type: object - description: Get display hints - properties: - relatedEntity: - description: | - Optional related entity. - If specified, then we return hints computed across related instances (e.g. condition occurrences where condition id=11). - Otherwise, we return hints computed across all instances (e.g. all persons). - type: object - properties: - name: - type: string - description: Related entity name - id: - $ref: "#/components/schemas/Literal" - - CohortCountQuery: - type: object - description: Count output entity instances for a cohort filter - properties: - criteriaGroupSectionId: - type: string - criteriaGroupId: - type: string - entity: - description: Entity to count. Defaults to primary entity. - type: string - countDistinctAttribute: - description: | - Attribute to count (e.g. person_id will return counts for the number of distinct person_ids - per group by combination). Defaults to id attribute. - type: string - groupByAttributes: - description: | - Attributes to group by. One count will be returned for each possible combination of attribute values - (e.g. [gender, hair_color] will return counts for man+red, man+black, woman+red, woman+black). - type: array - items: - type: string - orderByDirection: - $ref: "#/components/schemas/OrderByDirection" - limit: - type: integer - pageSize: - $ref: "#/components/schemas/PageSize" - pageMarker: - $ref: "#/components/schemas/PageMarker" - required: - - groupByAttributes - - ReviewQuery: - type: object - description: Query for review instances and annotations - properties: - includeAttributes: - description: Attributes to include in the returned instances - type: array - items: - type: string - entityFilter: - $ref: "#/components/schemas/Filter" - annotationFilter: - $ref: "#/components/schemas/AnnotationFilter" - orderBys: - type: array - description: Attributes or annotations, and direction to order the results by - items: - type: object - description: Attribute or annotation and the direction - properties: - attribute: - type: string - description: Name of the attribute - annotation: - type: string - description: ID of the annotation - direction: - $ref: "#/components/schemas/OrderByDirection" - limit: - $ref: "#/components/schemas/Limit" - pageSize: - $ref: "#/components/schemas/PageSize" - pageMarker: - $ref: "#/components/schemas/PageMarker" - - ReviewCountQuery: - type: object - description: Count review instances - properties: - attributes: - description: | - Attributes to group by. One count will be returned for each possible combination of attribute values - (e.g. [gender, hair_color] will return counts for man+red, man+black, woman+red, woman+black). - type: array - items: - type: string - - Filter: - type: object - description: Union of references to each filter type. Exactly one should be specified based on the filterType. - nullable: true - properties: - filterType: - type: string - enum: - [ - "ATTRIBUTE", - "TEXT", - "HIERARCHY", - "RELATIONSHIP", - "BOOLEAN_LOGIC", - "ITEM_IN_GROUP", - "GROUP_HAS_ITEMS", - "OCCURRENCE_FOR_PRIMARY", - "PRIMARY_WITH_CRITERIA", - ] - filterUnion: - type: object - properties: - attributeFilter: - $ref: "#/components/schemas/AttributeFilter" - textFilter: - $ref: "#/components/schemas/TextFilter" - hierarchyFilter: - $ref: "#/components/schemas/HierarchyFilter" - relationshipFilter: - $ref: "#/components/schemas/RelationshipFilter" - booleanLogicFilter: - $ref: "#/components/schemas/BooleanLogicFilter" - itemInGroupFilter: - $ref: "#/components/schemas/ItemInGroupFilter" - groupHasItemsFilter: - $ref: "#/components/schemas/GroupHasItemsFilter" - occurrenceForPrimaryFilter: - $ref: "#/components/schemas/OccurrenceForPrimaryFilter" - primaryWithCriteriaFilter: - $ref: "#/components/schemas/PrimaryWithCriteriaFilter" - - AttributeFilter: - type: object - description: Filter on an attribute value (e.g. color=red) - properties: - attribute: - type: string - operator: - type: string - enum: - [ - "IS_NULL", - "IS_NOT_NULL", - "IS_EMPTY_STRING", - "EQUALS", - "NOT_EQUALS", - "LESS_THAN", - "GREATER_THAN", - "LESS_THAN_OR_EQUAL", - "GREATER_THAN_OR_EQUAL", - "IN", - "NOT_IN", - "BETWEEN", - ] - values: - type: array - items: - $ref: "#/components/schemas/Literal" - - TextFilter: - type: object - description: Filter on a text search (e.g. person sounds like Joe) - properties: - matchType: - type: string - enum: ["EXACT_MATCH", "FUZZY_MATCH"] - attribute: - type: string - description: | - Attribute to match on. If not specified, then we match on whatever is specified in the text search mapping config. - Currently, fuzzy match only works on a single attribute (i.e. you must specify this field for fuzzy match). - text: - type: string - - HierarchyFilter: - type: object - description: Filter on a hierarchy (e.g. descendant of id=12) - properties: - hierarchy: - description: Name of the hierarchy - type: string - operator: - type: string - enum: ["CHILD_OF", "DESCENDANT_OF_INCLUSIVE", "IS_ROOT", "IS_MEMBER"] - values: - type: array - items: - $ref: "#/components/schemas/Literal" - - RelationshipFilter: - type: object - description: | - Filter on a relationship between entities (e.g. condition occurrences where condition=diabetes). - If the group_by_count_operator is set, then the group_by_count_value must also be set. - The group_by_count_attribute is optional. If undefined, we group by the id only. - When group_by fields are set, we filter on # of related entity instances. - e.g. filter person instances with >2 related condition_occurrence instances - properties: - entity: - type: string - subfilter: - $ref: "#/components/schemas/Filter" - groupByCountAttributes: - type: array - items: - type: string - groupByCountOperator: - $ref: "#/components/schemas/BinaryOperator" - groupByCountValue: - type: integer - nullable: true - - BooleanLogicFilter: - type: object - description: | - Compose multiple filters (e.g. color=red AND capacity=3, NOT color=red). - The NOT operator only allows a single subfilter. The OR and AND operators require more than one subfilter. - properties: - operator: - type: string - enum: ["AND", "OR", "NOT"] - subfilters: - type: array - items: - $ref: "#/components/schemas/Filter" - - ItemInGroupFilter: - type: object - required: [entityGroup] - description: | - Filter an items entity with a group-items entity group. (e.g. ingredients in a brand, - blood pressure readings for a person). - If the groupByCountOperator is set, then the groupByCountValue must also be set. - The groupByCountAttribute is optional. If undefined, we group by the id only. - When group by fields are set, we filter on the number of related entity instances. - e.g. filter ingredients that are included in >2 brands - properties: - entityGroup: - type: string - groupSubfilter: - $ref: "#/components/schemas/Filter" - groupByCountAttributes: - type: array - items: - type: string - groupByCountOperator: - $ref: "#/components/schemas/BinaryOperator" - groupByCountValue: - type: integer - - GroupHasItemsFilter: - type: object - required: [entityGroup] - description: | - Filter a group entity with any related items entities using a group-items entity group. - (e.g. brand with at least one ingredient, person with at least one blood pressure reading). - properties: - entityGroup: - type: string - itemsSubfilter: - $ref: "#/components/schemas/Filter" - groupByCountAttributes: - type: array - items: - type: string - groupByCountOperator: - $ref: "#/components/schemas/BinaryOperator" - groupByCountValue: - type: integer - - OccurrenceForPrimaryFilter: - type: object - required: [entityGroup, occurrenceEntity] - description: | - Filters an occurrence entity with a criteria-occurrence entity group (e.g. condition - occurrences for people with gender=female, condition=diabetes). - properties: - entityGroup: - type: string - occurrenceEntity: - type: string - primarySubfilter: - $ref: "#/components/schemas/Filter" - criteriaSubfilter: - $ref: "#/components/schemas/Filter" - - PrimaryWithCriteriaFilter: - type: object - required: [entityGroup] - description: | - Filter the primary entity with a criteria-occurrence entity group (e.g. people where - condition=diabetes and visit_type=inpatient). - If the groupByCountOperator is set, then the groupByCountValue must also be set. - The groupByCountAttributes are optional. If undefined, we group by the id only. - When group by fields are set, we filter on the number of related occurrence instances. - e.g. filter person instances with >2 related condition_occurrence instances - properties: - entityGroup: - type: string - criteriaSubfilter: - $ref: "#/components/schemas/Filter" - occurrenceSubfiltersAndGroupByAttributes: - type: object - description: | - Set of sub-filter and group by attributes per occurrence entity. - Map key is the occurrence entity name. - additionalProperties: - type: object - properties: - subfilters: - type: array - items: - $ref: "#/components/schemas/Filter" - group_by_count_attributes: - type: array - items: - type: string - groupByCountOperator: - $ref: "#/components/schemas/BinaryOperator" - groupByCountValue: - type: integer - - AnnotationFilter: - type: object - description: Filter on an annotation value (e.g. reviewStatus=complete) - properties: - annotation: - type: string - operator: - type: string - enum: ["EQUALS", "NOT_EQUALS", "LESS_THAN", "GREATER_THAN"] - value: - $ref: "#/components/schemas/Literal" - - OrderByDirection: - type: string - description: Defaults to ascending - enum: ["ASCENDING", "DESCENDING"] - - Limit: - type: integer - description: Maximum number of results to return. Defaults to 250. - default: 250 - - Instance: - type: object - properties: - attributes: - description: A map of entity attribute names to their value for this instance. Only the attributes requested are populated. - type: object - additionalProperties: - $ref: "#/components/schemas/ValueDisplay" - hierarchyFields: - description: Hierarchy field values for this instance. One set of values per hierarchy. Only the values requested are populated. - type: array - items: - type: object - properties: - hierarchy: - type: string - isMember: - type: boolean - path: - type: string - numChildren: - type: integer - isRoot: - type: boolean - relationshipFields: - description: Relationship field values for this instance. Only the values requested are populated. - type: array - items: - type: object - properties: - relatedEntity: - type: string - hierarchy: - type: string - count: - type: integer - displayHints: - type: string - - InstanceListResult: - type: object - description: List of instances - properties: - sql: - type: string - instances: - type: array - items: - $ref: "#/components/schemas/Instance" - pageMarker: - $ref: "#/components/schemas/PageMarker" - numRowsAcrossAllPages: - $ref: "#/components/schemas/NumRowsAcrossAllPages" - - InstanceCount: - type: object - properties: - count: - type: integer - attributes: - description: A map of entity attribute names to their value for this group - type: object - additionalProperties: - $ref: "#/components/schemas/ValueDisplay" - - InstanceCountList: - type: object - description: List of instance counts - properties: - sql: - type: string - instanceCounts: - type: array - items: - $ref: "#/components/schemas/InstanceCount" - pageMarker: - $ref: "#/components/schemas/PageMarker" - numRowsAcrossAllPages: - $ref: "#/components/schemas/NumRowsAcrossAllPages" - - DisplayHint: - type: object - description: Display hint for entity attribute - properties: - attribute: - $ref: "#/components/schemas/Attribute" - displayHint: - type: object - description: Display hint calculated from source data - properties: - enumHint: - $ref: "#/components/schemas/DisplayHintEnum" - numericRangeHint: - $ref: "#/components/schemas/DisplayHintNumericRange" - - DisplayHintEnum: - type: object - description: Enumeration of possible values, display strings, and counts - properties: - enumHintValues: - type: array - items: - type: object - description: Enum value and count - properties: - enumVal: - $ref: "#/components/schemas/ValueDisplay" - count: - type: integer - - DisplayHintNumericRange: - type: object - description: Maximum and minimum values - properties: - min: - description: Max value - type: number - format: double - max: - description: Min value - type: number - format: double - - DisplayHintList: - type: object - description: List of display hints - properties: - sql: - type: string - displayHints: - type: array - items: - $ref: "#/components/schemas/DisplayHint" - - Study: - type: object - required: [id, created, createdBy, lastModified] - properties: - id: - $ref: "#/components/schemas/StudyId" - displayName: - $ref: "#/components/schemas/StudyDisplayName" - description: - $ref: "#/components/schemas/StudyDescription" - properties: - $ref: "#/components/schemas/Properties" - created: - type: string - format: date-time - createdBy: - description: Email of user who created the study - type: string - lastModified: - type: string - format: date-time - isDeleted: - type: boolean - nullable: false - - StudyList: - type: array - items: - $ref: "#/components/schemas/Study" - - StudyCreateInfo: - type: object - properties: - id: - $ref: "#/components/schemas/StudyId" - displayName: - $ref: "#/components/schemas/StudyDisplayName" - description: - $ref: "#/components/schemas/StudyDescription" - properties: - $ref: "#/components/schemas/Properties" - - StudyUpdateInfo: - type: object - properties: - displayName: - $ref: "#/components/schemas/StudyDisplayName" - description: - $ref: "#/components/schemas/StudyDescription" - - StudyId: - type: string - description: ID of the study, immutable - - StudyDisplayName: - type: string - description: Human readable name of the study - - StudyDescription: - type: string - description: Description of the study - - Properties: - description: List of key-value pairs of strings - type: array - items: - $ref: "#/components/schemas/PropertyKeyValue" - - # There seems to be a bug in the TS code generator that fails to create - # proper objects for these when they're nested directy inside Properties. - # It instead leaves them as untyped "object". My best guess is that it's - # cause by having an array as the top level object, and it fails to generate - # a nested type for that case like for nested objects under other objects. - # I've moved it out into a separate top level type as a workaround. - PropertyKeyValue: - type: object - required: [key, value] - properties: - key: - description: | - String to identify the key. Keys must be 1-1024 characters, using letters, - numbers, dashes, and underscores and must not start with a dash or underscore. - type: string - value: - description: Arbitrary string value - type: string - - PropertyKeys: - description: List of property keys - type: array - items: - type: string - - Cohort: - type: object - properties: - id: - $ref: "#/components/schemas/CohortId" - revisionId: - $ref: "#/components/schemas/CohortRevisionId" - underlayName: - $ref: "#/components/schemas/UnderlayName" - displayName: - $ref: "#/components/schemas/CohortDisplayName" - description: - $ref: "#/components/schemas/CohortDescription" - criteriaGroupSections: - type: array - description: Criteria group sections that define the entity filter - items: - $ref: "#/components/schemas/CriteriaGroupSection" - created: - description: Timestamp of when the cohort was created - type: string - format: date-time - createdBy: - description: Email of user who created cohort - type: string - lastModified: - description: Timestamp of when the cohort was last modified - type: string - format: date-time - isDeleted: - type: boolean - required: - - id - - underlayName - - displayName - - criteriaGroups - - created - - createdBy - - lastModified - - CohortList: - type: array - items: - $ref: "#/components/schemas/Cohort" - - CohortId: - type: string - description: ID of the cohort, immutable - - CohortRevisionId: - type: string - description: ID of a frozen cohort revision, immutable - - CohortCreateInfo: - type: object - properties: - underlayName: - $ref: "#/components/schemas/UnderlayName" - displayName: - $ref: "#/components/schemas/CohortDisplayName" - description: - $ref: "#/components/schemas/CohortDescription" - - CohortUpdateInfo: - type: object - properties: - displayName: - $ref: "#/components/schemas/CohortDisplayName" - description: - $ref: "#/components/schemas/CohortDescription" - criteriaGroupSections: - type: array - description: Criteria group sections that define the entity filter - items: - $ref: "#/components/schemas/CriteriaGroupSection" - - CohortDisplayName: - type: string - description: Human readable name of the cohort - - CohortDescription: - type: string - description: Description of the cohort - - ConceptSet: - type: object - properties: - id: - $ref: "#/components/schemas/ConceptSetId" - underlayName: - $ref: "#/components/schemas/UnderlayName" - displayName: - $ref: "#/components/schemas/ConceptSetDisplayName" - description: - $ref: "#/components/schemas/ConceptSetDescription" - criteria: - type: array - description: Criteria that define the entity filter - items: - $ref: "#/components/schemas/Criteria" - entityOutputs: - type: array - description: Outputs per entity - items: - $ref: "#/components/schemas/EntityOutput" - created: - description: Timestamp of when the concept set was created - type: string - format: date-time - createdBy: - description: Email of user who created the concept set - type: string - lastModified: - description: Timestamp of when the concept set was last modified - type: string - format: date-time - required: - - id - - underlayName - - displayName - - criteria - - entityOutputs - - created - - createdBy - - lastModified - - EntityOutput: - type: object - properties: - entity: - description: Entity name - type: string - excludeAttributes: - type: array - description: Names of attributes to exclude from output - items: - type: string - required: - - entity - - ConceptSetList: - type: array - items: - $ref: "#/components/schemas/ConceptSet" - - ConceptSetId: - type: string - description: ID of the concept set, immutable - - ConceptSetCreateInfo: - type: object - properties: - underlayName: - $ref: "#/components/schemas/UnderlayName" - displayName: - $ref: "#/components/schemas/ConceptSetDisplayName" - description: - $ref: "#/components/schemas/ConceptSetDescription" - - ConceptSetUpdateInfo: - type: object - properties: - displayName: - $ref: "#/components/schemas/ConceptSetDisplayName" - description: - $ref: "#/components/schemas/ConceptSetDescription" - criteria: - type: array - description: Criteria that define the entity filter - items: - $ref: "#/components/schemas/Criteria" - entityOutputs: - type: array - description: Outputs per entity - items: - $ref: "#/components/schemas/EntityOutput" - - ConceptSetDisplayName: - type: string - description: Human readable name of the concept set - - ConceptSetDescription: - type: string - description: Description of the concept set - - UnderlayName: - type: string - description: Name of the underlay, immutable - - CriteriaGroupSection: - type: object - description: Section of criteria groups and boolean logic operators to combine them - properties: - id: - type: string - description: ID of the section, immutable - displayName: - type: string - description: Name of the section - criteriaGroups: - type: array - description: | - For a temporal section, this is the set of groups that define the first block. - For a non-temporal section, the set of groups are the union of this list and the secondBlockCriteriaGroups list. - items: - $ref: "#/components/schemas/CriteriaGroup" - firstBlockReducingOperator: - description: | - Reducing operator for the first block of criteria groups. - Only applies for a temporal section. - $ref: "#/components/schemas/ReducingOperator" - secondBlockCriteriaGroups: - type: array - description: | - For a temporal section, this is the set of groups that define the second block. - For a non-temporal section, the set of groups are the union of this list and the criteriaGroups list. - items: - $ref: "#/components/schemas/CriteriaGroup" - secondBlockReducingOperator: - description: | - Reducing operator for the second block of criteria groups. - Only applies for a temporal section. - $ref: "#/components/schemas/ReducingOperator" - operator: - type: string - description: Operator to use when combining the criteria groups in the section - enum: ["AND", "OR", "DURING_SAME_ENCOUNTER", "NUM_DAYS_BEFORE", "NUM_DAYS_AFTER", "WITHIN_NUM_DAYS"] - operatorValue: - type: integer - description: Value associated with the operator (e.g. num days) - excluded: - type: boolean - description: True to exclude the section, false to include it - required: - - id - - displayName - - criteriaGroups - - operator - - excluded - - ReducingOperator: - type: string - enum: ["ANY", "FIRST_MENTION_OF", "LAST_MENTION_OF"] - - CriteriaGroup: - type: object - description: Group of related criteria (primary + modifiers) - properties: - id: - type: string - description: ID of the group, immutable - displayName: - type: string - description: Name of the group - criteria: - type: array - description: Set of criteria in the group - items: - $ref: "#/components/schemas/Criteria" - required: - - id - - displayName - - criteria - - Criteria: - type: object - description: Single criteria for a cohort or concept set definition - properties: - id: - type: string - description: ID of the criteria, immutable - displayName: - type: string - description: Name of the criteria - pluginName: - type: string - description: Name of the plugin that generated this criteria - pluginVersion: - type: integer - description: Version of the plugin that generated this criteria - predefinedId: - type: string - description: Id of the predefined criteria in the config - selectorOrModifierName: - type: string - description: Name of the selector or modifier used by this config - selectionData: - type: string # JSON formatted, previously base64 Protobuf formatted - description: Serialized plugin-specific representation of the user's selection - uiConfig: - type: string # JSON formatted - description: Serialized plugin-specific UI configuration for the criteria - tags: - description: Unstructured key-value tags for the criteria - type: object - additionalProperties: - type: string - nullable: true - required: - - id - - displayName - - pluginName - - selectionData - - uiConfig - - tags - - Review: - type: object - properties: - id: - $ref: "#/components/schemas/ReviewId" - displayName: - $ref: "#/components/schemas/ReviewDisplayName" - description: - $ref: "#/components/schemas/ReviewDescription" - size: - $ref: "#/components/schemas/ReviewSize" - cohort: - $ref: "#/components/schemas/Cohort" - created: - description: Timestamp of when the review was created - type: string - format: date-time - createdBy: - description: Email of user who created the review - type: string - lastModified: - description: Timestamp of when the review was last modified - type: string - format: date-time - required: - - id - - displayName - - size - - cohortRevision - - created - - createdBy - - lastModified - - ReviewList: - type: array - items: - $ref: "#/components/schemas/Review" - - ReviewCreateInfo: - type: object - properties: - displayName: - $ref: "#/components/schemas/ReviewDisplayName" - description: - $ref: "#/components/schemas/ReviewDescription" - size: - $ref: "#/components/schemas/ReviewSize" - required: - - displayName - - size - - ReviewUpdateInfo: - type: object - properties: - displayName: - $ref: "#/components/schemas/ReviewDisplayName" - description: - $ref: "#/components/schemas/ReviewDescription" - - ReviewId: - type: string - description: ID of the review, immutable - - ReviewDisplayName: - type: string - description: Human readable name of the review - - ReviewDescription: - type: string - description: Description of the review - - ReviewSize: - type: integer - description: Number of primary entity instances included in the review - - Annotation: - type: object - properties: - id: - description: ID of the annotation, immutable - type: string - displayName: - $ref: "#/components/schemas/AnnotationDisplayName" - description: - $ref: "#/components/schemas/AnnotationDescription" - dataType: - $ref: "#/components/schemas/DataType" - enumVals: - type: array - description: | - May only be set if dataType=STRING. Annotation value must be one of - enumVals. - items: - type: string - required: - - id - - displayName - - dataType - - AnnotationList: - type: array - items: - $ref: "#/components/schemas/Annotation" - - AnnotationCreateInfo: - type: object - properties: - displayName: - $ref: "#/components/schemas/AnnotationDisplayName" - description: - $ref: "#/components/schemas/AnnotationDescription" - dataType: - $ref: "#/components/schemas/DataType" - enumVals: - type: array - description: | - May only be set if dataType=STRING. Annotation value must be one of - enumVals. - items: - type: string - required: - - displayName - - dataType - - AnnotationUpdateInfo: - type: object - properties: - displayName: - $ref: "#/components/schemas/AnnotationDisplayName" - description: - $ref: "#/components/schemas/AnnotationDescription" - - AnnotationDisplayName: - type: string - description: Human readable name of the annotation - maxLength: 35 - - AnnotationDescription: - type: string - description: Description of the annotation - - AnnotationValue: - type: object - properties: - instanceId: - description: ID of the annotation value, immutable - type: string - value: - $ref: "#/components/schemas/Literal" - isMostRecent: - type: boolean - isPartOfSelectedReview: - type: boolean - required: - - instanceId - - value - - isMostRecent - - isPartOfSelectedReview - - ReviewInstance: - type: object - properties: - stableIndex: - description: Index of the instance, unchanged when sorting - type: integer - attributes: - description: | - A map of entity attribute names to their value for this instance. The id attribute will always be included. - type: object - additionalProperties: - $ref: "#/components/schemas/ValueDisplay" - annotations: - description: A map of annotation ids to their values for this instance in this review - type: object - additionalProperties: - type: array - nullable: true - items: - $ref: "#/components/schemas/AnnotationValue" - - ReviewInstanceListResult: - type: object - description: List of instances - properties: - sql: - type: string - instances: - type: array - items: - $ref: "#/components/schemas/ReviewInstance" - pageMarker: - $ref: "#/components/schemas/PageMarker" - - VumcAdminServiceTest: - type: object - properties: - version: - type: string - round-trip: - type: string - - ExportPreviewRequest: - type: object - properties: - study: - type: string - cohorts: - description: List of cohort ids - type: array - items: - type: string - conceptSets: - description: List of concept set ids - type: array - items: - type: string - limit: - type: integer - includeAllAttributes: - type: boolean - description: | - When true, ignore the selected attributes in the data feature set definitions and include all - attributes for each output entity. - default: false - required: - - study - - cohorts - - conceptSets - - EntityOutputPreview: - type: object - properties: - entity: - description: Entity name - type: string - includedAttributes: - type: array - description: Names of attributes included in the output - items: - type: string - criteria: - type: array - items: - type: object - properties: - conceptSetId: - type: string - criteriaId: - type: string - required: - - conceptSetId - - criteriaId - indexSql: - type: string - description: | - SQL string against the index tables. - This will be populated if source queries are not configured for this entity. - sourceSql: - type: string - description: | - SQL string against the source tables. - This will be populated if source queries are configured for this entity. - required: - - entity - - includedAttributes - - criteria - - EntityOutputPreviewList: - type: object - properties: - entityOutputs: - type: array - items: - $ref: "#/components/schemas/EntityOutputPreview" - required: - - entityOutputs - - ExportRequest: - type: object - properties: - exportModel: - description: Name of the export model to use - type: string - inputs: - description: Key-value map of the export model inputs (e.g. filenamePrefix=test) - type: object - additionalProperties: - type: string - nullable: true - redirectBackUrl: - type: string - nullable: true - study: - type: string - nullable: false - cohorts: - description: List of cohort ids - type: array - items: - type: string - conceptSets: - description: List of concept set ids - type: array - items: - type: string - includeAnnotations: - description: Include the annotation data when true - type: boolean - - ExportResult: - type: object - properties: - status: - type: string - enum: ["SUCCEEDED", "FAILED"] - redirectAwayUrl: - type: string - outputs: - # TODO: Remove this outputs property from the service API once the UI is using the links. - description: Key-value map of output data generated by the export model - type: object - additionalProperties: - type: string - links: - description: Output link results generated by the export model - type: array - items: - $ref: "#/components/schemas/ExportLinkResult" - error: - description: Error message if this export failed outside of individual link generation - type: string - required: - - status - - outputs - - links - - ExportLinkResult: - type: object - properties: - displayName: - type: string - url: - type: string - tags: - description: | - Ordered list of tags that indicate how this link result should be displayed to the user. - The first tag is the top-level section, the second tag is a sub-section, etc. - e.g. ["Annotations", "Cohort 123"] means this link result will be displayed in the Annotations - section, Cohort 123 sub-section. - type: array - items: - type: string - message: - description: Optional message (e.g. "No entity data. File not generated."). - type: string - error: - description: Error message if generating this link result failed. - type: string - required: - - tags - - ExportModel: - type: object - properties: - name: - type: string - nullable: false - displayName: - type: string - nullable: false - description: - type: string - nullable: true - numPrimaryEntityCap: - description: Maximum number of primary entity instances, across all selected cohorts, that this model can export. - type: integer - inputs: - description: Map of input parameter names to descriptions - type: object - additionalProperties: - type: string - nullable: true - outputs: - description: Map of output parameters names to descriptions - type: object - additionalProperties: - type: string - nullable: true - - ExportModelList: - type: array - items: - $ref: "#/components/schemas/ExportModel" - - ResourceType: - type: string - enum: ["STUDY", "COHORT", "REVIEW"] - - ResourceObject: - type: object - properties: - type: - $ref: "#/components/schemas/ResourceType" - studyId: - $ref: "#/components/schemas/StudyId" - studyDisplayName: - $ref: "#/components/schemas/StudyDisplayName" - studyProperties: - $ref: "#/components/schemas/Properties" - cohortId: - $ref: "#/components/schemas/CohortId" - cohortDisplayName: - $ref: "#/components/schemas/CohortDisplayName" - cohortRevisionId: - $ref: "#/components/schemas/CohortRevisionId" - reviewId: - $ref: "#/components/schemas/ReviewId" - reviewDisplayName: - $ref: "#/components/schemas/ReviewDisplayName" - required: - - type - - studyId - - ActivityType: - type: string - enum: - [ - "CREATE_STUDY", - "DELETE_STUDY", - "CREATE_COHORT", - "DELETE_COHORT", - "EXPORT_COHORT", - "CREATE_REVIEW", - "DELETE_REVIEW", - ] - - ActivityLogEntry: - type: object - properties: - id: - type: string - nullable: false - userEmail: - type: string - nullable: false - logged: - type: string - format: date-time - nullable: false - systemVersion: - $ref: "#/components/schemas/SystemVersion" - activityType: - $ref: "#/components/schemas/ActivityType" - resources: - type: array - items: - $ref: "#/components/schemas/ResourceObject" - additionalInfo: - description: Additional information for specific activity types - type: object - properties: - exportModel: - description: (EXPORT_COHORT) Name of the export model used - type: string - nullable: true - recordsCount: - description: (EXPORT_COHORT, CREATE_REVIEW) Number of primary entity records involved - type: integer - format: int64 - nullable: true - required: - - id - - userEmail - - logged - - systemVersion - - activityType - - ActivityLogEntryList: - type: array - items: - $ref: "#/components/schemas/ActivityLogEntry" - - ErrorReport: - type: object - required: [message, statusCode, causes] - properties: - message: - type: string - statusCode: - type: integer - causes: - type: array - items: - type: string - - PageSize: - type: integer - - PageMarker: - type: string - - NumRowsAcrossAllPages: - type: integer - - BinaryOperator: - type: string - enum: - [ - "EQUALS", - "NOT_EQUALS", - "LESS_THAN", - "GREATER_THAN", - "LESS_THAN_OR_EQUAL", - "GREATER_THAN_OR_EQUAL", - ] - securitySchemes: + bearerAuth: + type: http + scheme: bearer authorization: type: oauth2 flows: @@ -2946,6 +171,3 @@ components: openid: open id authorization email: email authorization profile: profile authorization - bearerAuth: - type: http - scheme: bearer diff --git a/service/src/main/resources/api/studies.yaml b/service/src/main/resources/api/studies.yaml new file mode 100644 index 000000000..f2263d1d7 --- /dev/null +++ b/service/src/main/resources/api/studies.yaml @@ -0,0 +1,259 @@ +# Study APIs, parameters & schema objects + +paths: + /createListStudy: + get: + description: List all studies a user can read + operationId: listStudies + tags: [ Studies ] + parameters: + - $ref: '#/components/parameters/StudyFilterDisplayName' + - $ref: '#/components/parameters/StudyFilterDescription' + - $ref: '#/components/parameters/StudyFilterCreatedBy' + - $ref: '#/components/parameters/StudyFilterIncludeDeleted' + - $ref: '#/components/parameters/StudyFilterProperties' + - $ref: './common.yaml#/components/parameters/Offset' + - $ref: './common.yaml#/components/parameters/Limit' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/StudyList' + 500: + $ref: './common.yaml#/components/responses/ServerError' + post: + description: Create a new study + operationId: createStudy + tags: [ Studies ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/StudyCreateInfo' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Study' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /getUpdateDeleteStudy: + parameters: + - $ref: '#/components/parameters/StudyId' + get: + description: Get an existing study + operationId: getStudy + tags: [ Studies ] + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Study' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + patch: + description: Update an existing study + operationId: updateStudy + tags: [ Studies ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/StudyUpdateInfo' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Study' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + delete: + description: Delete a study + operationId: deleteStudy + tags: [ Studies ] + responses: + 204: + $ref: './common.yaml#/components/responses/NoContent' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /updateDeleteStudyProperties: + parameters: + - $ref: '#/components/parameters/StudyId' + post: + description: Update the properties in a study. Only properties with keys + in request are updated. Properties with keys not in request are not updated + operationId: updateStudyProperties + tags: [ Studies ] + requestBody: + required: true + content: + application/json: + schema: + $ref: './common.yaml#/components/schemas/Properties' + responses: + 204: + $ref: './common.yaml#/components/responses/NoContent' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + patch: + description: Delete properties in a study. Only properties with keys in + request are deleted. Properties with keys not in request are not deleted + operationId: deleteStudyProperties + tags: [ Studies ] + requestBody: + required: true + content: + application/json: + schema: + $ref: './common.yaml#/components/schemas/PropertyKeys' + responses: + 204: + $ref: './common.yaml#/components/responses/NoContent' + 400: + $ref: './common.yaml#/components/responses/BadRequest' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + +components: + parameters: + StudyId: + description: ID of the study + name: studyId + in: path + required: true + schema: + type: string + + StudyFilterDisplayName: + description: Text search on the study display name + name: displayName + in: query + required: false + schema: + type: string + + StudyFilterDescription: + description: Text search on the study description + name: description + in: query + required: false + schema: + type: string + + StudyFilterCreatedBy: + description: Text search on the study created by email + name: createdBy + in: query + required: false + schema: + type: string + + StudyFilterIncludeDeleted: + description: True to include studies that have been deleted + name: includeDeleted + in: query + required: false + schema: + type: boolean + + StudyFilterProperties: + description: Text search on the study metadata properties. The list + must alternate key1, value1, key2, value2 + name: properties + in: query + required: false + schema: + type: array + items: + type: string + + schemas: + StudyList: + type: array + items: + $ref: '#/components/schemas/Study' + + Study: + type: object + required: [ id, created, createdBy, lastModified ] + properties: + id: + $ref: '#/components/schemas/StudyId' + displayName: + $ref: '#/components/schemas/StudyDisplayName' + description: + $ref: '#/components/schemas/StudyDescription' + properties: + $ref: './common.yaml#/components/schemas/Properties' + created: + type: string + format: date-time + createdBy: + description: Email of user who created the study + type: string + lastModified: + type: string + format: date-time + isDeleted: + type: boolean + nullable: false + + StudyId: + description: ID of the study, immutable + type: string + + StudyDisplayName: + description: Human readable name of the study + type: string + + StudyDescription: + description: Description of the study + type: string + + StudyCreateInfo: + type: object + properties: + id: + $ref: '#/components/schemas/StudyId' + displayName: + $ref: '#/components/schemas/StudyDisplayName' + description: + $ref: '#/components/schemas/StudyDescription' + properties: + $ref: './common.yaml#/components/schemas/Properties' + + StudyUpdateInfo: + type: object + properties: + displayName: + $ref: '#/components/schemas/StudyDisplayName' + description: + $ref: '#/components/schemas/StudyDescription' diff --git a/service/src/main/resources/api/test.yaml b/service/src/main/resources/api/test.yaml new file mode 100644 index 000000000..acd05b496 --- /dev/null +++ b/service/src/main/resources/api/test.yaml @@ -0,0 +1,30 @@ +# Test APIs, parameters & schema objects + +paths: + /vumcAdminServiceTest: + get: + description: Temporary endpoint to test service-to-service communication + with the VUMC admin service. + operationId: vumcAdminServiceTest + tags: [ Test ] + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/VumcAdminServiceTest' + 401: + $ref: './common.yaml#/components/responses/Unauthorized' + 500: + $ref: './common.yaml#/components/responses/ServerError' + +components: + schemas: + VumcAdminServiceTest: + type: object + properties: + version: + type: string + round-trip: + type: string diff --git a/service/src/main/resources/api/underlays.yaml b/service/src/main/resources/api/underlays.yaml new file mode 100644 index 000000000..d53159bc6 --- /dev/null +++ b/service/src/main/resources/api/underlays.yaml @@ -0,0 +1,132 @@ +# Underlay APIs, parameters & schema objects + +paths: + /listUnderlaySummaries: + get: + description: List the underlay summaries + operationId: listUnderlaySummaries + tags: [ Underlays ] + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UnderlaySummaryList' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /getUnderlay: + parameters: + - $ref: '#/components/parameters/UnderlayName' + get: + description: Get an underlay + operationId: getUnderlay + tags: [ Underlays ] + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Underlay' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + +components: + parameters: + UnderlayName: + description: Name of the underlay + name: underlayName + in: path + required: true + schema: + type: string + + schemas: + UnderlaySummaryList: + description: List of underlay summaries + type: object + properties: + underlays: + type: array + items: + $ref: '#/components/schemas/UnderlaySummary' + + UnderlaySummary: + description: Underlay summary + type: object + required: [ name, displayName, primaryEntity ] + properties: + name: + description: Name + type: string + displayName: + description: Display name + type: string + description: + description: Description + type: string + primaryEntity: + description: Primary entity name + type: string + + Underlay: + description: Underlay + type: object + required: [ summary, serializedConfiguration, uiConfiguration ] + properties: + summary: + $ref: '#/components/schemas/UnderlaySummary' + serializedConfiguration: + $ref: '#/components/schemas/UnderlaySerializedConfiguration' + # TODO: Remove this uiConfiguration property from the service API once the UI config overhaul is done. + uiConfiguration: + description: UI configuration + type: string + + UnderlaySerializedConfiguration: + description: Contents of the underlay config files + type: object + required: [ underlay, entities,groupItemsEntityGroups, + criteriaOccurrenceEntityGroups ] + properties: + underlay: + description: Contents of the underlay.json file + type: string + entities: + description: Contents of the entity.json files + type: array + items: + type: string + groupItemsEntityGroups: + description: Contents of the group-items type entityGroup.json files + type: array + items: + type: string + criteriaOccurrenceEntityGroups: + description: Contents of the criteria-occurrence type entityGroup.json files + type: array + items: + type: string + criteriaSelectors: + description: Contents of the criteria selector json files + type: array + items: + type: string + prepackagedDataFeatures: + description: Contents of the prepackaged data feature json files + type: array + items: + type: string + visualizations: + description: Contents of the visualization json files + type: array + items: + type: string + + UnderlayName: + description: Name of the underlay, immutable + type: string diff --git a/service/src/main/resources/api/underlays_entity.yaml b/service/src/main/resources/api/underlays_entity.yaml new file mode 100644 index 000000000..e223f9bcb --- /dev/null +++ b/service/src/main/resources/api/underlays_entity.yaml @@ -0,0 +1,808 @@ +# Underlay-Entity APIs, parameters & schema objects + +paths: + /listEntities: + parameters: + - $ref: './underlays.yaml#/components/parameters/UnderlayName' + get: + description: List the entities in an underlay + operationId: listEntities + tags: [ Underlays ] + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/EntityList' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /getEntity: + parameters: + - $ref: './underlays.yaml#/components/parameters/UnderlayName' + - $ref: '#/components/parameters/EntityName' + get: + description: Get an entity + operationId: getEntity + tags: [ Underlays ] + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/Entity' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + # --------------- Query Instances --------------- + + /listInstances: + parameters: + - $ref: './underlays.yaml#/components/parameters/UnderlayName' + - $ref: '#/components/parameters/EntityName' + post: + description: List entity instances + operationId: listInstances + tags: [ Underlays ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Query' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/InstanceListResult' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + /listInstancesForPrimaryEntity: + parameters: + - $ref: './underlays.yaml#/components/parameters/UnderlayName' + - $ref: '#/components/parameters/EntityName' + post: + description: List entity instances filtered for a single primary entity id + operationId: listInstancesForPrimaryEntity + tags: [ Underlays ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/QueryFilterOnPrimaryEntity' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/InstanceListResult' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + # --------------- Query Count --------------- + + /countInstances: + parameters: + - $ref: './underlays.yaml#/components/parameters/UnderlayName' + - $ref: '#/components/parameters/EntityName' + post: + description: Count entity instances + operationId: countInstances + tags: [ Underlays ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CountQuery' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/InstanceCountList' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + + # --------------- Query Hints --------------- + + /queryHints: + parameters: + - $ref: './underlays.yaml#/components/parameters/UnderlayName' + - $ref: '#/components/parameters/EntityName' + post: + description: Query entity display hints + operationId: queryHints + tags: [ Underlays ] + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/HintQuery' + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/DisplayHintList' + 404: + $ref: './common.yaml#/components/responses/NotFound' + 500: + $ref: './common.yaml#/components/responses/ServerError' + +components: + parameters: + EntityName: + description: Name of the entity + name: entityName + in: path + required: true + schema: + type: string + + PrimaryEntityInstanceId: + description: ID of the primary entity instance that the annotation value + is associated with + name: instanceId + in: path + required: true + schema: + type: string + + schemas: + EntityList: + description: List of entities + type: object + properties: + entities: + type: array + items: + $ref: '#/components/schemas/Entity' + + Entity: + description: Entity + type: object + required: [ name, idAttribute ] + properties: + name: + description: Name + type: string + idAttribute: + description: ID attribute name + type: string + attributes: + description: List of attributes + type: array + items: + $ref: '#/components/schemas/Attribute' + + Attribute: + type: object + description: Entity attribute + properties: + name: + description: Name + type: string + type: + description: Attribute type + type: string + enum: [ 'SIMPLE', 'KEY_AND_DISPLAY' ] + dataType: + $ref: './common.yaml#/components/schemas/DataType' + + # --------------- Query Filters --------------- + + Filter: + description: Union of references to each filter type. Exactly one should + be specified based on the filterType + type: object + nullable: true + properties: + filterType: + type: string + enum: [ 'ATTRIBUTE', 'TEXT', 'HIERARCHY', 'RELATIONSHIP', + 'BOOLEAN_LOGIC', 'ITEM_IN_GROUP', 'GROUP_HAS_ITEMS', + 'OCCURRENCE_FOR_PRIMARY', 'PRIMARY_WITH_CRITERIA' ] + filterUnion: + type: object + properties: + attributeFilter: + $ref: '#/components/schemas/AttributeFilter' + textFilter: + $ref: '#/components/schemas/TextFilter' + hierarchyFilter: + $ref: '#/components/schemas/HierarchyFilter' + relationshipFilter: + $ref: '#/components/schemas/RelationshipFilter' + booleanLogicFilter: + $ref: '#/components/schemas/BooleanLogicFilter' + itemInGroupFilter: + $ref: '#/components/schemas/ItemInGroupFilter' + groupHasItemsFilter: + $ref: '#/components/schemas/GroupHasItemsFilter' + occurrenceForPrimaryFilter: + $ref: '#/components/schemas/OccurrenceForPrimaryFilter' + primaryWithCriteriaFilter: + $ref: '#/components/schemas/PrimaryWithCriteriaFilter' + + AttributeFilter: + description: Filter on an attribute value (e.g. color=red) + type: object + properties: + attribute: + type: string + operator: + type: string + enum: [ 'IS_NULL', 'IS_NOT_NULL', 'IS_EMPTY_STRING', 'EQUALS', + 'NOT_EQUALS', 'LESS_THAN', 'GREATER_THAN', 'LESS_THAN_OR_EQUAL', + 'GREATER_THAN_OR_EQUAL', 'IN', 'NOT_IN', 'BETWEEN' ] + values: + type: array + items: + $ref: './common.yaml#/components/schemas/Literal' + + TextFilter: + description: Filter on a text search (e.g. person sounds like Joe) + type: object + properties: + matchType: + type: string + enum: [ 'EXACT_MATCH', 'FUZZY_MATCH' ] + attribute: + description: Attribute to match on. If not specified, then we match + on whatever is specified in the text search mapping config. + Currently, fuzzy match only works on a single attribute + (i.e. you must specify this field for fuzzy match) + type: string + text: + type: string + + HierarchyFilter: + description: Filter on a hierarchy (e.g. descendant of id=12) + type: object + properties: + hierarchy: + description: Name of the hierarchy + type: string + operator: + type: string + enum: [ 'CHILD_OF', 'DESCENDANT_OF_INCLUSIVE', 'IS_ROOT', 'IS_MEMBER' ] + values: + type: array + items: + $ref: './common.yaml#/components/schemas/Literal' + + RelationshipFilter: + description: Filter on a relationship between entities (e.g. condition + occurrences where condition=diabetes). If the group_by_count_operator + is set, then the group_by_count_value must also be set. The + group_by_count_attribute is optional. If undefined, we group by the id + only. When group_by fields are set, we filter on the number of related + entity instances. e.g. filter person instances with >2 related + condition_occurrence instances + type: object + properties: + entity: + type: string + subfilter: + $ref: '#/components/schemas/Filter' + groupByCountAttributes: + type: array + items: + type: string + groupByCountOperator: + $ref: '#/components/schemas/BinaryOperator' + groupByCountValue: + type: integer + nullable: true + + BooleanLogicFilter: + description: Compose multiple filters (e.g. color=red AND capacity=3, + NOT color=red). The NOT operator only allows a single subfilter. + The OR and AND operators require more than one subfilter + type: object + properties: + operator: + type: string + enum: [ 'AND', 'OR', 'NOT' ] + subfilters: + type: array + items: + $ref: '#/components/schemas/Filter' + + ItemInGroupFilter: + description: Filter an items entity with a group-items entity group. + (e.g. ingredients in a brand, blood pressure readings for a person). + If the groupByCountOperator is set, then the groupByCountValue must + also be set. The groupByCountAttribute is optional. If undefined, we + group by the id only. When group by fields are set, we filter on the + number of related entity instances. e.g. filter ingredients that are + included in >2 brands + type: object + required: [ entityGroup ] + properties: + entityGroup: + type: string + groupSubfilter: + $ref: '#/components/schemas/Filter' + groupByCountAttributes: + type: array + items: + type: string + groupByCountOperator: + $ref: '#/components/schemas/BinaryOperator' + groupByCountValue: + type: integer + + GroupHasItemsFilter: + description: Filter a group entity with any related items entities using + a group-items entity group. (e.g. brand with at least one ingredient, + person with at least one blood pressure reading) + type: object + required: [ entityGroup ] + properties: + entityGroup: + type: string + itemsSubfilter: + $ref: '#/components/schemas/Filter' + groupByCountAttributes: + type: array + items: + type: string + groupByCountOperator: + $ref: '#/components/schemas/BinaryOperator' + groupByCountValue: + type: integer + + OccurrenceForPrimaryFilter: + description: Filters an occurrence entity with a criteria-occurrence + entity group (e.g. condition occurrences for people with gender=female, + condition=diabetes) + type: object + required: [ entityGroup, occurrenceEntity ] + properties: + entityGroup: + type: string + occurrenceEntity: + type: string + primarySubfilter: + $ref: '#/components/schemas/Filter' + criteriaSubfilter: + $ref: '#/components/schemas/Filter' + + PrimaryWithCriteriaFilter: + description: Filter the primary entity with a criteria-occurrence entity + group (e.g. people where condition=diabetes and visit_type=inpatient). + If the groupByCountOperator is set, then the groupByCountValue must also + be set. The groupByCountAttributes are optional. If undefined, we group + by the id only. When group by fields are set, we filter on the number + of related occurrence instances. e.g. filter person instances with >2 + related condition_occurrence instances + type: object + required: [ entityGroup ] + properties: + entityGroup: + type: string + criteriaSubfilter: + $ref: '#/components/schemas/Filter' + occurrenceSubfiltersAndGroupByAttributes: + description: Set of sub-filter and group by attributes per occurrence + entity. Map key is the occurrence entity name + type: object + additionalProperties: + type: object + properties: + subfilters: + type: array + items: + $ref: '#/components/schemas/Filter' + group_by_count_attributes: + type: array + items: + type: string + groupByCountOperator: + $ref: '#/components/schemas/BinaryOperator' + groupByCountValue: + type: integer + + BinaryOperator: + type: string + enum: [ 'EQUALS', 'NOT_EQUALS', 'LESS_THAN', 'GREATER_THAN', + 'LESS_THAN_OR_EQUAL', 'GREATER_THAN_OR_EQUAL' ] + + # --------------- Query Instances --------------- + + Query: + description: Query for entity instances + type: object + properties: + includeAttributes: + description: Attributes to include in the returned instances + type: array + items: + type: string + includeHierarchyFields: + description: Hierarchy fields to include in the returned instances. + All fields will be returned for each hierarchy specified + type: object + properties: + hierarchies: + description: Hierarchy names + type: array + items: + type: string + fields: + type: array + items: + type: string + enum: [ 'IS_MEMBER', 'PATH', 'NUM_CHILDREN', 'IS_ROOT' ] + includeRelationshipFields: + description: Relationship (count) fields to include in the + returned instances + type: array + items: + description: Related entity and optional hierarchies. Per-node + rollups are always returned + type: object + properties: + relatedEntity: + type: string + hierarchies: + description: Hierarchy names + type: array + items: + type: string + filter: + $ref: '#/components/schemas/Filter' + orderBys: + description: Attributes and direction to order the results by + type: array + items: + description: Attribute or relationship (count) field and the direction + type: object + properties: + attribute: + type: string + relationshipField: + type: object + properties: + relatedEntity: + type: string + hierarchy: + type: string + direction: + $ref: './common.yaml#/components/schemas/OrderByDirection' + limit: + $ref: './common.yaml#/components/schemas/Limit' + pageSize: + $ref: './common.yaml#/components/schemas/PageSize' + pageMarker: + $ref: './common.yaml#/components/schemas/PageMarker' + + InstanceListResult: + description: List of instances + type: object + properties: + sql: + type: string + instances: + type: array + items: + $ref: '#/components/schemas/Instance' + pageMarker: + $ref: './common.yaml#/components/schemas/PageMarker' + numRowsAcrossAllPages: + $ref: './common.yaml#/components/schemas/NumRowsAcrossAllPages' + + Instance: + type: object + properties: + attributes: + description: A map of entity attribute names to their value for this + instance. Only the attributes requested are populated + type: object + additionalProperties: + $ref: './common.yaml#/components/schemas/ValueDisplay' + hierarchyFields: + description: Hierarchy field values for this instance. One set of + values per hierarchy. Only the values requested are populated + type: array + items: + type: object + properties: + hierarchy: + type: string + isMember: + type: boolean + path: + type: string + numChildren: + type: integer + isRoot: + type: boolean + relationshipFields: + description: Relationship field values for this instance. Only the + values requested are populated + type: array + items: + type: object + properties: + relatedEntity: + type: string + hierarchy: + type: string + count: + type: integer + displayHints: + type: string + + QueryFilterOnPrimaryEntity: + description: Query for entity instances filtered for a single primary entity id + type: object + required: [ includeAttributes, orderBys, primaryEntityId ] + properties: + includeAttributes: + description: Attributes to include in the returned instances. Empty + array means to include all attributes + type: array + items: + type: string + orderBys: + description: Attributes and direction to order the results by + type: array + items: + description: Attribute field and the direction + type: object + properties: + attribute: + type: string + direction: + $ref: './common.yaml#/components/schemas/OrderByDirection' + primaryEntityId: + $ref: './common.yaml#/components/schemas/Literal' + pageSize: + $ref: './common.yaml#/components/schemas/PageSize' + pageMarker: + $ref: './common.yaml#/components/schemas/PageMarker' + + # --------------- Query Count --------------- + + CountQuery: + description: Count entity instances + type: object + properties: + attributes: + description: Attributes to group by. One count will be returned for each + possible combination of attribute values (e.g. [gender, hair_color] + will return counts for man+red, man+black, woman+red, woman+black) + type: array + items: + type: string + filter: + $ref: '#/components/schemas/Filter' + pageSize: + $ref: './common.yaml#/components/schemas/PageSize' + pageMarker: + $ref: './common.yaml#/components/schemas/PageMarker' + + InstanceCountList: + description: List of instance counts + type: object + properties: + sql: + type: string + instanceCounts: + type: array + items: + $ref: '#/components/schemas/InstanceCount' + pageMarker: + $ref: './common.yaml#/components/schemas/PageSize' + numRowsAcrossAllPages: + $ref: './common.yaml#/components/schemas/NumRowsAcrossAllPages' + + InstanceCount: + type: object + properties: + count: + type: integer + attributes: + description: A map of entity attribute names to their value for this group + type: object + additionalProperties: + $ref: './common.yaml#/components/schemas/ValueDisplay' + + # --------------- Query Hints --------------- + + HintQuery: + description: Get display hints + type: object + properties: + relatedEntity: + description: Optional related entity. If specified, then we return + hints computed across related instances (e.g. condition occurrences + where condition id=11). Otherwise, we return hints computed across + all instances (e.g. all persons) + type: object + properties: + name: + description: Related entity name + type: string + id: + $ref: './common.yaml#/components/schemas/Literal' + + DisplayHintList: + description: List of display hints + type: object + properties: + sql: + type: string + displayHints: + type: array + items: + $ref: '#/components/schemas/DisplayHint' + + DisplayHint: + description: Display hint for entity attribute + type: object + properties: + attribute: + $ref: '#/components/schemas/Attribute' + displayHint: + description: Display hint calculated from source data + type: object + properties: + enumHint: + $ref: '#/components/schemas/DisplayHintEnum' + numericRangeHint: + $ref: '#/components/schemas/DisplayHintNumericRange' + + DisplayHintEnum: + description: Enumeration of possible values, display strings, and counts + type: object + properties: + enumHintValues: + type: array + items: + description: Enum value and count + type: object + properties: + enumVal: + $ref: './common.yaml#/components/schemas/ValueDisplay' + count: + type: integer + + DisplayHintNumericRange: + description: Maximum and minimum values + type: object + properties: + min: + description: Max value + type: number + format: double + max: + description: Min value + type: number + format: double + + # --------------- Criteria --------------- + + CriteriaGroupSection: + description: Section of criteria groups and boolean logic operators to + combine them + type: object + required: [ id, displayName, criteriaGroups, operator, excluded ] + properties: + id: + description: ID of the section, immutable + type: string + displayName: + description: Name of the section + type: string + criteriaGroups: + description: For a temporal section, this is the set of groups that + define the first block. For a non-temporal section, the set of + groups is the union of this list and the secondBlockCriteriaGroups list + type: array + items: + $ref: '#/components/schemas/CriteriaGroup' + firstBlockReducingOperator: + $ref: '#/components/schemas/ReducingOperator' + secondBlockCriteriaGroups: + description: For a temporal section, this is the set of groups that + define the second block. For a non-temporal section, the set of + groups are the union of this list and the criteriaGroups list + type: array + items: + $ref: '#/components/schemas/CriteriaGroup' + secondBlockReducingOperator: + $ref: '#/components/schemas/ReducingOperator' + operator: + description: Operator to use when combining the criteria groups in the section + type: string + enum: [ 'AND', 'OR', 'DURING_SAME_ENCOUNTER', 'NUM_DAYS_BEFORE', + 'NUM_DAYS_AFTER', 'WITHIN_NUM_DAYS'] + operatorValue: + description: Value associated with the operator (e.g. num days) + type: integer + excluded: + description: True to exclude the section, false to include it + type: boolean + + CriteriaGroup: + description: Group of related criteria (primary + modifiers) + type: object + required: [ id, displayName, criteria ] + properties: + id: + type: string + description: ID of the group, immutable + displayName: + type: string + description: Name of the group + criteria: + type: array + description: Set of criteria in the group + items: + $ref: '#/components/schemas/Criteria' + + Criteria: + description: Single criteria for a cohort or concept set definition + type: object + required: [ id, displayName, pluginName, selectionData, uiConfig, tags ] + properties: + id: + description: ID of the criteria, immutable + type: string + displayName: + description: Name of the criteria + type: string + pluginName: + description: Name of the plugin that generated this criteria + type: string + pluginVersion: + description: Version of the plugin that generated this criteria + type: integer + predefinedId: + description: Id of the predefined criteria in the config + type: string + selectorOrModifierName: + description: Name of the selector or modifier used by this config + type: string + selectionData: + description: Serialized plugin-specific representation of the user's selection + type: string # JSON formatted, previously base64 Protobuf formatted + uiConfig: + description: Serialized plugin-specific UI configuration for the criteria + type: string # JSON formatted + tags: + description: Unstructured key-value tags for the criteria + type: object + additionalProperties: + type: string + nullable: true + + ReducingOperator: + description: Reducing operator for the criteria groups blocks. Only + applies for a temporal section + type: string + enum: [ 'ANY', 'FIRST_MENTION_OF', 'LAST_MENTION_OF'] diff --git a/service/src/main/resources/api/users.yaml b/service/src/main/resources/api/users.yaml new file mode 100644 index 000000000..0d8e358f6 --- /dev/null +++ b/service/src/main/resources/api/users.yaml @@ -0,0 +1,30 @@ +# User APIs, parameters & schema objects + +paths: + /getMe: + get: + description: Returns the current user's profile information + operationId: getMe + tags: [ Users ] + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: '#/components/schemas/UserProfile' + 500: + $ref: './common.yaml#/components/responses/ServerError' + +components: + schemas: + UserProfile: + description: User profile + type: object + required: [ email, subjectId ] + properties: + email: + type: string + subjectId: + type: string + From e8adc08edd43d32ad01818a88ba0bccf4e6c25ae Mon Sep 17 00:00:00 2001 From: dexamundsen Date: Wed, 28 Aug 2024 17:31:44 -0700 Subject: [PATCH 2/4] Fixes 1 --- service/src/main/resources/api/service_openapi.yaml | 2 +- service/src/main/resources/api/underlays_entity.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/service/src/main/resources/api/service_openapi.yaml b/service/src/main/resources/api/service_openapi.yaml index 55c3195c8..44461c36f 100644 --- a/service/src/main/resources/api/service_openapi.yaml +++ b/service/src/main/resources/api/service_openapi.yaml @@ -33,7 +33,7 @@ paths: security: [ ] description: Returns the deployed version of the service operationId: serviceVersion - tags: [ Public ] + tags: [ Unauthenticated ] responses: 200: description: Version properties diff --git a/service/src/main/resources/api/underlays_entity.yaml b/service/src/main/resources/api/underlays_entity.yaml index e223f9bcb..b5396c08f 100644 --- a/service/src/main/resources/api/underlays_entity.yaml +++ b/service/src/main/resources/api/underlays_entity.yaml @@ -616,7 +616,7 @@ components: items: $ref: '#/components/schemas/InstanceCount' pageMarker: - $ref: './common.yaml#/components/schemas/PageSize' + $ref: './common.yaml#/components/schemas/PageMarker' numRowsAcrossAllPages: $ref: './common.yaml#/components/schemas/NumRowsAcrossAllPages' From 8690180ac8c0858e5406e51dc2d82feb95f63259 Mon Sep 17 00:00:00 2001 From: dexamundsen Date: Wed, 28 Aug 2024 17:40:26 -0700 Subject: [PATCH 3/4] Fixes 2 --- service/src/main/resources/api/annotations.yaml | 2 -- service/src/main/resources/api/common.yaml | 2 -- service/src/main/resources/api/conceptSets.yaml | 5 ++--- service/src/main/resources/api/export.yaml | 4 +--- service/src/main/resources/api/reviews.yaml | 15 ++++----------- 5 files changed, 7 insertions(+), 21 deletions(-) diff --git a/service/src/main/resources/api/annotations.yaml b/service/src/main/resources/api/annotations.yaml index f370c8707..ad6376b8b 100644 --- a/service/src/main/resources/api/annotations.yaml +++ b/service/src/main/resources/api/annotations.yaml @@ -146,8 +146,6 @@ components: schema: type: string - - schemas: AnnotationList: type: array diff --git a/service/src/main/resources/api/common.yaml b/service/src/main/resources/api/common.yaml index 334ebcc9a..28457c204 100644 --- a/service/src/main/resources/api/common.yaml +++ b/service/src/main/resources/api/common.yaml @@ -2,8 +2,6 @@ components: parameters: - # --------------- Pagination --------------- - Offset: description: The number of items to skip before starting to collect the result set diff --git a/service/src/main/resources/api/conceptSets.yaml b/service/src/main/resources/api/conceptSets.yaml index ec667f123..703ab05ef 100644 --- a/service/src/main/resources/api/conceptSets.yaml +++ b/service/src/main/resources/api/conceptSets.yaml @@ -161,6 +161,7 @@ components: EntityOutput: type: object + required: [ entity ] properties: entity: description: Entity name @@ -170,9 +171,7 @@ components: type: array items: type: string - required: - - entity - + ConceptSetCreateInfo: type: object properties: diff --git a/service/src/main/resources/api/export.yaml b/service/src/main/resources/api/export.yaml index 36ac15912..65d127c48 100644 --- a/service/src/main/resources/api/export.yaml +++ b/service/src/main/resources/api/export.yaml @@ -188,14 +188,12 @@ components: type: array items: type: object + required: [ conceptSetId, criteriaId ] properties: conceptSetId: type: string criteriaId: type: string - required: - - conceptSetId - - criteriaId indexSql: description: SQL string against the index tables. This will be populated if source queries are not configured for this entity diff --git a/service/src/main/resources/api/reviews.yaml b/service/src/main/resources/api/reviews.yaml index befd2958a..8d39643da 100644 --- a/service/src/main/resources/api/reviews.yaml +++ b/service/src/main/resources/api/reviews.yaml @@ -194,14 +194,8 @@ components: description: Timestamp of when the review was last modified type: string format: date-time - required: - - id - - displayName - - size - - cohortRevision - - created - - createdBy - - lastModified + required: [ id, displayName, size, cohortRevision, created, createdBy, + lastModified ] ReviewId: description: ID of the review, immutable @@ -221,6 +215,7 @@ components: ReviewCreateInfo: type: object + required: [ displayName, size ] properties: displayName: $ref: '#/components/schemas/ReviewDisplayName' @@ -228,9 +223,7 @@ components: $ref: '#/components/schemas/ReviewDescription' size: $ref: '#/components/schemas/ReviewSize' - required: - - displayName - - size + ReviewUpdateInfo: type: object From 2cfd622dfcdc993cd28677de029d27a63c1bab12 Mon Sep 17 00:00:00 2001 From: dexamundsen Date: Wed, 28 Aug 2024 19:07:51 -0700 Subject: [PATCH 4/4] remove new line --- service/src/main/resources/api/users.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/service/src/main/resources/api/users.yaml b/service/src/main/resources/api/users.yaml index 0d8e358f6..be40f1f94 100644 --- a/service/src/main/resources/api/users.yaml +++ b/service/src/main/resources/api/users.yaml @@ -27,4 +27,3 @@ components: type: string subjectId: type: string -