create dedicated API endpoint for on-this-day

api/v1/openapi.yaml

@@ -35,6 +35,8 @@ paths:
     $ref: "./openapi/paths/documents-findByMention.yaml"
   /documents/findByAuthor/{authorID}:
     $ref: "./openapi/paths/documents-findByAuthor.yaml"
+  /documents/otd:
+    $ref: "./openapi/paths/documents-otd.yaml"
   /code/findByElement/{element}:
     $ref: "./openapi/paths/code-findByElement.yaml"
   /application/status:

api/v1/openapi/paths/documents-otd.yaml

@@ -0,0 +1,39 @@
+# /documents/otd path
+get:
+  tags:
+    - Documents
+  summary: Returns documents which feature events on this day
+  description: |
+    This endpoint returns a list of documents which feature events on this day.
+    The events are extracted from the metadata (e.g. birth of a person, writing date of a letter) 
+    and do not take mentioned events (from the text) into account.
+  parameters:
+    - name: date
+      in: query
+      description: |
+        The day and month to search for in years before the given year. 
+        If no date is provided, the current server date will be used.
+      required: false
+      schema:
+        type: string
+        format: date
+        default: '2024-12-18'
+    - $ref: '../parameters/docType.yaml'
+    - $ref: '../parameters/offset.yaml'
+    - $ref: '../parameters/limit.yaml'
+  responses:
+    '200':
+      description: An array of documents
+      headers:
+        totalrecordcount:
+          description: The total size of the result set
+          schema:
+            type: integer
+      content:
+        application/json:
+          schema:
+            type: array
+            items:
+              $ref: '../schemas/document.yaml'
+    default:
+      $ref: '../responses/unexpectedError.yaml'

api/v1/openapi/schemas/document-otd.yaml

@@ -0,0 +1,30 @@
+# Document "on this day" schema
+# This is merely a clone of the document schema
+# with additional properties for "on this day"
+type: object
+properties:
+  uri:
+    type: string
+    description: Unique identifier representing a specific document
+  docID:
+    type: string
+    description: The WeGA document identifier representing a specific document
+  docType:
+    type: string
+    description: The WeGA document type
+  title:
+    type: string
+    description: The title of the document
+  otdTitle:
+    type: string
+    description: The title of the event
+  otdEvent:
+    type: string
+    description: The type of event occurring in the document
+    enum:
+      - birth
+      - death
+  otdJubilee:
+    type: integer
+    format: int32
+    description: The years between the event and the provided on-this-day date

modules/api.xqm

@@ -108,6 +108,30 @@ declare function api:documents-findByAuthor($model as map(*)) as map(*) {
     )
 };
 
+declare function api:documents-otd($model as map(*)) as map(*) {
+    let $date :=
+        if($model?date castable as xs:date)
+        then $model?date => substring(6, 5)
+        else current-date() => substring(6, 5)
+    let $dateElements :=
+        for $docType in api:resolve-docTypes($model)
+        return
+            switch($docType)
+            case 'letters' return
+                core:getOrCreateColl(
+                    $docType,'indices', true()
+                )//tei:TEI[ft:query(., 'date:' || $date)]//tei:correspAction[@type='sent']/tei:date[contains(@when, $date)][following::tei:text//tei:p]
+(:            case 'persons' return:)
+(:                core:getOrCreateColl($docType, 'indices', true())//tei:date[contains(@when, $month-day)][not(preceding-sibling::tei:date[contains(@when, $month-day)])][parent::tei:birth or parent::tei:death][ancestor::tei:person/@source='WeGA']:)
+            default return ()
+    return (
+        map {
+            'totalRecordCount': count($dateElements),
+            'results': api:document-otd(api:subsequence($dateElements, $model), $model)
+        }
+    )
+};
+
 declare function api:code-findByElement($model as map(*)) {
     let $documents := 
         for $docType in api:resolve-docTypes($model)
@@ -528,12 +552,46 @@ declare %private function api:document($documents as document-node()*, $model as
         let $id := $doc/*/data(@xml:id)
         let $docType := config:get-doctype-by-id($id)
         return
-            map { 
-                'uri' : api:document-uri($id, $model),
-                'docID' : $id,
-                'docType' : $docType,
-                'title' : wdt:lookup($docType, $doc)('title')('txt')
+            api:document-basics($doc, $id, $docType, $model)
+    }
+};
+
+(:~
+ :  Helper function for creating a Document otd object
+~:)
+declare %private function api:document-otd($dateElements as element(tei:date)*, $model as map(*)) as array(*) {
+    array {
+        for $dateElem in $dateElements
+        let $docID := $dateElem/root()/*/data(@xml:id)
+        let $docType := config:get-doctype-by-id($docID)
+        let $typeOfEvent :=
+            if($dateElem/ancestor::tei:correspDesc) then 'letter'
+            else if($dateElem[@type='baptism']) then 'isBaptised'
+            else if($dateElem/parent::tei:birth) then 'isBorn'
+            else if($dateElem[@type='funeral']) then 'wasBuried'
+            else if($dateElem/parent::tei:death) then 'dies'
+            else ()
+        let $isJubilee := (year-from-date($model?date) - $dateElem/year-from-date(@when)) mod 25 = 0
+        return map:merge((
+            api:document-basics($dateElem/root(), $docID, $docType, $model),
+            map {
+                'otdTitle': '',
+                'otdEvent': $typeOfEvent,
+                'otdJubilee': ''
             }
+        ))
+    }
+};
+
+(:~
+ :  Helper function for api:document and api:document-otd
+:)
+declare %private function api:document-basics($doc as document-node(), $docID as xs:string, $docType as xs:string, $model as map(*)) as map(*) {
+    map {
+        'uri' : api:document-uri($docID, $model),
+        'docID' : $docID,
+        'docType' : $docType,
+        'title' : wdt:lookup($docType, $doc)('title')('txt')
     }
 };
 
@@ -637,6 +695,15 @@ declare function api:validate-toDate($model as map(*)) as map(*)? {
     else error($api:INVALID_PARAMETER, 'Unsupported date format given: "' || $model('toDate') || '". Should be YYYY-MM-DD.')
 };
 
+(:~
+ : Check parameter date
+~:)
+declare function api:validate-date($model as map(*)) as map(*)? {
+    if($model('date') castable as xs:date) then $model
+    else if($model?date ='') then () (: an empty string is simply dropped :)
+    else error($api:INVALID_PARAMETER, 'Unsupported date format given: "' || $model('date') || '". Should be YYYY-MM-DD.')
+};
+
 (:~
  : Check parameter docID
 ~:)