aiiinotate 0.2.0

package/src/fileServer/data/vhs_wit253_man253_anno253_anno-24.json

@@ -0,0 +1 @@
+{"@type": "sc:AnnotationList", "resources": [{"@id": "http://iscd.huma-num.fr/sas/annotation/wit253_man253_anno253_c24_b2204564e1d74023bc38cbd2906e137b", "@type": "oa:Annotation", "dcterms:created": "2025-09-09T11:42:43", "dcterms:modified": "2025-09-09T11:42:43", "resource": [{"@type": "dctypes:Text", "https://iscd.huma-num.fr/sas/full_text": "", "format": "text/html", "chars": "<p></p>"}], "on": [{"@type": "oa:SpecificResource", "within": {"@id": "https://iscd.huma-num.fr/vhs/iiif/v2/wit253_man253_anno253/manifest.json", "@type": "sc:Manifest"}, "selector": {"@type": "oa:Choice", "default": {"@type": "oa:FragmentSelector", "value": "xywh=212,381,1021,1610"}, "item": {"@type": "oa:SvgSelector", "value": "<svg xmlns=\"http://www.w3.org/2000/svg\"><path xmlns='http://www.w3.org/2000/svg' d='M212 381 h 510 v 0 h 510 v 805 v 805 h -510 h -510 v -805Z' id='rectangle_wit253_man253_anno253_c24_b2204564e1d74023bc38cbd2906e137b' data-paper-data='{&quot;strokeWidth&quot;:1,&quot;rotation&quot;:0,&quot;annotation&quot;:null,&quot;nonHoverStrokeColor&quot;:[&quot;Color&quot;,0,1,0],&quot;editable&quot;:true,&quot;deleteIcon&quot;:null,&quot;rotationIcon&quot;:null,&quot;group&quot;:null}' fill-opacity='0' fill='#00ff00' fill-rule='nonzero' stroke='#00ff00' stroke-width='1' stroke-linecap='butt' stroke-linejoin='miter' stroke-miterlimit='10' stroke-dashoffset='0' style='mix-blend-mode: normal'/></svg>"}}, "full": "https://iscd.huma-num.fr/vhs/iiif/v2/wit253_man253_anno253/canvas/c24.json"}], "motivation": ["oa:commenting", "oa:tagging"], "@context": "http://iiif.io/api/presentation/2/context.json"}]}

package/src/fileServer/index.js

@@ -0,0 +1,64 @@
+/**
+ * the `fileServer` plugin makes test files available to the entire fastify app, mostly for testing purposes.
+ */
+import fastifyPlugin from "fastify-plugin";
+
+import { annotations2Invalid, annotations2Valid, annotationListUri, annotationListUriArray, annotationList, annotationListArray, annotationListUriInvalid, annotationListUriArrayInvalid } from "#src/fileServer/annotations.js";
+import { manifest2Valid, manifest2ValidUri, manifest2Invalid, manifest2InvalidUri } from "#fileServer/manifests.js";
+import { readFileToObject } from "#fileServer/utils.js";
+
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+
+
+/**
+ * NOTE: `done` musn't be used with async plugins. it raises an error `FST_ERR_PLUGIN_INVALID_ASYNC_HANDLER`
+ * @param {FastifyInstanceType} fastify  Encapsulated Fastify Instance
+ * @param {object} options
+ */
+async function fileServer(fastify, options) {
+
+  /** route to return a file in `dataDir` */
+  fastify.get(
+    "/fileServer/:fileName",
+    {
+      schema: {
+        params: {
+          type: "object",
+          properties: { fileName: { type: "string" } }
+        }
+      },
+      response: {
+        200: {
+          type: "string"
+        },
+        500: {
+          type: "object",
+          properties: {
+            error: { type: "string" }
+          }
+        }
+      }
+    },
+    (request, reply) => {
+      const { fileName } = request.params;
+      return readFileToObject(fileName);
+    }
+  )
+
+  fastify.decorate("fileServer", {
+    annotationListUri: annotationListUri,
+    annotationListUriArray: annotationListUriArray,
+    annotationList: annotationList,
+    annotationListArray: annotationListArray,
+    annotationListUriArrayInvalid: annotationListUriArrayInvalid,
+    annotationListUriInvalid: annotationListUriInvalid,
+    annotations2Invalid: annotations2Invalid,
+    annotations2Valid: annotations2Valid,
+    manifest2Valid: manifest2Valid,
+    manifest2ValidUri: manifest2ValidUri,
+    manifest2Invalid: manifest2Invalid,
+    manifest2InvalidUri: manifest2InvalidUri
+  });
+}
+
+export default fastifyPlugin(fileServer);

