Building and Testing Fern Definitions

docs/_snippets/patient.mdx

@@ -66,7 +66,7 @@
 
 </ParamField>
 
-<ParamField query="externalId" type="string">
+<ParamField body="externalId" type="string">
   An external Patient ID to associate to a Patient in Metriport.
 </ParamField>
 

docs/medical-api/api-reference/fhir/consolidated-data-count.mdx

@@ -12,6 +12,8 @@ Returns the amount of resources for each resource type, for a given Patient.
   The ID of the Patient.
 </ParamField>
 
+## Query Params
+
 <ParamField query="resources" type="string" optional>
     A comma separated, case sensitive list of resources to be counted. If none are provided all
     resources will be included.

docs/medical-api/api-reference/patient/delete-patient.mdx

@@ -6,7 +6,7 @@ api: "DELETE /medical/v1/patient/{id}"
 
 ## Query Params
 
-<ParamField query="facilityId" type="string" required>
+<ParamField query="facilityId" type="string" optional>
   The ID of the Facility where the patient is receiving care.
 </ParamField>
 

fern/definition/commons.yml

@@ -19,7 +19,7 @@ types:
         type: string
         docs: Zip must be a string consisting of 5 numbers.
       country:
-        type: string
+        type: optional<string>
         docs: Defaults to “USA”
     examples:
       - name: Example1
@@ -84,3 +84,8 @@ types:
       - WV
       - WI
       - WY
+
+  Period:
+    properties:
+      start: optional<string>
+      end: optional<string>

fern/definition/medical/document.yml

@@ -1,4 +1,6 @@
 # yaml-language-server: $schema=https://raw.githubusercontent.com/fern-api/fern/main/fern.schema.json
+imports:
+  commons: ../commons.yml
 
 service:
   base-path: /medical/v1/document
@@ -32,16 +34,22 @@ service:
           facilityId:
             docs: The ID of the Facility where the patient is receiving care.
             type: string
+        body:
+          docs: |
+            Metadata holds a record of up to 50 custom string key-value pairs. Key names can be up to 40 characters long and values up to 500 characters long. 
+            This metadata will be returned in the webhook response.
+          type: optional<map<string, string>>
       response: DocumentQuery
       examples:
         - name: Example1
           query-parameters:
             patientId: "12345678"
             facilityId: "12345678"
+          request: {"youCan": "putAny", "stringKeyValue": "pairsHere"}
           response:
             body: $DocumentQuery.Example1
 
-    getQueryStatus:
+    getQueryStatus:  
       display-name: Get Document Query Status
       docs: |
         Returns the document query status for the specified patient.
@@ -79,25 +87,19 @@ service:
           patientId:
             docs: The ID of the Patient for which to list available Documents.
             type: string
-          facilityId:
-            docs: The ID of the Facility where the patient is receiving care.
-            type: string
           dateFrom:
             docs: The start date (inclusive) for which to filter returned documents - formatted `YYYY-MM-DD` as per ISO 8601. If not provided, no start date filter will be applied.
             type: optional<string>
           dateTo:
             docs: The end date (inclusive) for which to filter returned documents - formatted `YYYY-MM-DD` as per ISO 8601. If not provided, no end date filter will be applied.
             type: optional<string>
+          content:
+            docs: |
+              Value to search on the document reference (minimum 3 chars).
+            type: optional<string>
       response:
-        type: ListDocumentsResponse
+        type: MedplumDocumentReference
         docs: An array of objects describing the Documents that can be retrieved for the Patient.
-      examples:
-        - name: Example1
-          query-parameters:
-            patientId: "12345678"
-            facilityId: "12345678"
-          response:
-            body: $ListDocumentsResponse.Example1
 
     getURL:
       display-name: Get Document URL
@@ -129,12 +131,42 @@ service:
             conversionType: "pdf"
           response:
             body: $DocumentUrl.Example1
