aiiinotate 0.2.0

package/docs/specifications/5_sas.md

@@ -0,0 +1,119 @@
+# SIMPLE ANNOTATION SERVER
+
+---
+
+## Sources
+
+- [official docs](https://github.com/glenrobson/SimpleAnnotationServer/tree/master/doc)
+- [endpoints](https://github.com/glenrobson/SimpleAnnotationServer/blob/master/doc/Endpoints.md)
+- [IIIF annotations search](https://github.com/glenrobson/SimpleAnnotationServer/blob/master/doc/IIIFSearch.md)
+
+---
+
+## What does SAS do ?
+
+From what I gather, SAS stores 2 types of data:
+- IIIF annotations
+- IIIF manifests
+- annotations and manifests seem to follow the IIIF 2.x presentation API (instead of the most recent 3.0). 
+
+SAS has 2 main functionnalities:
+- "backend": store and serve annotations in JSON format
+- "frontend": provide a GUI to manage IIIF collections and, most importantly, collections of IIIF annotations. 
+    - SAS uses Mirador as its IIIF graphical interface. 
+    - SAS does have a Mirador plugin but a custom version of Mirador.
+
+In turn, annotations are the primary ressources stored by SAS. SAS also needs to store manifests, so that it can enrich the manifests with the annitations, in order to send a complete manifest (a manifest in which annotations are either referenced or embdded).
+
+--- 
+
+## Endpoints
+
+### Fetch data
+
+#### IIIF search API
+```
+GET /search-api/$manifestShortId/search
+```
+- **returns**: `AnnotationList` with an empty `@id`
+- `$manifestShortId` is the manifest's ID
+- search parameters are [as per the IIIF docs](https://iiif.io/api/search/2.0/#request-1): 
+    - `q`: query string, searched in the annotation's textual body or its URI
+    - `motivation`: search through each annotation's `motivation` key
+    - `date`: date ranges
+    - `users`: the usrs who edited the annotation
+- if no parameters are supplied, all annotations are returned
+- *example: https://aikon.enpc.fr/sas/search-api/wit9_man11_anno165/search?q=*
+
+#### Show all annotations for a canvas
+```
+GET /annotation/search?uri=$canvasUri
+```
+- **returns** `Annotation[]`
+- `$canvasUri` is the URI for the canvas we want annotations for
+- *example: https://aikon.enpc.fr/sas/annotation/search?uri=https://aikon.enpc.fr/aikon/iiif/v2/wit9_man11_anno165/canvas/c16.json#xywh=0,31,1865,1670 shows annotations for canvas https://aikon.enpc.fr/aikon/iiif/v2/wit9_man11_anno165/canvas/c16.json#xywh=0,31,1865,1670*
+
+#### List all indexed IIIF manifests
+```
+GET /manifests
+```
+
+- **returns**
+    ```js
+    {
+        "@type": "sc:Collection",
+        "@id": "http://annotation//collection/managed.json",
+        "label": "string",
+        "@context": "http://iiif.io/api/presentation/2/context.json",
+        "members": [
+            { 
+                "@type": "sc:Manifest",
+                "@id": "URI"
+            }
+        ]
+    }
+    ``` 
+
+### Create/Update data
+
+#### Populate / Import an AnnotationList into SAS
+```
+POST /annotation/populate
+```
+- POST body: the AnnotationList to import can be passed dirctly or as an URI to the AnnotationList (see [SAS source code](https://github.com/glenrobson/SimpleAnnotationServer/blob/dc7c8c6de9f4693c678643db2a996a49eebfcbb0/src/main/java/uk/org/llgc/annotation/store/Populate.java#L46)):
+    - `{ "uri": $annotationListUri }`, where `$annotationListUri` is an URI pointing to a IIIF annotations list
+    - IIIF AnnotationList
+
+#### Create an annotation
+```
+POST /annotation/create
+```
+- POST body: IIIF Annotation
+
+#### Update an annotation
+```
+POST /annotation/update
+```
+- POST body: IIIF Annotation
+    - the annotation's `@id` should point to an annotation that exists in the store
+
+#### Index a new manifest 
+```
+POST /manifests
+```
+- POST body: IIIF Manifest
+
+### Delete data
+
+#### Delete an annotation
+```
+DELETE /annotation/destroy/?uri=$annotationUri
+```
+- `$annotationUri` is the `@id` of the annotation to delete
+
+#### Unindex a manifest
+```
+DELETE /manifests/$manifestId
+```
+- `$manifestId` is the short manifest identifier
+- actually I'm not 100% sure it is implemented by SAS but we [would need it](https://github.com/Aikon-platform/aikon/blob/cc8430c52e205e6a1c04c4ae84f69126fb5a3bda/front/app/webapp/utils/iiif/annotation.py#L769)

package/docs/specifications/6_mirador.md

@@ -0,0 +1,119 @@
+# WRITING A MIRADOR PLUGIN
+
+To integrate an annotation server with Mirador, we need to write a Mirador plugin that that interfaces Mirador with the annotation server.
+
+Writing a mirador plugin is actually really simple: see the [annotot endpoint plugin](https://github.com/ProjectMirador/mirador-annotot-endpoint-plugin)
+
+SAS apparently uses a [custom version of Mirador 2](https://github.com/glenrobson/SimpleAnnotationServer/tree/master/src/main/webapp/mirador-2.6.1)
+
+---
+
+## Sources
+
+- [Mirador docs: plugins](https://github.com/ProjectMirador/mirador/wiki/Mirador-3-plugins)
+- [Mirador docs: writing a plugin](https://github.com/ProjectMirador/mirador/wiki/Creating-a-Mirador-4-plugin)
+- [Mirador annoto endpoint](https://github.com/ProjectMirador/mirador-annotot-endpoint-plugin/tree/master)
+
+---
+
+## Install and use a Mirador plugin
+
+1. npm-install the plugin you want to use:
+    ```bash
+    npm install mirador-image-tools --save
+    ```
+2. when instanciating Mirador, add the plugin to the `plugins` array:
+    ```js
+    import miradorImageToolsPlugin from 'mirador-image-tools/es/plugins/miradorImageToolsPlugin.js';
+
+    const config = {
+        // your Mirador config
+    };
+
+    const plugins = [
+        ...miradorImageToolsPlugin
+    ];
+
+    Mirador.viewer(config, plugins);
+    ```
+
+---
+
+## Writing a plugin
+
+### General architecture
+
+```
+root/
+ |_src
+    |_index.js               // exports the plugin
+    |_components/            // folder containing all the react components that comprise the plugin
+       |_pluginComponent.js  // the react files.
+```
+
+### Plugin config
+
+The plugin's configuration in `index.js` defines how to inject the plugin in Mirador:
+```js
+const plugin = {
+    target: 'WorkspaceControlPanelButtons',                 // where to inject the plugin in the Mirador architecture
+    mode: 'wrap',                                           // how to inject. "add"/"wrap"
+    component: PluginComponent,                             // the plugin as a React component
+    // `connectOptions`, `mapStateToProps` and `mapDispatchToProps` connect the plugin to Mirador
+    connectOptions: additionalOptionsToPassToReduxConnect,  // plugin extras
+    mapStateToProps: mapStateToProps,                       // React redux function that connects store data with react props
+    mapDispatchToProps: mapDispatchToProps,                 // React redux function that dispatches actions to the store
+    // `reducers` and `saga` manipulate state
+    reducers: {
+        pluginState: pluginStateReducer,
+    },
+    saga: saga 
+};
+```
+
+`PluginComponent` is a React component that contains the entire plugin. Nested React components are allowed in `PluginComponent`.
+
+About the `mode`:
+- `mode=add` injects the component at designated areas of the Mirador app.
+- `mode=wrap` overrides mirador behaviour. 
+    - wrapping plugins can:
+        - replace the content of a Mirador coponent
+        - wrap a Mirador component with additional context
+        - to intercept and modify the attributes of a component
+    - all Mirador components can be wrapped
+
+### Plugin components
+
+A plugin component is a React component:
+
+```js
+import React, { Component } from 'react';
+
+export default function () {
+  return <h5>Custom metadata!</h5>;
+}
+```
+
+In the example above,
+- if `mode=add`, the `PluginComponent` will will be added as a child of its `target`.
+- if `mode=wrap`, the `PluginComponent` will replace the `target`.
+
+When `mode = wrap`, the plugin component can modify its `target`. The plugin will receive the Mirador component that is being wrapped as an attribute => we can change the props of the component, surround it with extra context, change its behaviour...
+
+```js
+import React, { Component } from 'react';
+
+export default function ({ TargetComponent, targetProps  }) {
+  return <TargetComponent {...targetProps} />;
+}
+``` 
+
+--- 
+
+## Annotot plugin 
+
+- [repo](https://github.com/ProjectMirador/mirador-annotot-endpoint-plugin/)
+- [plugin component](https://github.com/ProjectMirador/mirador-annotot-endpoint-plugin/blob/master/src/plugins/miradorAnnototEndpointPlugin.js)
+- [plugin config](https://github.com/ProjectMirador/mirador-annotot-endpoint-plugin/blob/42a04b93429b0a85dee50a3dbe4d6d5e3fb8046e/src/plugins/miradorAnnototEndpointPlugin.js#L65)
+- [usage demo](https://github.com/ProjectMirador/mirador-annotot-endpoint-plugin/blob/master/demo/src/index.js)
+

package/docs/specifications/7_aikon.md

@@ -0,0 +1,137 @@
+# AIKON NEEDS
+
+Hre we desribe the functionnalities our annotation server should implement, and list which functionnalities are aldready implemented by SAS.
+
+---
+
+## Reminders
+
+- in Aikon, a Regions corresponds to a regions extraction on a document, and that Regions extrction corresponds to a IIIF manifest. 1 manifest => 1 regions extraction
+- IIIF and SAS specific code in Aikon is stored in [front.app.webapp.utils.iiif](https://github.com/Aikon-platform/aikon/tree/main/front/app/webapp/utils/iiif)
+- in AIKON, IIIF manifests aren't stored in the app. Instead, they are generated dynamically and served when needed.
+    - IIIF and SAS specific code in Aikon is stored in [front.app.webapp.utils.iiif](https://github.com/Aikon-platform/aikon/tree/main/front/app/webapp/utils/iiif)
+    - see [front.app.webapp.utils.iiif.manifests](https://github.com/Aikon-platform/aikon/blob/main/front/app/webapp/utils/iiif/manifest.py)
+    - *note: IIIF manifests are stored by SAS, because SAS needs the manifests. In the app however, we don't use the SAS stored manifests*
+
+---
+
+## Implemented by SAS
+
+### Fetch data
+
+- get all manifests stored in SAS
+    - SAS route: `GET /manifests`
+- get all annotations / implement a IIIF search API. 
+    - SAS route: `GET /search-api/$manifestId/search`
+    - if we don't implement a full search API, we can use this route to return all annotations for a manifest
+- get all annotations for a single canvas
+    - SAS route: `GET /annotation/search/?uri=$canvasUri`, where `$canvasUri` is the URI of the canvas for which we want the annotatione
+
+### Create / update data
+
+- import a new IIIF manifest 
+    - SAS route: `POST /manifests`, where the body is the new IIIF manifest
+- import an AnnotationList 
+    - SAS route: `POST /annotation/populate`, where the body is either an URI pointing to an AnnotationList, or the AnnotationList itself
+
+### Delete data
+
+- delete a manifest (actually not 100% sure that this is implemented by SAS)
+    - sas route: `DELETE /manifests`
+- delete an annotation
+    - sas route: `DELETE /annotation/destroy/?uri=$annotationUri` where `$annotationUri` is the ID of the annotation to delete
+
+### Provided by SAS but not currently used in AIKON:
+
+- `POST /annotation/create`: crate a single annotation
+- `POST /annotation/update`: update a single annotation
+
+---
+
+## Not implemented by SAS
+
+### Fetch data
+
+- get all annotations for a single manifest ([code](https://github.com/Aikon-platform/aikon/blob/cc8430c52e205e6a1c04c4ae84f69126fb5a3bda/front/app/webapp/utils/iiif/annotation.py#L32)).
+    - this behaviour is implemented by SAS but results are paginated which requires to run several queries
+- get the total number of annotations in a single manifest ([code](https://github.com/Aikon-platform/aikon/blob/cc8430c52e205e6a1c04c4ae84f69126fb5a3bda/front/app/webapp/utils/iiif/annotation.py#L648))
+- get all annotations for a specific canvas
+- get all annotations for a range of canvases
+- have several "export format" for an annotation:
+    - IIIF annotation of course
+      ```
+      {
+            "@id" : "http://aikon.enpc.fr/sas/annotation/wit69_man69_anno134_c179_23f885ed66914139ab7d67d22f8f8f46",
+            "@type" : "oa:Annotation",
+            "dcterms:created" : "2025-03-03T14:40:57",
+            "dcterms:modified" : "2025-03-03T14:40:57",
+            "resource" : {
+              "@type" : "dctypes:Text",
+              "format" : "text/html",
+              "chars" : "<p></p>",
+              "https://aikon.enpc.fr/sas/full_text" : "",
+              "https://iscd.huma-num.fr/sas/full_text" : ""
+            },
+            "on" : "https://aikon.enpc.fr/aikon/iiif/v2/wit69_man69_anno134/canvas/c179.json#xywh=52,1221,891,54",
+            "motivation" : [ "oa:tagging", "oa:commenting" ],
+            "@context" : "http://iiif.io/* TLSv1.2 (IN), TLS header, Supplemental data (23):
+        api/presentation/2/context.json",
+            "label" : ""
+      }
+      ```
+    - standardized metadata (used in application for svelte) (e.g. `https://iscd.huma-num.fr/vhs/witness/2339/regions/canvas`)
+      ```
+      r_annos[canvas][aid] = {
+            "id": aid,
+            "ref": f"{img}_{xywh}",
+            "class": "Region",
+            "type": get_name("Regions"),
+            "title": region_title(canvas, xywh),
+            "url": gen_iiif_url(img, res=f"{xywh}/full/0"),
+            "canvas": canvas,
+            "xywh": xywh.split(","),
+            "img": img,
+      }
+      ```
+    - only ids
+      ```
+      manifest_annotations.extend(
+          annotation["@id"] for annotation in annotations["resources"]
+      )
+      ```
+    - API url list (e.g. [`https://iscd.huma-num.fr/vhs/witness/2339/regions/canvas`](https://iscd.huma-num.fr/vhs/wit249_man249_anno249/list/))
+      ```
+      "wit249_man249_0021_695,1020,123,214": "https://iscd.huma-num.fr/iiif/2/wit249_man249_0021.jpg/695,1020,123,214/full/0/default.jpg",
+      "wit249_man249_0021_880,1032,421,135": "https://iscd.huma-num.fr/iiif/2/wit249_man249_0021.jpg/880,1032,421,135/full/0/default.jpg",
+      "wit249_man249_0021_167,1282,505,770": "https://iscd.huma-num.fr/iiif/2/wit249_man249_0021.jpg/167,1282,505,770/full/0/default.jpg",
+      "wit249_man249_0021_308,1179,220,236": "https://iscd.huma-num.fr/iiif/2/wit249_man249_0021.jpg/308,1179,220,236/full/0/default.jpg",
+      "wit249_man249_0021_207,1013,468,149": "https://iscd.huma-num.fr/iiif/2/wit249_man249_0021.jpg/207,1013,468,149/full/0/default.jpg"
+      ```
+
+### Create / update data
+
+- index all annotations for a manifest in 1 query ([code](https://github.com/Aikon-platform/aikon/blob/cc8430c52e205e6a1c04c4ae84f69126fb5a3bda/front/app/webapp/utils/iiif/annotation.py#L197)).
+
+### Delete data
+
+- unindex a manifest ([code](https://github.com/Aikon-platform/aikon/blob/cc8430c52e205e6a1c04c4ae84f69126fb5a3bda/front/app/webapp/utils/iiif/annotation.py#L769))
+- remove all annotations for a single manifest in 1 query ([code](https://github.com/Aikon-platform/aikon/blob/cc8430c52e205e6a1c04c4ae84f69126fb5a3bda/front/app/webapp/utils/iiif/annotation.py#L798)). currently, we need to 
+    - loop over each canvas in a manifest
+    - loop over each annotation in the canvas
+    - delete that annotation in an HTTP request => tons of HTTP requests
+
+### Other
+
+- annotations should be ordered by their position on the page (or have a method that returns annotations ordered)
+- store rectangular annotations (bounding boxes) as well as polygonal annotations
+- canvas number management:
+    - annotation should have their canvas number as standard metadata (for now we need to parse `canvas = anno["on"].split("/canvas/c")[1].split(".json")[0]` 😰)
+    - make annotations ordered not alphabetically (137 arriving before 14) but by canvas order
+    - technically, this means that, when saving an annotation, you need to:
+        - fetch the manifest of the `annotation.on`
+        - index it (minimally, as a manifest URL + ordered array of canvases)
+        - extract the proper canvas number for the current annotation
+        - save in the annotation the canvas number
+- Create a pipeline to import SAS annotation inside new server easily
+
+

package/eslint.config.js

@@ -0,0 +1,27 @@
+import js from "@eslint/js";
+import globals from "globals";
+import json from "@eslint/json";
+import css from "@eslint/css";
+import { defineConfig, globalIgnores } from "eslint/config";
+import stylistic from "@stylistic/eslint-plugin"
+
+/** https://eslint.org/docs/latest/use/configure/rules */
+export default defineConfig([
+  {
+    files: ["**/*.{js,mjs,cjs}"],
+    plugins: {
+      "js": js,
+      "@stylistic": stylistic
+    },
+    extends: ["js/recommended"],
+    languageOptions: { globals: {...globals.browser, ...globals.node} },
+    rules: {
+      "no-unused-vars": "off",
+      "quotes": ["error", "double"],
+      "@stylistic/indent": ["error", 2],
+    },
+  },
+  { files: ["**/*.json"], plugins: { json }, language: "json/json", extends: ["json/recommended"] },
+  { files: ["**/*.css"], plugins: { css }, language: "css/css", extends: ["css/recommended"] },
+  globalIgnores(["package-lock.json"]),
+]);

package/migrations/baseConfig.js

@@ -0,0 +1,56 @@
+import path from "path";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * @typedef Config
+ * @type {object}
+ * @property {string} connString
+ * @property {dbName} dbName
+ * @property {migrationsDir} migrationsDir
+ */
+
+// path to dirctory of curent file
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * generate a migrate-mongo config file based on options defined in `mongoConfig`.
+ * the object returned here is a copy of what's generated by `migrate-mongo init`.
+ * @param {Config} config */
+export default (config) => ({
+  mongodb: {
+    url: config.connString,
+
+    databaseName: config.dbName,
+
+    options: {
+      useNewUrlParser: true, // removes a deprecation warning when connecting
+      useUnifiedTopology: true, // removes a deprecating warning when connecting
+      //   connectTimeoutMS: 3600000, // increase connection timeout to 1 hour
+      //   socketTimeoutMS: 3600000, // increase socket timeout to 1 hour
+    }
+  },
+
+  // The migrations dir, can be an relative or absolute path. Only edit this when really necessary.
+  migrationsDir: path.join(path.resolve(__dirname), "migrationScripts"),
+
+  // The mongodb collection where the applied changes are stored. Only edit this when really necessary.
+  changelogCollectionName: "changelog",
+
+  // The mongodb collection where the lock will be created.
+  lockCollectionName: "changelog_lock",
+
+  // The value in seconds for the TTL index that will be used for the lock. Value of 0 will disable the feature.
+  lockTtl: 0,
+
+  // The file extension to create migrations and search for in migration dir
+  migrationFileExtension: ".js",
+
+  // Enable the algorithm to create a checksum of the file contents and use that in the comparison to determine
+  // if the file should be run.  Requires that scripts are coded to be run multiple times.
+  useFileHash: false,
+
+  // Don't change this, unless you know what you're doing
+  //NOTE: default value is 'commonjs'
+  moduleSystem: "esm",
+})

package/migrations/manageIndex.js

@@ -0,0 +1,55 @@
+/**
+ * utility functions to create/remove an index
+ */
+
+/**
+ * @typedef IndexSpecType
+ * @type {object}
+ * @property {string} indexName - the name of the index we're creating
+ * @property {any} [prop] - any other key-value pairs are allowed
+ */
+
+/** @typedef {import("mongodb").IndexSpecification} IndexSpecificationType */
+/** @typedef {import("mongodb").Db} DbType */
+/** @typedef {import("mongodb").CreateIndexesOptions} CreateIndexesOptionsType */
+
+
+/**
+ * @param {CreateIndexesOptionsType} indexOptions - indexOptions.name MUST be defined !
+ */
+const validateIndexOptions = (indexOptions) => {
+  if ( indexOptions.name == null ) {
+    throw new Error("indexOptions.name must be defined !")
+  }
+}
+
+/**
+ *
+ * @param {DbType} db
+ * @param {string} collectionName
+ * @param {IndexSpecificationType} indexSpec
+ * @param {CreateIndexesOptionsType} indexOptions - indexOptions.name MUST be defined !
+ */
+async function createIndex(db, collectionName, indexSpec, indexOptions) {
+  validateIndexOptions(indexOptions);
+  const collection = db.collection(collectionName);
+  const result = await collection.createIndex(indexSpec, indexOptions);
+  console.log("created index:", result);
+}
+
+/**
+ * @param {DbType} db
+ * @param {string} collectionName
+ * @param {CreateIndexesOptionsType} indexOptions - indexOptions.name MUST be defined !
+ */
+async function removeIndex(db, collectionName, indexOptions) {
+  validateIndexOptions(indexOptions);
+  const collection = db.collection(collectionName);
+  const result = await collection.dropIndex(indexOptions.name);
+  console.log("dropped index:", result);
+}
+
+export {
+  createIndex,
+  removeIndex
+}

package/migrations/migrate-mongo-config-main.js

@@ -0,0 +1,8 @@
+import baseConfig from "#migrations/baseConfig.js";
+
+const config = {
+  connString: process.env.MONGODB_CONNSTRING,
+  dbName: process.env.MONGODB_DB
+}
+
+export default baseConfig(config);

package/migrations/migrate-mongo-config-test.js

@@ -0,0 +1,8 @@
+import baseConfig from "#migrations/baseConfig.js";
+
+const config = {
+  connString: process.env.MONGODB_CONNSTRING_TEST,
+  dbName: process.env.MONGODB_DB_TEST
+}
+
+export default baseConfig(config);

package/migrations/migrationScripts/20250825185706-collections.js

@@ -0,0 +1,41 @@
+/**
+ * create the collections of the database (without schema)
+ * - annotations3 : annotations following the w3c Web Annotations standard (used by IIIF 3.0 presentation API)
+ * - annotations2 : annotations following the Open Annotations standard (used by IIIF 2.1 presentation API)
+ * - manifests3   : IIIF manifests following the IIIF 3.0 presentation API
+ * - manifests2   : IIIF manifests following the IIIF 2.1 (and 2.0) presentation API
+ */
+
+const collectionNames = [
+  "annotations3",
+  "annotations2",
+  "manifests3",
+  "manifests2"
+];
+
+/**
+ * @param {import('mongodb').Db} db
+ * @param {import('mongodb').MongoClient} client
+ * @returns {Promise<void>}
+ */
+export const up = async (db, client) => {
+  // See https://github.com/seppevs/migrate-mongo/#creating-a-new-migration-script
+  collectionNames.forEach((colName) => {
+    db.createCollection(colName);
+  })
+};
+
+/**
+ * @param {import('mongodb').Db} db
+ * @param {import('mongodb').MongoClient} client
+ * @returns {Promise<void>}
+ */
+export const down = async (db, client) => {
+  // Example:
+  // await db.collection('albums').updateOne({artist: 'The Beatles'}, {$set: {blacklisted: false}});
+  collectionNames.forEach(async (colName) => {
+    const collection = db.collection(colName);
+    await collection.drop();
+  })
+}
+

package/migrations/migrationScripts/20250826194832-annotations2-canvas-index.js

@@ -0,0 +1,31 @@
+/**
+ * create a text index in collection `annotations2` on annotation targets;
+ * indexes key is `on.full` that describes the target canvases for each annotation.
+ */
+
+const
+  colName = "annotations2",
+  indexSpec = { "on.full": 1 },
+  indexOptions = { name: "canvasIdIndex" };
+
+/**
+ * @param {import('mongodb').Db} db
+ * @param {import('mongodb').MongoClient} client
+ * @returns {Promise<void>}
+ */
+export const up = async (db, client) => {
+  const collection = db.collection(colName);
+  const result = await collection.createIndex(indexSpec, indexOptions);
+  console.log("created index:", result);
+};
+
+/**
+ * @param {import('mongodb').Db} db
+ * @param {import('mongodb').MongoClient} client
+ * @returns {Promise<void>}
+ */
+export const down = async (db, client) => {
+  const collection = db.collection(colName);
+  const result = await collection.dropIndex(indexOptions.name);
+  console.log("dropped index:", result);
+};

package/migrations/migrationScripts/20250904080710-annotations2-schema.js

@@ -0,0 +1,42 @@
+/**
+ * define the validation schema on collection `annotations2`.
+ */
+import build from "#src/app.js"
+
+// const inspect = (theObj) => util.inspect(theObj, {showHidden: false, depth: null, colors: true});
+
+/**
+ * @param db {import('mongodb').Db}
+ * @param client {import('mongodb').MongoClient}
+ * @returns {Promise<void>}
+ */
+export const up = async (db, client) => {
+  const
+    fastify = await build(),
+    fastifySchema = fastify.schemasPresentation2.getSchema("annotation"),
+    schema = fastify.schemasResolver(fastifySchema),
+    commandDoc = {
+      collMod: "annotations2",
+      validator: { $jsonSchema: schema }
+    },
+    r = await db.command(commandDoc);
+
+  if ( r.ok !== 1 ) {
+    throw new Error(`command failed with error: ${r}`);
+  }
+};
+
+/**
+ * @param db {import('mongodb').Db}
+ * @param client {import('mongodb').MongoClient}
+ * @returns {Promise<void>}
+ */
+export const down = async (db, client) => {
+  const r = await db.command({
+    collMod: "annotations2",
+    validator: {}
+  });
+  if ( r.ok !== 1 ) {
+    throw new Error(`command failed with error: ${r}`);
+  }
+};