package/src/fileServer/manifests.js

@@ -0,0 +1,14 @@
+import { readFileToObject, toUrl } from "#fileServer/utils.js";
+
+const manifest2ValidUri = { uri: toUrl("bnf_valid_manifest.json") };
+const manifest2Valid = readFileToObject("bnf_valid_manifest.json");
+const manifest2InvalidUri = { uri: toUrl("bnf_invalid_manifest.json") };
+const manifest2Invalid = readFileToObject("bnf_invalid_manifest.json");
+
+
+export {
+  manifest2ValidUri,
+  manifest2Valid,
+  manifest2InvalidUri,
+  manifest2Invalid
+}

package/src/fileServer/utils.js

@@ -0,0 +1,35 @@
+import url from "node:url";
+import path from "node:path";
+import fs from "node:fs";
+
+// path to dirctory of curent file
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+// path to fileServer/data
+const dataDir = path.join(__dirname, "data");
+
+const availableFiles = fs.readdirSync(dataDir);
+
+/**
+ * for simplicity, `readFileToObject` is synchronous. given that `fileServer` should only be used in tests, there is no performance downgrade for the prod server.
+ * @param {string} fn: the filename
+ * @returns {object}
+ */
+const readFileToObject = (fn) => {
+  if ( !availableFiles.includes(fn) ) {
+    throw new Error(`file not found: ${fn}`);
+  }
+  return JSON.parse(fs.readFileSync(path.join(dataDir, fn), { encoding: "utf8" }));
+}
+
+/**
+ * @param {string} fn
+ * @returns {string}
+ */
+const toUrl = (fn) => `${process.env.APP_BASE_URL}/fileServer/${fn}`;
+
+
+export {
+  dataDir,
+  readFileToObject,
+  toUrl
+}

package/src/schemas/index.js

@@ -0,0 +1,20 @@
+import fastifyPlugin from "fastify-plugin";
+
+import schemasBase from "#src/schemas/schemasBase.js";
+import schemasPresentation2 from "#src/schemas/schemasPresentation2.js";
+import schemasPresentation3 from "#src/schemas/schemasPresentation3.js";
+import schemasResolver from "#schemas/schemasResolver.js";
+import schemasRoutes from "#src/schemas/schemasRoutes.js";
+
+function schemas(fastify, options, done) {
+
+  fastify.register(schemasResolver);
+  fastify.register(schemasBase);
+  fastify.register(schemasPresentation2);
+  fastify.register(schemasPresentation3);
+  fastify.register(schemasRoutes);
+
+  done()
+}
+
+export default fastifyPlugin(schemas);

package/src/schemas/schemasBase.js

