Add dataset, FHIR stores and annotations stores and related resources (…

…#71)

* Add Text, make Note extend Text, update date-annotator to take as input one note

* The date annotator takes as input Text instead of Notes

* Add post and get all datasets

* Add get one dataset by id and delete one dataset

* Add annotation store

* Add endpoints to manage annotations

* Shave Annotation and DateAnnotation schemas from DB-related fields

* Add note stores and notes

* Date annotator now takes one Text object as input

* Add StoredAnnotation and StoredDateAnnotation schemas

* Add IBM OpenAPI Validator

* Fix errors reported by IBM validators

* Fix some warnings returned by IBM OpenAPI Validator

* Fix operationIds

* Fix pagination AllOf

* Add missing descriptions

* Fix last warnings returned by IBM validator for the data node API

* Update before refactoring dataset endpoints

* Add endpoints to create and list FHIR stores

* Add endpoint to get and delete a FHIR store

* Add endpoints to create and list FHIR patients

* Add endpoints to get and delete a FHIR patient

* Add endpoints to manipulate notes in FHIR store

* Restore annotation store endpoints

* Major update after introduction of readOnly

* Keep only CI/CD for data-node for now

* Update annotation schemas

* Dataset and store names are no longer readOnly

* Array in page now named according to the type of objects

* Successful post request now returns 201

* Note path comes ../fhir/Note

* Now returning paginated annotation stores

* Update annotation schemas and endpoints

* Add option to filter annotations to be returned by annotationType

* Enable poster to set annotation id; rename PageResponse to ResponsePageMetadata

* Text annotation object is now a property of the annotation record

* Remove health endpoint from date annotator

* Remove commons path health

* Fix case sensitive issue

* Fix date annotator API

* Use Google bundle schema approach for Annotation

* Make name of dataset and stores readOnly

* The poster no longer specify an annotationId

* Fix PageOfAnnotations

* Add annotation examples

* Replace PageOfAnnotations.items by PageOfAnnotations.annotations

.validaterc

@@ -0,0 +1,108 @@
+{
+  "shared": {
+    "operations": {
+      "no_operation_id": "error",
+      "operation_id_case_convention": [
+        "warning",
+        "lower_camel_case"
+      ],
+      "no_summary": "warning",
+      "no_array_responses": "error",
+      "parameter_order": "warning",
+      "undefined_tag": "warning",
+      "unused_tag": "warning",
+      "operation_id_naming_convention": "warning"
+    },
+    "pagination": {
+      "pagination_style": "error"
+    },
+    "parameters": {
+      "no_parameter_description": "error",
+      "param_name_case_convention": [
+        "error",
+        "lower_camel_case"
+      ],
+      "invalid_type_format_pair": "error",
+      "content_type_parameter": "error",
+      "accept_type_parameter": "error",
+      "authorization_parameter": "warning",
+      "required_param_has_default": "warning"
+    },
+    "paths": {
+      "missing_path_parameter": "error",
+      "duplicate_path_parameter": "error",
+      "snake_case_only": "off",
+      "paths_case_convention": [
+        "warning",
+        "lower_camel_case"
+      ]
+    },
+    "responses": {
+      "inline_response_schema": "error"
+    },
+    "security_definitions": {
+      "unused_security_schemes": "warning",
+      "unused_security_scopes": "warning"
+    },
+    "security": {
+      "invalid_non_empty_security_array": "error"
+    },
+    "schemas": {
+      "invalid_type_format_pair": "warning",
+      "snake_case_only": "off",
+      "no_schema_description": "warning",
+      "no_property_description": "warning",
+      "description_mentions_json": "warning",
+      "array_of_arrays": "warning",
+      "inconsistent_property_type": "off",
+      "property_case_convention": [
+        "error",
+        "lower_camel_case"
+      ],
+      "property_case_collision": "error",
+      "enum_case_convention": [
+        "error",
+        "lower_snake_case"
+      ],
+      "undefined_required_properties": "warning"
+    },
+    "walker": {
+      "no_empty_descriptions": "error",
+      "has_circular_references": "warning",
+      "$ref_siblings": "off",
+      "duplicate_sibling_description": "warning",
+      "incorrect_ref_pattern": "warning"
+    }
+  },
+  "swagger2": {
+    "operations": {
+      "no_consumes_for_put_or_post": "error",
+      "get_op_has_consumes": "warning",
+      "no_produces": "warning"
+    }
+  },
+  "oas3": {
+    "operations": {
+      "no_request_body_content": "error",
+      "no_request_body_name": "warning"
+    },
+    "parameters": {
+      "no_in_property": "error",
+      "invalid_in_property": "error",
+      "missing_schema_or_content": "error",
+      "has_schema_and_content": "error"
+    },
+    "responses": {
+      "no_response_codes": "error",
+      "no_success_response_codes": "warning",
+      "no_response_body": "warning",
+      "ibm_status_code_guidelines": "warning"
+    },
+    "schemas": {
+      "json_or_param_binary_string": "warning"
+    }
+  },
+  "spectral": {
+    "rules": {}
+  }
+}

README.md

@@ -63,6 +63,10 @@ TBA
 - List paths in alphanumerical order
 - Add schemas and paths used in more than one API to `commons`
 
+## TODO
+
+> "description": "Creates a new Annotation record. It is valid to create Annotation objects for the same source more than once since a unique ID is assigned to each record by this service.",
+
 <!-- Definitions -->
 
 [data_node_yaml]: https://Sage-Bionetworks.github.io//nlp-sandbox-schemas/data-node/develop/openapi.yaml

openapi/commons/components/schemas/Annotation.yaml

@@ -1,18 +1,24 @@
 type: object
-description: An annotation in a text
-allOf:
-  - $ref: Entity.yaml
-  - type: object
-    properties:
-      noteId:
-        description: The note ID
-        type: integer
-      start:
-        description: The position of the first character
-        type: integer
-      length:
-        description: The length of the annotation
-        type: integer
-      text:
-        description: The string annotated
-        type: string
+description: An annotation record
+properties:
+  name:
+    description: Resource name of the annotation record, of the form datasets/{datasetId}/annotationStores/{annotationStoreId}/annotations/{annotationId}
+    type: string
+    readOnly: true
+  annotationSource:
+    $ref: AnnotationSource.yaml
+  textDateAnnotations:
+    description: Date annotations in a text
+    type: array
+    items:
+      $ref: TextDateAnnotation.yaml
+  textPersonNameAnnotations:
+    description: Person name annotations in a text
+    type: array
+    items:
+      $ref: TextPersonNameAnnotation.yaml
+  textPhysicalAddressAnnotations:
+    description: Physical address annotations in a text
+    type: array
+    items:
+      $ref: TextPhysicalAddressAnnotation.yaml

openapi/commons/components/schemas/AnnotationSource.yaml

@@ -0,0 +1,6 @@
+type: object
+description: The source of an annotation record
+properties:
+  name:
+    description: The source of the annotation record
+    type: string

openapi/commons/components/schemas/Error.yaml

@@ -1,4 +1,5 @@
 type: object
+description: Problem details (tools.ietf.org/html/rfc7807)
 properties:
   title:
     type: string

openapi/commons/components/schemas/Note.yaml

@@ -1,18 +1,18 @@
 type: object
 description: A clinical note
-allOf:
-  - $ref: Entity.yaml
-  - type: object
-    properties:
-      text:
-        description: The content of the note
-        type: string
-        example: On 09-03-1999, Ms Chloe Price met with Dr Joe.
-      type:
-        description: The note type
-        type: string
-        enum:
-          - pathology
-          - phone_call
-# required:
-#   - text
+properties:
+  id:
+    description: The ID of the note
+    type: string
+    readOnly: true
+  text:
+    description: A text
+    type: string
+    example: "This is a text."
+  noteType:
+    description: The note type (LOINC concept)
+    type: string
+    example: "loinc:LP29684-5"
+  patientId:
+    description: The patient ID
+    type: string

openapi/commons/components/schemas/Patient.yaml

@@ -0,0 +1,18 @@
+type: object
+description: A FHIR Patient
+properties:
+  id:
+    description: The patient ID
+    type: string
+    readOnly: true
+  identifier:
+    description: An identifier for this patient
+    type: string
+  gender:
+    description: Gender of the patient
+    type: string
+    enum:
+      - male
+      - female
+      - other
+      - unknown

openapi/commons/components/schemas/ResponsePageMetadata.yaml

@@ -0,0 +1,21 @@
+type: object
+description: A page of results
+properties:
+  offset:
+    description: Index of the first result that must be returned
+    type: integer
+  limit:
+    description: Maximum number of results returned
+    type: integer
+  links:
+    description: Links to navigate to different pages of results
+    type: object
+    properties:
+      next:
+        description: Link to the next page of results
+        type: string
+        format: uri
+required:
+  - offset
+  - limit
+  - links

openapi/commons/components/schemas/TextAnnotation.yaml

@@ -0,0 +1,12 @@
+type: object
+description: An annotation in a text
+properties:
+  start:
+    description: The position of the first character
+    type: integer
+  length:
+    description: The length of the annotation
+    type: integer
+  text:
+    description: The string annotated
+    type: string

openapi/commons/components/schemas/DateAnnotation.yaml → openapi/commons/components/schemas/TextDateAnnotation.yaml

@@ -1,9 +1,14 @@
 type: object
 description: A date annotation in a text
 allOf:
-  - $ref: Annotation.yaml
+  - $ref: TextAnnotation.yaml
   - type: object
     properties:
-      format:
+      dateFormat:
         description: Date format (ISO 8601)
         type: string
+example:
+  start: 42
+  length: 10
+  text: 10/26/2020
+  dateFormat: "MM/DD/YYYY"

openapi/commons/components/schemas/TextPersonNameAnnotation.yaml

@@ -0,0 +1,8 @@
+type: object
+description: A person name annotation in a text
+allOf:
+  - $ref: TextAnnotation.yaml
+example:
+  start: 42
+  length: 11
+  text: Chloe Price