+
+    createDocumentReference:
+      display-name: Upload Document
+      docs: |
+        Creates a DocumentReference and returns its ID and a URL to use for a medical document upload to our servers.
+      method: POST
+      path: /upload
+      request:
+        name: UploadDocumentRequest
+        query-parameters:
+          patientId:
+            docs: The ID of the Patient for which to list available Documents.
+            type: string
+        body:
+          docs: |
+            A FHIR DocumentReference.
+          type: UploadDocumentReference
+      response: 
+        type: UploadDocumentResponse
+        docs: The DocumentReference ID and a URL to be used for file upload.   
+      examples:
+        - name: Example1
+          query-parameters:
+            patientId: "12345678"
+          request: $UploadDocumentReference.Example1
+          response:
+            body: $UploadDocumentResponse.Example1 
 
 types:
   DocumentQuery:
     properties:
       download: optional<Progress>
       convert: optional<Progress>
+      requestId:
+        type: optional<string>
+        docs: The ID of the Document Query.
     examples:
       - name: Example1
         value:
@@ -177,16 +209,11 @@ types:
       - html
       - pdf
 
-  ListDocumentsResponse:
+  MedplumDocumentReference:
     properties:
-      documents: list<DocumentReference>
-    examples:
-      - name: Example1
-        value:
-          documents:
-            - $DocumentReference.Example1
+      documents: list<map<string, unknown>>
 
-  DocumentReference:
+  DocumentReferenceDocumentWebhook:
     properties:
       id:
         type: string
@@ -265,6 +292,62 @@ types:
           code: "62479008"
           display: Diagnoses
 
+
+  UploadDocumentReference:
+    properties:
+      description:
+        type: string
+        docs: A brief description of the document - for example Discharge Summary
+      type:
+        type: CodeableConcept
+        docs: A CodeableConcept of the document type.
+      context:
+        type: list<DocumentReferenceContext>
+        docs: Context of the document content.
+    examples:
+      - name: Example1
+        value:
+          description: "Third degree wrist burn treatment"
+          type:
+            text: "Burn management Hospital Progress note"
+            coding:
+              - code: "100556-0"
+                system: "http://loinc.org"
+                display: "Burn management Hospital Progress note"
+          context: [$DocumentReferenceContext.Example1]
+
+
+  DocumentReferenceContext:
+    properties:
+      period: 
+        type: optional<commons.Period>
+        docs: The time period over which the document was created.
+      facilityType:
+        type: optional<CodeableConcept>
+        docs: The kind of facility where the patient was seen.
+    examples:
+      - name: Example1
+        value:
+          period:
+              start: "2023-10-10T14:14:17Z"
+              end: "2023-10-10T15:30:30Z"
+          facilityType:
+            text: "John Snow Clinic - Acute Care Centre"
+
+  UploadDocumentResponse:
+    properties:
+      documentReferenceId:
+        type: string
+        docs: The ID of the DocumentReference.
+      uploadUrl:
+        type: string
+        docs: The URL to use for uploading the document.
+    examples:
+      - name: Example1
+        value:
+          documentReferenceId: "<DocumentReference-ID-string>"
+          uploadUrl: "<url-string>"
+
   DocumentUrl:
     docs: A json object containing the URL will be returned.
     properties:

fern/definition/medical/fhir.yml

@@ -6,62 +6,90 @@ service:
   audiences: 
     - public
   endpoints:
-    startConsolidatedQuery:
-      display-name: Start Consolidated Data Query
-      docs: Trigger a consolidated data query for the given patient
-      method: POST
+    # startConsolidatedQuery:
+    #   display-name: Start Consolidated Data Query
+    #   docs: Trigger a consolidated data query for the given patient
+    #   method: POST
+    #   path: /patient/{id}/consolidated/query
+    #   path-parameters:
+    #     id:
+    #       type: string
+    #       docs: The ID of the Patient.
+    #   request:
+    #     name: GetPatientConsolidatedData
+    #     query-parameters:
+    #       resources:
+    #         docs: |
+    #           A comma separated, case sensitive list of resources to be returned. 
+    #           If none are provided all resources will be included.
+    #         type: optional<string>
+    #       dateFrom:
+    #         docs: |
+    #           The start date (inclusive) for which to filter returned resources - 
+    #           formatted `YYYY-MM-DD` as per ISO 8601. If not provided, 
+    #           no start date filter will be applied.
+    #         type: optional<string>
+    #       dateTo:
+    #         docs: |
+    #           The end date (inclusive) for which to filter returned resources - 
+    #           formatted `YYYY-MM-DD` as per ISO 8601. If not provided,
+    #            no end date filter will be applied.
+    #         type: optional<string>
+    #       conversionType:
+    #         docs: |
+    #           The doc type to convert to. Either html or pdf.
+    #         type: optional<string>
+    #     body:
+    #       docs: |
+    #         Metadata holds a record of up to 50 custom string key-value pairs. Key names can be up to 40 characters long and values up to 500 characters long. 
+    #         This metadata will be returned in the webhook response.
+    #       type: optional<map<string, string>>
+
+    #   response:
+    #     type: StartConsolidatedQueryResponse
+    #     docs: Returns a Bundle that contains a property entry which is simply an array of FHIR resources.
+    #   examples:
+    #     - path-parameters:
+    #         id: "12345678"
+    #       response:
+    #         body:
+    #           status: processing
+
+    getConsolidatedQueryStatus:
+      display-name: Get Consolidated Data Query status
+      docs: Get the status of querying for patient's consolidated data.
+      method: GET
       path: /patient/{id}/consolidated/query
       path-parameters:
         id:
           type: string
-          docs: The ID of the Patient.
-      request:
-        name: GetPatientConsolidatedData
-        query-parameters:
-          resources:
-            docs: |
-              A comma separated, case sensitive list of resources to be returned. 
-              If none are provided all resources will be included.
-            type: optional<string>
-          dateFrom:
-            docs: |
-              The start date (inclusive) for which to filter returned resources - 
-              formatted `YYYY-MM-DD` as per ISO 8601. If not provided, 
-              no start date filter will be applied.
-            type: optional<string>
-          dateTo:
-            docs: |
-              The end date (inclusive) for which to filter returned resources - 
-              formatted `YYYY-MM-DD` as per ISO 8601. If not provided,
-               no end date filter will be applied.
-            type: optional<string>
+          docs: The ID of the Patient
       response:
-        type: StartConsolidatedQueryResponse
-        docs: Returns a Bundle that contains a property entry which is simply an array of FHIR resources.
+        type: GetConsolidatedQueryStatusResponse
       examples:
-        - path-parameters:
+        - name: Example1
+          path-parameters:
             id: "12345678"
           response:
-            body:
-              status: processing
+            body: $GetConsolidatedQueryStatusResponse.Example0
 
-    getConsolidatedQueryStatus:
-      display-name: Get Consolidated Data Query status
-      docs: Get the status of querying for patient's consolidated data.
-      method: GET
-      path: /patient/{id}/consolidated/query
+    createPatientConsolidated:
+      display-name: Create Patient's Consolidated Data
+      docs: Create Patient's Consolidated Data with a FHIR Bundle.
+      method: PUT
+      path: /patient/{id}/consolidated
       path-parameters:
         id:
           type: string
           docs: The ID of the Patient
       response:
-        type: GetConsolidatedQueryStatusResponse
+        type: TransactionResponse
       examples:
         - name: Example1
           path-parameters:
             id: "12345678"
           response:
-            body: $GetConsolidatedQueryStatusResponse.Example0
+            body: $TransactionResponse.Example0
 
     countPatientData:
       display-name: Count Patient Data
@@ -150,6 +178,28 @@ types:
             no end date filter will be applied.
         type: optional<string>
 
+  TransactionResponse:
+    properties:
+      resourceType:
+        type: string
+        docs: The type of the FHIR resource. For a transaction response, this is always "Bundle".
+      id:
+        type: string
+        docs: A unique identifier for this transaction response.
+      type:
+        type: string
+        docs: The type of the bundle, which is "transaction-response" in this case.
+      entry:
+        type: list<map<string, unknown>>
+        docs: An array of responses for each transaction in the bundle. Each entry can be any arbitrary JSON object. 
+    examples:
+      - name: Example0
+        value:
+          resourceType: "Bundle"
+          id: "12345"
+          type: "transaction-response"
+          entry: [{ "resourceId": "abc123", "status": "created", "details": "Resource created successfully" }]
+
   ResourcesSearchableByPatient:
     enum:
       - Account