@@ -0,0 +1,47 @@
+import fastifyPlugin from "fastify-plugin"
+
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+
+/** @param {"search"|"presentation"} slug */
+const makeSchemaUri = (slug) =>
+  `${process.env.APP_BASE_URL}/schemas/${slug}/version`;
+
+/**
+ * @param {FastifyInstanceType} fastify
+ * @param {"search"|"presentation"} slug
+ */
+const getSchema = (fastify, slug) =>
+  fastify.getSchema(makeSchemaUri(slug));
+
+function addSchemas(fastify, options, done) {
+
+  // fastify.decorate("makeSchemaUri", makeSchemaUri);
+  // fastify.decorate("getSchema", (slug) => getSchema(fastify, slug));
+
+  // schemas are defined on the global `fastify` instance
+  fastify.addSchema({
+    $id: makeSchemaUri("presentation"),
+    type: "integer",
+    enum: [2, 3],
+    description: "IIIF presentation API versions"
+  });
+  fastify.addSchema({
+    $id: makeSchemaUri("search"),
+    type: "integer",
+    enum: [1, 2],
+    description: "IIIF search API versions"
+  });
+
+  // functions `makeSchemaUri` and `getSchema`
+  // are defined in an object that is used to decorate the global `fastify` instance,
+  // this namespacing the functions and allowing each plugin
+  // in this module to have functions with the same name.
+  fastify.decorate("schemasBase", {
+    makeSchemaUri: makeSchemaUri,
+    getSchema: (slug) => getSchema(fastify, slug)
+  }) ;
+
+  done()
+}
+
+export default fastifyPlugin(addSchemas);

package/src/schemas/schemasPresentation2.js

