aiiinotate 0.6.2 → 0.7.0

package/config/.env.template

@@ -16,6 +16,8 @@ AIIINOTATE_SCHEME=http
 
 # max number of items to display per result page
 AIIINOTATE_PAGE_SIZE=5000
+# "true"|"false". strict error throwing when inserting annotations. equivalent to `throwOnCanvasIndexError=true` (raise an error if an annotation's target manifest can't be found) and `throwOnXywhError=true` (raise an error if you can't extract a bounding box for an annotation's target). use in controlled environments where you know precisely the structure of your annotations and where you know that your manifests are accessible through HTTP.
+AIIINOTATE_STRICT_MODE=false
 
 # IGNORE
 AIIINOTATE_BASE_URL="$AIIINOTATE_SCHEME://$AIIINOTATE_HOST:$AIIINOTATE_PORT"

package/docs/endpoints.md

@@ -72,7 +72,8 @@ AnnotationList | AnnotationPage | string[]
 - Only exact matches are allowed for `q` and `motivation`
 - About `canvasMin` and `canvasMax`:
     - they are used to search for annotations that target a range of canvases: for example, fetch all anotations between pages 3 and 30 of a manuscript.
-    - See section **Create/update an annotation** for more information and possible issues with canvas indexes.
+    - they are **0-indexed**: the 1st canvas of a manifest is indexed `0`, the 2nd is indexed `1`...
+    - See section [Create/update an annotation](#createupdate-an-annotation) for more information and possible issues with canvas indexes.
 
 ---
 
@@ -238,7 +239,8 @@ Create or update a single annotation
     - `iiif_version` (`2 | 3`): the IIIF version of the annotation
     - `action` (`create | update`): the action to perform: create or update an annotation
 - Query:
-    - `throwOnCanvasIndexError` (`boolean`): if there is an error fetching the related manifest, or getting a target canvas' index, throw an error.
+    - `throwOnCanvasIndexError` (`boolean`): throw an error if there's a problem fetching the annotation's target canvas index. See [Appendix 1](#appendix-1-annotation-canvas-index-and-bounding-box-calculation)
+    - `throwOnXywhError` (`boolean`): throw an error if target bounding box calculation fails. See [Appendix 1](#appendix-1-annotation-canvas-index-and-bounding-box-calculation)
 - Body (`Object`): a IIIF annotation that follows the IIIF Presentation API 2 or 3 (depending on the value of `iiif_version`)
 
 #### Response
@@ -252,21 +254,6 @@ Create or update a single annotation
 }
 ```
 
-#### Notes
-
-- A side effect of inserting annotations is inserting the related manifests.
-- When inserting an annotation, the annotation's target manifest is also fetched and inserted in the database
-- Annotations in `aiiinotate` contain 3 nonstandard fields. In IIIF presentation 2.x,
-    - `annotation.on[0].manifestUri`: the URI of the manifest on which is an annotation
-    - `annotation.on[0].manifestShortId`: the unique identifier of the manifest on which is an annotation
-    - `annotation.on[0].canvasIdx`: the position of an annotation's target canvas within the target manifest, as an integer
-    - this depends on reconstructing an annotation's target manifest URL and fetching it. If this process fails, the fields above will be `undefined`.
-    - the annotation's target's manifest is fetched and inserted in the database, if possible, and stored in `annotation.on[0].manifestShortId`
-- If `throwOnCanvasIndexError`, an error will be thrown if an error appears anywhere in the proicess of fetching the target manifest or populating the `canvasIdx` field.
-    - fetching an annotation's target manfest is error prone: it depends on the manifest being available through HTTP, which is not in our control.
-    - in turn, normally, if there's an error, we will just add the issue to `fetchErrorIds` and not throw.
-    - in controlled environments where you know your manifests WILL be available and where you rely heavily on the `canvasIdx` field (like AIKON), throwing an error will ensure that the `canvasIdx` field is always defined.
-
 ---
 
 ### Insert several annotations
@@ -279,8 +266,11 @@ Batch insert multiple annotations.
 
 #### Request
 
-- Query:
+- Parameters:
     - `iiif_version` (`2 | 3`): the IIIF version of the annotation
+- Query:
+    - `throwOnCanvasIndexError` (`boolean`): throw an error if there's a problem fetching the annotation's target canvas index. See [Appendix 1](#appendix-1-annotation-canvas-index-and-bounding-box-calculation)
+    - `throwOnXywhError` (`boolean`): throw an error if target bounding box calculation fails. See [Appendix 1](#appendix-1-annotation-canvas-index-and-bounding-box-calculation)
 - Body: either:
     - a full `AnnotationList | AnnotationPage` embedded in the body (type must match `iiif_version`: AnnotationPage for IIIF 3, AnnotationList for IIIF 2).
     - `AnnotationList[] | AnnotationPage[]` (type must match `iiif_version`): an array of annotation lists or pages
@@ -305,7 +295,42 @@ Batch insert multiple annotations.
 
 ---
 
-## Appending 1: App logic: URL prefixes
+## Appendix 1: annotation canvas index and bounding box calculation
+
+Two non-standard side-effects happen when inserting an annotation:
+- the annotation's target manifest is also fetched and inserted in the database. The annotation's target canvas index is fetched and added to the annotation.
+- calculating the XYWH bounding box of an annotation.
+
+Annotations in `aiiinotate` contain nonstandard fields. In IIIF presentation 2.x,
+- `manifestUri`, `manifestShortId`, `canvasIdx`:
+    - `annotation.on.manifestUri`: the URI of the manifest on which is an annotation
+    - `annotation.on.manifestShortId`: the unique identifier of the manifest on which is an annotation
+    - `annotation.on.canvasIdx`: the position of an annotation's target canvas within the target manifest, as an integer. `canvasIdx` is **0-indexed**: the 1st canvas in a manifest is indexed from `0`
+    - this relies on reconstructing an annotation's target manifest URL and fetching it. If this process fails, the fields above will be `undefined`.
+    - fetching an annotation's target manfest is error prone: it depends on the manifest being available through HTTP, which is not in our control.
+    - **you can control error throwing** (throw an error if a canvas index can't be found) using:
+        - at route-level, the `throwOnCanvasIndexError` query parameter
+        - at app-level, the `AIIINOTATE_STRICT_MODE` env variable.
+        - if `AIIINOTATE_STRICT_MODE` or `throwOnCanvasIndexError`, an error will be thrown if an error appears anywhere in the process of fetching the target manifest and populating the `canvasIdx` field.
+- `annotation.on.xywh`: the annotation's bounding box on its target canvas.
+    - when inserting an annotation, aiiinotate will attempt to extract its XYWH bounding box and store it as an `[number,number,number,number]`.
+    - this only works for `oa:SvgSelectors`, `oa:FragmentSeletors`, `oa:Choice` containing either an `SvgSelector` or a `FragmentSelector`, or a string-target (an URI with a `#xywh=` fragment selector).
+    - **you can control error-throwing** (throw an error if a bounding-box can't be calculated) using:
+        - at route-level, the `throwOnXywhError` query parameter
+        - at app-level, the `AIIINOTATE_STRICT_MODE` env variable.
+
+About `throwOnCanvasIndexError`, `throwOnXywhError` and `AIIINOTATE_STRICT_MODE`:
+- as indicated above, fetching an annotation's target canvas index and calculating an annotation's target bounding boxc is error prone.
+- in turn, you can decide wether or not to throw errors using:
+    - at route-level, the `throwOnCanvasIndexError` (for canvas index) and `throwOnXywhError` (for bounding box) query parameters
+    - at app-level, the `AIIINOTATE_STRICT_MODE` env variable. Setting this to `true` will set the value of `throwOnCanvasIndexError` and `throwOnXywhError` to `true` by default.
+    - the value of `AIIINOTATE_STRICT_MODE` can be overridden by setting a value to query parameters `throwOnCanvasIndexError` and `throwOnXywhError`.
+- if those are set to `true`, an error will be thrown if a canvas index can't be found. Otherwise, the values will be set to `undefined`.
+- in controlled environments where you know your manifests will be available and where you rely heavily on the `canvasIdx` field (like AIKON), throwing an error will ensure that the `canvasIdx` field is always defined.
+
+---
+
+## Appendix 2: App logic: URL prefixes
 
 URL anatomy is a mix of [SAS endpoints](./specifications/4_sas.md) and IIIF specifications. In turn, we define the following prefixes:
 
@@ -333,7 +358,7 @@ There is an extra URL prefix: `schemas`. It is only used internally (not accessi
 
 ---
 
-## Appendix 2: IIIF URIs
+## Appendix 3: IIIF URIs
 
 IIIF URIs in the Presentation 2.1 API are:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiiinotate",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "a fast IIIF-compliant annotation server",
   "main": "./cli/index.js",
   "type": "module",

package/src/data/annotations/annotations2.js

@@ -6,7 +6,7 @@ import fastifyPlugin from "fastify-plugin";
 
 import CollectionAbstract from "#data/collectionAbstract.js";
 import { IIIF_PRESENTATION_2_CONTEXT } from "#utils/iiifUtils.js";
-import { ajvCompile, objectHasKey, isNullish, maybeToArray, inspectObj, visibleLog, memoize } from "#utils/utils.js";
+import { ajvCompile, objectHasKey, isNullish, maybeToArray, visibleLog, memoize, STRICT_MODE } from "#utils/utils.js";
 import { getManifestShortId, makeTarget, makeAnnotationId, toAnnotationList, canvasUriToManifestUri } from "#utils/iiif2Utils.js";
 
 
@@ -128,17 +128,24 @@ class Annotations2 extends CollectionAbstract {
    * some of the work consists of translating what is defined by the OpenAnnotations standard to what is actually used by IIIF annotations.
    * if `update`, some cleaning will be skipped (especially the redefinition of "@id"), otherwise updates would fail.
    *
-   * @param {object} annotation
-   * @param {boolean} update - set to `true` if performing an update instead of an insert.
+   * @param {{ annotation: object, update: boolean, throwOnXywhError: boolean }} annotation
    * @returns {object}
    */
-  async #cleanAnnotation(annotation, update=false) {
+  async #cleanAnnotation({
+    annotation,
+    update=false,
+    throwOnXywhError=STRICT_MODE
+  }) {
     // 1) extract ids and targets. convert the target to an array.
     // we assume that all values of `annotationTargetArray` point to the same manifest => `manifestShortId` is extracted from the 1st target
     const
       annotationTargetArray = await makeTarget(annotation),
       manifestShortId = annotationTargetArray[0].manifestShortId;
 
+    if ( throwOnXywhError && annotationTargetArray[0]?.xywh.some(x => isNaN(x)) ) {
+      throw this.insertError("annotations2.#cleanAnnotation: could not extract bounding box for annotation target", annotation.on);
+    }
+
     // in updates, "@id" has aldready been extracted
     if ( !update ) {
       annotation["@id"] = makeAnnotationId(annotation, manifestShortId);
@@ -183,17 +190,17 @@ class Annotations2 extends CollectionAbstract {
    * take an annotationList, clean it and return it as a array of annotations.
    * see: https://iiif.io/api/presentation/2.1/#annotation-list
    * @param {object} annotationList
-   * @returns {object[]}
+   * @param {boolean} throwOnXywhError
+   * @returns {Promise<object[]>}
    */
-  async #cleanAnnotationList(annotationList) {
+  async #cleanAnnotationList(annotationList, throwOnXywhError=STRICT_MODE) {
     // NOTE: if `this.#cleanAnnotationList` can only be accessed from annotations routes, then this check is useless (has aldready been performed).
     if ( this.validatorAnnotationList(annotationList) ) {
       this.errorNoAction("Annotations2.#cleanAnnotationList: could not recognize AnnotationList. see: https://iiif.io/api/presentation/2.1/#annotation-list.", annotationList)
     }
-    //NOTE: using an arrow function is necessary to avoid losing the scope of `this`. otherwise, `this` is undefined in `#cleanAnnotation`.
     return await Promise.all(
       annotationList.resources.map(async (ressource) =>
-        await this.#cleanAnnotation(ressource)
+        await this.#cleanAnnotation({ annotation: ressource, throwOnXywhError })
       )
     )
   }
@@ -206,7 +213,7 @@ class Annotations2 extends CollectionAbstract {
    * @param {object|object[]} annotationData - an annotation, or array of annotations.
    * @param {boolean} throwOnCanvasIndexError - if canvasIdx can't be found, raise an error.
    */
-  async #insertManifestsAndGetCanvasIdx(annotationData, throwOnCanvasIndexError=false) {
+  async #insertManifestsAndGetCanvasIdx(annotationData, throwOnCanvasIndexError=STRICT_MODE) {
     // NOTE: instead of propagating `throwOnCanvasIndexError` to `insertManifestsFromUriArray`, we could just check if `insertResponse.fetchErrorIds.length > 0` and return an error then.
     // convert objects to array to get a uniform interface.
     let converted;
@@ -322,12 +329,17 @@ class Annotations2 extends CollectionAbstract {
    * when inserting, aiiinotate attempts to fetch the target manifest of an annotation and to add the canvas number of the annotation to `annotation.on`.
    * this may fail for a number of reasons (manifest URL and JSON structure, server storing the manifest is inaccessible...). if `throwOnCanvasIndexError`, it will raise.
    *
+   * about `throwOnXywhError`: XYWH bounding-box extraction of an annotation is not supported for all selectors (see: `selectorToXywh()`).
+   * by default, no error is raised if a bounding box can't be extracted.
+   * if `throwOnXywhError`, an error will be thrown. this is for controlled environments where you know exactly what you'll be sending aiiinotate and must rely on `xywh`
+   *
    * @param {object} annotation
-   * @param {boolean?} throwOnCanvasIndexError
+   * @param {boolean} throwOnCanvasIndexError
+   * @param {boolean} throwOnXywhError
    * @returns {Promise<InsertResponseType>}
    */
-  async insertAnnotation(annotation, throwOnCanvasIndexError=false) {
-    annotation = await this.#cleanAnnotation(annotation);
+  async insertAnnotation(annotation, throwOnCanvasIndexError=STRICT_MODE, throwOnXywhError=STRICT_MODE) {
+    annotation = await this.#cleanAnnotation({ annotation, update: false, throwOnXywhError });
     annotation = await this.#insertManifestsAndGetCanvasIdx(annotation, throwOnCanvasIndexError);
     return this.insertOne(annotation);
   }
@@ -336,11 +348,12 @@ class Annotations2 extends CollectionAbstract {
    * TODO: handle side effects when changing `annotation.on`: changes that can affect `manifestShortId`, `manifestUri` and `canvasIdx`
    *    (for example, updating `annotation.on.full` would ask to change `canvasIdx`).
    * @param {object} annotation
+   * @param {boolean} throwOnXywhError
    * @returns {Promise<UpdateResponseType>}
    */
-  async updateAnnotation(annotation) {
+  async updateAnnotation(annotation, throwOnXywhError=STRICT_MODE) {
     // necessary: on insert, the `@id` received is modified by `this.#cleanAnnotationList`.
-    annotation = await this.#cleanAnnotation(annotation, true);
+    annotation = await this.#cleanAnnotation({ annotation, update: true, throwOnXywhError });
     const
       query = { "@id": annotation["@id"] },
       update = { $set: annotation };
@@ -358,9 +371,9 @@ class Annotations2 extends CollectionAbstract {
    * @param {boolean?} throwOnCanvasIndexError
    * @returns {Promise<InsertResponseType>}
    */
-  async insertAnnotationList(annotationList, throwOnCanvasIndexError) {
+  async insertAnnotationList(annotationList, throwOnCanvasIndexError=STRICT_MODE, throwOnXywhError=STRICT_MODE) {
     let annotationArray;
-    annotationArray = await this.#cleanAnnotationList(annotationList);
+    annotationArray = await this.#cleanAnnotationList(annotationList, throwOnXywhError);
     annotationArray = await this.#insertManifestsAndGetCanvasIdx(annotationArray, throwOnCanvasIndexError);
     return this.insertMany(annotationArray);
   }

package/src/data/annotations/routes.js

@@ -1,6 +1,6 @@
 import fastifyPlugin from "fastify-plugin"
 
-import { pathToUrl, objectHasKey, maybeToArray, inspectObj, throwIfKeyUndefined, throwIfValueError, getFirstNonEmptyPair, visibleLog } from "#utils/utils.js";
+import { pathToUrl, objectHasKey, maybeToArray, throwIfKeyUndefined, throwIfValueError, getFirstNonEmptyPair, visibleLog, STRICT_MODE } from "#utils/utils.js";
 import { makeResponseSchema, makeResponsePostSchema, returnError, addPagination } from "#utils/routeUtils.js";
 
 
@@ -206,11 +206,12 @@ function annotationsRoutes(fastify, options, done) {
             action: { type: "string", enum: [ "create", "update" ] }
           }
         },
-        // NOTE: throwOnCanvasIndexError is only implemented if `action==="create"` (see preValidation)
+        // NOTE: `throwOnCanvasIndexError` is only implemented if `action==="create"` (see preValidation)
         querystring: {
           type: "object",
           properties: {
-            throwOnCanvasIndexError: { type: "boolean" },
+            throwOnCanvasIndexError: { type: "boolean", default: STRICT_MODE },
+            throwOnXywhError: { type: "boolean", default: STRICT_MODE },
           }
         },
         preValidation: async (request, reply) => {
@@ -218,7 +219,7 @@ function annotationsRoutes(fastify, options, done) {
             { action } = request.params,
             { throwOnCanvasIndexError } = request.querystring;
           if ( action==="update" && throwOnCanvasIndexError ) {
-            returnError(request, reply, "'throwOnCanvasIndexError' is only allowed when ':action' is 'create'.")
+            returnError(request, reply, "'throwOnCanvasIndexError' is only allowed when ':action' is 'create'.");
           }
           return;
         },
@@ -229,7 +230,7 @@ function annotationsRoutes(fastify, options, done) {
     async (request, reply) => {
       const
         { iiifPresentationVersion, action } = request.params,
-        { throwOnCanvasIndexError } = request.query,
+        { throwOnCanvasIndexError, throwOnXywhError } = request.query,
         annotation = request.body;
 
       try {
@@ -237,8 +238,8 @@ function annotationsRoutes(fastify, options, done) {
         // insert or update
         if ( iiifPresentationVersion === 2 ) {
           return action==="create"
-            ? await annotations2.insertAnnotation(annotation, throwOnCanvasIndexError)
-            : await annotations2.updateAnnotation(annotation);
+            ? await annotations2.insertAnnotation(annotation, throwOnCanvasIndexError, throwOnXywhError)
+            : await annotations2.updateAnnotation(annotation, throwOnXywhError);
         } else {
           annotations3.notImplementedError();
         }
@@ -275,7 +276,8 @@ function annotationsRoutes(fastify, options, done) {
         querystring: {
           type: "object",
           properties: {
-            throwOnCanvasIndexError: { type: "boolean", },
+            throwOnCanvasIndexError: { type: "boolean", default: STRICT_MODE },
+            throwOnXywhError: { type: "boolean", default: STRICT_MODE },
           }
         },
         body: routeAnnotationCreateManySchema,
@@ -285,7 +287,7 @@ function annotationsRoutes(fastify, options, done) {
     async (request, reply) => {
       const
         { iiifPresentationVersion } = request.params,
-        { throwOnCanvasIndexError } = request.query,
+        { throwOnCanvasIndexError, throwOnXywhError } = request.query,
         body = maybeToArray(request.body),  // convert to an array to have a homogeneous data structure
         insertResponseArray = [];
 
@@ -310,7 +312,7 @@ function annotationsRoutes(fastify, options, done) {
         if ( iiifPresentationVersion === 2 ) {
           await Promise.all(annotationsArray.map(
             async (annotationList) => {
-              const r = await annotations2.insertAnnotationList(annotationList, throwOnCanvasIndexError);
+              const r = await annotations2.insertAnnotationList(annotationList, throwOnCanvasIndexError, throwOnXywhError);
               insertResponseArray.push(r);
             }
           ));

package/src/data/annotations/routes.test.js

@@ -64,7 +64,7 @@ test("test annotation Routes", async (t) => {
     for ( let i=0; i<data.length; i++ ) {
       let [ testData, func ] = data.at(i);
       for ( let i=0; i<testData.length; i++ ) {
-        await func(t, "/annotations/2/createMany", testData.at(i));
+        await func(t, "/annotations/2/createMany?throwOnXywhError=true", testData.at(i));
       }
     }
 
@@ -95,19 +95,10 @@ test("test annotation Routes", async (t) => {
     ]
     for ( const [ testData, func ] of data ) {
       for ( let i=0; i<testData.length; i++ ) {
-        await func(t, "/annotations/2/create", testData.at(i));
+        await func(t, "/annotations/2/create?throwOnXywhError=true", testData.at(i));
       }
     };
 
-    // test throwOnCanvasIndexError
-    const annotationWithTargetError = structuredClone(fastify.fixtures.annotations2Valid.at(0));
-    annotationWithTargetError.on = `https://test/${uuid4()}#xywh=100,100,300,300`;
-    data = [[testPostRouteCreateFailure, true], [testPostRouteCreateSuccess, false]];
-    for (let i=0; i<data.length; i++) {
-      const [func, v] = data.at(i);
-      await func(t, `/annotations/2/create?throwOnCanvasIndexError=${v}`, annotationWithTargetError)
-    }
-
     // test SVG to XYWH conversion
     // 1. insert and assert there was no mistake
     // 2. retrieve the inserted annotation and check its xywh coordinates.
@@ -125,6 +116,34 @@ test("test annotation Routes", async (t) => {
         t.assert.deepStrictEqual(target.xywh.every((i) => !isNaN(i)), true);
       })
     }
+
+    // test throwOnCanvasIndexError
+    let annotationError;
+    annotationError = structuredClone(fastify.fixtures.annotations2Valid.at(0));
+    annotationError.on = `https://test/${uuid4()}#xywh=100,100,300,300`;
+    data = [[testPostRouteCreateFailure, true], [testPostRouteCreateSuccess, false]];
+    for (let i=0; i<data.length; i++) {
+      const [func, v] = data.at(i);
+      await func(t, `/annotations/2/create?throwOnCanvasIndexError=${v}`, annotationError)
+    }
+
+    // test throwOnXywhError. SvgSelectors are not supported, so this should fail
+    annotationError = structuredClone(fastify.fixtures.annotations2Valid.at(0));
+    // NOTE : this is an SVG selector and not a CSS selector !!!!
+    annotationError.on = {
+      "@type": "oa:SpecificResource",
+      "full": "https://aikon.enpc.fr/aikon/iiif/v2/wit9_man11_anno165/canvas/c11.json",
+      selector: {
+        "@context": "http://iiif.io/api/annex/openannotation/context.json",
+        "@type": "iiif:ImageApiSelector",
+        "region": "50,50,1250,1850"      }
+    }
+    data = [[testPostRouteCreateFailure, true], [testPostRouteCreateSuccess, false]];
+    for (let i=0; i<data.length; i++) {
+      const [func, v] = data.at(i);
+      await func(t, `/annotations/2/create?throwOnXywhError=${v}`, annotationError);
+    }
+
   })
 
   await t.test("test route /annotations/:iiifPresentationVersion/update", async (t) => {

package/src/data/routes.test.js

@@ -35,51 +35,6 @@ test("test common routes", async (t) => {
   ////////////////////////////////////////////////
   // GET routes
 
-  // NOTE: testing canvasMin/canvasMax parameters on the `search-api` would be good but is too complicated (would require storing the manifests on a live server so they can be queried through HTTP). so we drop the tests for now
-  //  await t.test("test route /search-api/:iiifSearchVersion/manifests/:manifestShortId/search", async (t) => {
-  //    const [manifest, annotationList] = fastify.fixtures.generateIiif2ManifestAndAnnotationsList(1000,1000);
-  //    const rm = await injectPost(fastify, "/manifests/2/create", manifest);
-  //    t.assert.deepStrictEqual(rm.statusCode, 200);
-  //    const ra = await injectPost(fastify, "/annotations/2/createMany", annotationList);
-  //    t.assert.deepStrictEqual(ra.statusCode, 200);
-  //
-  //    // within annotationList, the number of annotations that are between canvases canvasMin and canvasMax
-  //    const
-  //      manifestShortId = getManifestShortId(manifest["@id"]),
-  //      canvasMin = 400,
-  //      canvasMax = 600,
-  //      rangeCanvasIds =
-  //        manifest.sequences[0].canvases
-  //          .slice(canvasMin, canvasMax)
-  //          .map((canvas) => canvas["@id"]),
-  //      annotationCount = annotationList.resources.filter((annotation) =>
-  //        rangeCanvasIds.includes(annotation.on.split("#")[0])
-  //      ).length;
-  //
-  //    const x = await injectGet(fastify, `/search-api/1/manifests/${manifestShortId}/search`);
-  //    console.log(visibleLog(await x.json()));
-  //    console.log(manifestShortId);
-  //
-  //    // now, check that search-api with canvasMin / canvasMax has the same result as annotationCount
-  //    const
-  //      rCanvasRange = await injectGet(fastify, `/search-api/1/manifests/${manifestShortId}/search?canvasMin=${canvasMin}&canvasMax=${canvasMax}`),
-  //      rCanvasRangeBody = await rCanvasRange.json(),
-  //      rCanvasRangeCount = rCanvasRangeBody.length;
-  //    console.log(rCanvasRangeBody);
-  //    t.assert.deepStrictEqual(rCanvasRange.statusCode, 200);
-  //    t.assert.deepStrictEqual(rCanvasRangeCount, annotationCount);
-  //
-  //    // NOTE I THINK I'M GONNA HAVE TO DROP THE preExistingIds TESTING.
-  //    // it's wayyyy to convoluted to handle dummy URLs pointing to nopn existant files.
-  //    // in real life, canvasMin/canvasMax do seem to work.
-  //
-  //    // q
-  //    // motivation
-  //    // canvasMin
-  //    // canvasMax
-  //
-  //  })
-
   await t.test("test route /search-api/:iiifPresentationVersion/manifests/:manifestShortId/search", async (t) => {
     await injectTestAnnotations(fastify, t, annotationList);
 

package/src/schemas/schemasPresentation2.js

@@ -7,7 +7,7 @@ import { IIIF_PRESENTATION_2, IIIF_PRESENTATION_2_CONTEXT } from "#utils/iiifUti
 // TODO: schemas are maybe wayyy too strict.
 // convert all enums (the arrays below) to { type: string } ?
 
-const oaSelectorTypes = [
+const oaSelectorValues = [
   "oa:FragmentSelector",
   "oa:CssSelector",
   "oa:XPathSelector",
@@ -67,14 +67,6 @@ const getSchema = (fastify, slug) =>
 
 function addSchemas(fastify, options, done) {
 
-  /////////////////////////////////////////////
-  // GENERIC STUFF
-
-  fastify.addSchema({
-    $id: makeSchemaUri("context"),
-    type: "string",
-    enum: [ IIIF_PRESENTATION_2_CONTEXT["@context"] ]
-  });
 
   /////////////////////////////////////////////
   // SPECIFIC RESOURCES
@@ -83,14 +75,14 @@ function addSchemas(fastify, options, done) {
   fastify.addSchema({
     $id: makeSchemaUri("iiifImageApiSelector"),
     type: "object",
-    required: [ "@id", "@type", "@context" ],
+    required: [ "@type", "@context" ],
     properties: {
       "@id": { type: "string" },
       "@type": {
         type: "string",
         enum: [ "iiif:ImageApiSelector" ]
       },
-      "@context": { $ref: makeSchemaUri("context") },
+      "@context": { type: "string" },
       region: { type: "string" },
       size: { type: "string" },
       rotation: { type: "string" },
@@ -108,17 +100,17 @@ function addSchemas(fastify, options, done) {
     properties: {
       "@id": { type: "string" },
       "@type": {
-        anyOf: [
+        oneOf: [
           {
             type: "string",
-            enum: oaSelectorTypes
+            enum: oaSelectorValues
           },
           {
             // 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
+              enum: oaSelectorValues
             }
           }
         ]
@@ -204,8 +196,13 @@ function addSchemas(fastify, options, done) {
         ]
       },
       xywh: {
-        type: "array",
-        items: { type: "number" }
+        oneOf: [
+          {
+            type: "array",
+            items: { type: "number" }
+          },
+          { type: "null" }
+        ]
       },
       selector: { $ref: makeSchemaUri("selector") },
       purpose: { type: "string" }
@@ -310,7 +307,7 @@ function addSchemas(fastify, options, done) {
     required: [ "@id", "@context", "@type", "motivation", "on" ],
     properties: {
       "@id": { type: "string" },
-      "@context": { $ref: makeSchemaUri("context") },
+      "@context": { type: "string" },
       "@type": { type: "string", enum: [ "oa:Annotation" ] },
       motivation: { $ref: makeSchemaUri("motivation") },
       on: { $ref: makeSchemaUri("annotationTarget") },
@@ -327,7 +324,7 @@ function addSchemas(fastify, options, done) {
     required: ["@id", "@type", "@context", "resources"],
     properties: {
       "@id": { type: "string" },
-      "@context": { $ref: makeSchemaUri("context") },
+      "@context": { type: "string" },
       "@type": {
         type: "string",
         enum: [ "sc:AnnotationList" ]
@@ -403,7 +400,7 @@ function addSchemas(fastify, options, done) {
     type: "object",
     required: [ "@id", "@type", "@context", "members" ],
     properties: {
-      "@context": { $ref: makeSchemaUri("context") },
+      "@context": { type: "string" },
       "@type": { type: "string", enum: [ "sc:Collection" ] },
       "@id": { type: "string" },
       label: { type: "string" },

package/src/schemas/schemasPresentation3.js

@@ -17,19 +17,13 @@ const getSchema = (fastify, 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") },
+      "@context": { type: "string" },
       id: { type: "string" },
       items: {
         type: "array",

package/src/utils/iiif2Utils.js

@@ -193,16 +193,17 @@ const stringToSpecificResource = (target) => {
  * @returns {Promise<object>}
  */
 const makeSingleTarget = async (target) => {
-  const err = new Error(`${makeSingleTarget.name}: could not make target for annotation: 'annotation.on' must be an URI, a SpecificResouece or an array of SpecificResources`, { info: target });
+  const err = new Error(`${makeSingleTarget.name}: could not make target for annotation: 'annotation.on' must be an URI, a SpecificResource or an array of SpecificResources. The key 'SpecificResource.full' MUST be defined.`, { info: target });
 
   let specificResource;
 
-  // 1. convert to SpecificResouece
+  // 1. convert to SpecificResource
   if ( typeof(target) === "string" && !isNullish(target) ) {
     specificResource = stringToSpecificResource(target);
   } else if ( isObject(target) && target["@type"] === "oa:SpecificResource" && !isNullish(target["full"]) ) {
     specificResource = target;
     specificResource.selector = normalizeSelectorType(specificResource.selector);
+
   // if target is neither a string nor a SpecificResource, raise
   } else {
     throw err

package/src/utils/utils.js

@@ -20,7 +20,7 @@ const isNullOrUndefined = (v) => v == null;
 const isNullish = (v) => v == null || !v.length;
 
 /** o is an object but not an array. https://stackoverflow.com/a/44556453 */
-const isObject = (o) => o.constructor === Object;
+const isObject = (o) => o?.constructor === Object;
 
 const isNonEmptyArray = (a) => Array.isArray(a) && a.length;
 
@@ -305,6 +305,8 @@ const memoize = (fn, timeout = 2000) => {
   }
 }
 
+const STRICT_MODE = process.env.AIIINOTATE_STRICT_MODE?.toLowerCase() === "true";
+
 export {
   maybeToArray,
   pathToUrl,
@@ -323,5 +325,6 @@ export {
   visibleLog,
   isNonEmptyArray,
   mergeObjects,
-  memoize
+  memoize,
+  STRICT_MODE
 }