@@ -0,0 +1,417 @@
+import fastifyPlugin from "fastify-plugin";
+
+import { IIIF_PRESENTATION_2, IIIF_PRESENTATION_2_CONTEXT } from "#utils/iiifUtils.js";
+
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+
+// TODO: schemas are maybe wayyy too strict.
+// convert all enums (the arrays below) to { type: string } ?
+
+const oaSelectorTypes = [
+  "oa:FragmentSelector",
+  "oa:CssSelector",
+  "oa:XPathSelector",
+  "oa:TextQuoteSelector",
+  "oa:TextPositionSelector",
+  "oa:DataPositionSelector",
+  "oa:SvgSelector",
+  "oa:RangeSelector",
+  "cnt:ContentAsText",  // this one is only described in IIIF Presentation API.
+  // also allow values without extension
+  "FragmentSelector",
+  "CssSelector",
+  "XPathSelector",
+  "TextQuoteSelector",
+  "TextPositionSelector",
+  "DataPositionSelector",
+  "SvgSelector",
+  "RangeSelector",
+  "ContentAsText"
+]
+
+const motivationValues = [
+  "sc:painting",
+  "oa:commenting",
+  "oa:describing",
+  "oa:tagging",
+  "oa:linking",
+  "painting",
+  "commenting",
+  "describing",
+  "tagging",
+  "linking",
+]
+
+const embeddedBodyTypeValues = [
+  "oa:TextualBody",
+  "cnt:ContentAsText",
+  "dctypes:Text",
+  "oa:Tag",
+  "TextualBody",
+  "ContentAsText",
+  "Text",
+  "Tag",
+]
+
+/** @param {string} slug */
+const makeSchemaUri = (slug) =>
+  `${process.env.APP_BASE_URL}/schemas/presentation/${IIIF_PRESENTATION_2}/${slug}`
+
+/**
+ * @param {FastifyInstanceType} fastify
+ * @param {"search"|"presentation"} slug
+ */
+const getSchema = (fastify, slug) =>
+  fastify.getSchema(makeSchemaUri(slug))
+
+
+function addSchemas(fastify, options, done) {
+
+  /////////////////////////////////////////////
+  // GENERIC STUFF
+
+  fastify.addSchema({
+    $id: makeSchemaUri("context"),
+    type: "string",
+    enum: [ IIIF_PRESENTATION_2_CONTEXT["@context"] ]
+  });
+
+  /////////////////////////////////////////////
+  // SPECIFIC RESOURCES
+
+  // derived from: https://iiif.io/api/annex/openannotation/context.json
+  fastify.addSchema({
+    $id: makeSchemaUri("iiifImageApiSelector"),
+    type: "object",
+    required: [ "@id", "@type", "@context" ],
+    properties: {
+      "@id": { type: "string" },
+      "@type": {
+        type: "string",
+        enum: [ "iiif:ImageApiSelector" ]
+      },
+      "@context": { $ref: makeSchemaUri("context") },
+      region: { type: "string" },
+      size: { type: "string" },
+      rotation: { type: "string" },
+      format: { type: "string" },
+      quality: { type: "string" },
+    }
+  });
+
+  // NOTE: we don't support refinedBy and any other recursive selectors.
+  // https://github.com/Aikon-platform/aiiinotate/blob/main/docs/specifications/0_w3c_web_annotations.md#selectors-data-model
+  fastify.addSchema({
+    $id: makeSchemaUri("oaSelector"),
+    type: "object",
+    required: [ "@type" ],  // could also add `value` or `chars` but one or the other may be used, not both.
+    properties: {
+      "@id": { type: "string" },
+      "@type": {
+        anyOf: [
+          {
+            type: "string",
+            enum: oaSelectorTypes
+          },
+          {
+            // IIIF 2.1 has examples with multiple `@types`: // `chars` is used by SvgSelector in: https://iiif.io/api/presentation/2.1/#non-rectangular-segments
+            type: "array",
+            items: {
+              type: "string",
+              enum: oaSelectorTypes
+            }
+          }
+        ]
+      },
+      value: { type: "string" },
+      chars: { type: "string" }  // `chars` is used by SvgSelector in: https://iiif.io/api/presentation/2.1/#non-rectangular-segments
+    }
+  })
+
+  fastify.addSchema({
+    $id: makeSchemaUri("oaOrIiifSelector"),
+    type: "object",
+    oneOf: [
+      { $ref: makeSchemaUri("oaSelector") },
+      { $ref: makeSchemaUri("iiifImageApiSelector") },
+    ]
+  })
+
+  fastify.addSchema({
+    $id: makeSchemaUri("oaChoiceSelector"),
+    type: "object",
+    required: [ "@type", "default" ],
+    properties: {
+      "@type": { type: "string", enum: ["oa:Choice"] },
+      default: { $ref: makeSchemaUri("oaOrIiifSelector") },
+      item: { $ref: makeSchemaUri("oaOrIiifSelector") }
+    }
+  })
+
+  // selector is either a string, string[], iiifImageApiSelector, iiifImageApiSelector[]. oaSelector, oaSelector[]
+  fastify.addSchema({
+    $id: makeSchemaUri("selector"),
+    anyOf: [
+      { type: "string" },
+      { type: "array", items: { type: "string" } },
+      { $ref: makeSchemaUri("oaOrIiifSelector") },
+      { $ref: makeSchemaUri("oaChoiceSelector") },
+      {
+        type: "array",
+        items: { $ref: makeSchemaUri("oaOrIiifSelector") }
+      },
+    ]
+  })
+
+  fastify.addSchema({
+    $id: makeSchemaUri("specificResource"),
+    type: "object",
+    required: [ "@type", "full", "selector" ],
+    properties: {
+      "@id": { type: "string" },
+      "@type": {
+        type: "string",
+        enum: [ "oa:SpecificResource" ]
+      },
+      // NOTE: OA defines a `source` field for SpecificResources, but in IIIF `full` seems to have the same role
+      // https://github.com/Aikon-platform/aiiinotate/blob/main/docs/specifications/0_w3c_web_annotations.md#specific-resources-data-model
+      full: {
+        anyOf: [
+          // URI
+          { type: "string" },
+          // object describing an image
+          {
+            type: "object",
+            required: [ "@id", "@type" ],
+            properties: {
+              "@id": { type: "string" },
+              "@type": { type: "string" }
+            }
+          }
+        ],
+      },
+      selector: { $ref: makeSchemaUri("selector") },
+      purpose: { type: "string" }
+    }
+  })
+
+  /////////////////////////////////////////////
+  // ANNOTATIONS
+  // NOTE : annotations can define both painting and non-painting annotations.
+
+  fastify.addSchema({
+    $id: makeSchemaUri("annotationTarget"),
+    anyOf: [
+      // URI
+      { type: "string" },
+      // SpecificResource
+      { $ref: makeSchemaUri("specificResource") }
+    ]
+  })
+
+  fastify.addSchema({
+    $id: makeSchemaUri("motivation"),
+    anyOf: [
+      { type: "string", enum: motivationValues },
+      {
+        type: "array",
+        items : { type: "string", enum: motivationValues }
+      },
+    ],
+  })
+
+  fastify.addSchema({
+    $id: makeSchemaUri("referencedBody"),
+    type: "object",
+    required: [ "@id", "@type" ],
+    properties: {
+      "@id": { type: "string" },
+      "@type": { type: "string" },  // should match `dctypes:[a-zA-Z]+`. regex is disabled for performance reasons.
+      "format": { type: "string" }  // should be a MimeType.
+    },
+  })
+
+  // embedded textual body
+  fastify.addSchema({
+    $id: makeSchemaUri("embeddedBody"),
+    type: "object",
+    required: [ "@type", "chars" ],
+    properties: {
+      "@type": {
+        anyOf: [
+          {
+            type: "string",
+            enum: embeddedBodyTypeValues
+          },
+          {
+            type: "array",
+            items: {
+              type: "string",
+              enum: embeddedBodyTypeValues
+            }
+          },
+        ]
+      },
+      chars: { type: "string" },
+      motivation: { type: "string" },
+      format: { type: "string" },  // should be a MimeType
+    }
+  })
+
+  fastify.addSchema({
+    $id: makeSchemaUri("body"),
+    oneOf: [
+      { $ref: makeSchemaUri("embeddedBody") },
+      { $ref: makeSchemaUri("referencedBody") },
+      {
+        type: "array",
+        items: {
+          type: "object",
+          anyOf: [
+            { $ref: makeSchemaUri("embeddedBody") },
+            { $ref: makeSchemaUri("referencedBody") },
+          ]
+        }
+      }
+    ]
+  })
+
+  // NOTE: maeData is used by `mirador-annotations-editor` (MAE) to store data specific to that mirador plugin. since MAE is external to the Aikon ecosystem, we don't define it further to avoid errors if/when its data format changes.
+  // we set additionalProperties: true, because otherwise, writing annotations to database will be fine, but sending responses will strip out the contents of maeData.
+  fastify.addSchema({
+    $id: makeSchemaUri("maeData"),
+    additionalProperties: true,
+    type: "object"
+  })
+
+  fastify.addSchema({
+    $id: makeSchemaUri("annotation"),
+    type: "object",
+    required: [ "@id", "@context", "@type", "motivation", "on" ],
+    properties: {
+      "@id": { type: "string" },
+      "@context": { $ref: makeSchemaUri("context") },
+      "@type": { type: "string", enum: [ "oa:Annotation" ] },
+      motivation: { $ref: makeSchemaUri("motivation") },
+      on: { $ref: makeSchemaUri("annotationTarget") },
+      // in OA, one OR the other should be use, but `oneOf` can't be used in `properties`.
+      resource: { $ref: makeSchemaUri("body") },
+      bodyValue: { type: "string" },
+      maeData: { $ref: makeSchemaUri("maeData") }
+    },
+  });
+
+  fastify.addSchema({
+    $id: makeSchemaUri("annotationList"),
+    type: "object",
+    required: ["@id", "@type", "@context", "resources"],
+    properties: {
+      "@id": { type: "string" },
+      "@context": { $ref: makeSchemaUri("context") },
+      "@type": {
+        type: "string",
+        enum: [ "sc:AnnotationList" ]
+      },
+      "resources": {
+        type: "array",
+        items: { $ref: makeSchemaUri("annotation") }
+      }
+    }
+  });
+
+  // NOTE : not sure it's needed.
+  fastify.addSchema({
+    $id: makeSchemaUri("annotationArray"),
+    type: "array",
+    items: { $ref: makeSchemaUri("annotation") }
+  })
+
+  /////////////////////////////////////////////
+  // MANIFESTS
+
+  // internal data model for IIIF manifests, containing just what we need.
+  // manifests are just stored as an @id, a short ID, an array of canvas Ids. we don't need more info.
+  fastify.addSchema({
+    $id: makeSchemaUri("manifestMongo"),
+    type: "object",
+    required: ["@id", "@type", "manifestShortId", "canvasIds"],
+    properties: {
+      "@id": { type: "string" },
+      "@type": { type: "string", enum: ["sc:Manifest"] },
+      manifestShortId: { type: "string" },
+      canvasIds: { type: "array", items: { type: "string" }}
+    }
+  })
+
+  // minimal structure we need to work with a IIIF 2.x manifest.
+  fastify.addSchema({
+    $id: makeSchemaUri("manifestPublic"),
+    type: "object",
+    required: ["@id", "sequences"],
+    properties: {
+      "@id": { type: "string" },
+      sequences: {
+        type: "array",
+        items: {
+          type: "object",
+          required: [ "@id", "canvases" ],
+          properties: {
+            "@id": { type: "string" },
+            canvases: {
+              type: "array",
+              items: {
+                type: "object",
+                required: [ "@id" ],
+                properties: {
+                  "@id": { type: "string" }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  })
+
+  /////////////////////////////////////////////
+  // COLLETION
+
+  fastify.addSchema({
+    $id: makeSchemaUri("collection"),
+    type: "object",
+    required: [ "@id", "@type", "@context", "members" ],
+    properties: {
+      "@context": { $ref: makeSchemaUri("context") },
+      "@type": { type: "string", enum: [ "sc:Collection" ] },
+      "@id": { type: "string" },
+      label: { type: "string" },
+      members: {
+        type: "array",
+        items: {
+          type: "object",
+          required: ["@id"],
+          properties: {
+            "@id": { type: "string" },
+            "@type": { type: "string", enum: [ "sc:Manifest" ] },
+          }
+        }
+      }
+    }
+  });
+
+  /////////////////////////////////////////////
+  // DONE
+
+  fastify.decorate("schemasPresentation2", {
+    makeSchemaUri: makeSchemaUri,
+    getSchema: (slug) => getSchema(fastify, slug)
+  })
+
+  done();
+}
+
+
+
+
+
+export default fastifyPlugin(addSchemas)

package/src/schemas/schemasPresentation3.js

@@ -0,0 +1,57 @@
+import fastifyPlugin from "fastify-plugin";
+
+import { IIIF_PRESENTATION_3, IIIF_PRESENTATION_3_CONTEXT } from "#utils/iiifUtils.js";
+
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+
+/** @param {string} slug */
+const makeSchemaUri = (slug) =>
+  `${process.env.APP_BASE_URL}/schemas/presentation/${IIIF_PRESENTATION_3}/${slug}`
+
+/**
+ * @param {FastifyInstanceType} fastify
+ * @param {"search"|"presentation"} slug
+ */
+const getSchema = (fastify, slug) =>
+  fastify.getSchema(makeSchemaUri(slug))
+
+function addSchemas(fastify, options, done) {
+
+  fastify.addSchema({
+    $id: makeSchemaUri("context"),
+    type: "string",
+    enum: [ IIIF_PRESENTATION_3_CONTEXT["@context"] ]
+  });
+
+  // minimal schema for IIIF manifests3, containing just what we need to process a manifest
+  fastify.addSchema({
+    $id: makeSchemaUri("manifestPublic"),
+    type: "object",
+    required: [ "@context", "id", "items" ],
+    properties: {
+      "@context": { $ref: makeSchemaUri("context") },
+      id: { type: "string" },
+      items: {
+        type: "array",
+        items: {
+          type: "object",
+          required: [ "id" ],
+          properties: {
+            id: { type: "string" }
+          }
+        }
+      }
+    }
+  });
+
+  fastify.decorate("schemasPresentation3", {
+    makeSchemaUri: makeSchemaUri,
+    getSchema: (slug) => getSchema(fastify, slug)
+  });
+
+  done()
+}
+
+export default fastifyPlugin(addSchemas);
+
+