@paulhectork/aiiinotate 0.12.0

package/src/schemas/schemasPresentation2.js

@@ -0,0 +1,410 @@
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+
+// TODO: schemas are maybe wayyy too strict.
+// convert all enums (the arrays below) to { type: string } ?
+
+const oaSelectorValues = [
+  "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",
+]
+
+function addSchemas(fastify, makeSchemaUri) {
+
+  /////////////////////////////////////////////
+  // SPECIFIC RESOURCES
+
+  // derived from: https://iiif.io/api/annex/openannotation/context.json
+  fastify.addSchema({
+    $id: makeSchemaUri("iiifImageApiSelector"),
+    type: "object",
+    required: [ "@type", "@context" ],
+    properties: {
+      "@id": { type: "string" },
+      "@type": {
+        type: "string",
+        enum: [ "iiif:ImageApiSelector" ]
+      },
+      "@context": { type: "string" },
+      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": {
+        oneOf: [
+          {
+            type: "string",
+            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: oaSelectorValues
+            }
+          }
+        ]
+      },
+      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" }
+            }
+          }
+        ],
+      },
+      manifestShortId: { type: "string" },
+      canvasIdx: {
+        anyOf: [
+          { type: "number" },
+          { type: "null" }
+        ]
+      },
+      manifestUri: {
+        anyOf: [
+          { type: "string" },
+          { type: "null" }
+        ]
+      },
+      xywh: {
+        oneOf: [
+          {
+            type: "array",
+            items: { type: "number" }
+          },
+          { type: "null" }
+        ]
+      },
+      selector: { $ref: makeSchemaUri("selector") },
+      purpose: { type: "string" }
+    }
+  })
+
+  /////////////////////////////////////////////
+  // ANNOTATIONS
+  // NOTE : annotations can define both painting and non-painting annotations.
+
+  fastify.addSchema({
+    $id: makeSchemaUri("annotationTarget"),
+    type: "array",
+    items: {
+      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": { type: "string" },
+      "@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": { type: "string" },
+      "@type": {
+        type: "string",
+        enum: [ "sc:AnnotationList" ]
+      },
+      "resources": {
+        type: "array",
+        items: { $ref: makeSchemaUri("annotation") }
+      },
+      "prev": { type: "string" },
+      "next": { type: "string" },
+    }
+  });
+
+  // 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": { type: "string" },
+      "@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" ] },
+          }
+        }
+      }
+    }
+  });
+
+  return fastify;
+}
+
+
+
+
+export default addSchemas;

package/src/schemas/schemasPresentation3.js

@@ -0,0 +1,33 @@
+import fastifyPlugin from "fastify-plugin";
+
+import { IIIF_PRESENTATION_3, IIIF_PRESENTATION_3_CONTEXT } from "#utils/iiifUtils.js";
+
+/** @typedef {import("#types").FastifyInstanceType} FastifyInstanceType */
+
+function addSchemas(fastify, makeSchemaUri) {
+  // 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": { type: "string" },
+      id: { type: "string" },
+      items: {
+        type: "array",
+        items: {
+          type: "object",
+          required: [ "id" ],
+          properties: {
+            id: { type: "string" }
+          }
+        }
+      }
+    }
+  });
+  return fastify
+}
+
+export default addSchemas;
+
+

package/src/schemas/schemasResolver.js

@@ -0,0 +1,71 @@
+import fastifyPlugin from "fastify-plugin";
+
+/**
+ * resolve schemas: convert all references to external schemas to embedded JsonSchemas.
+ *
+ * mongo doesn't implement the whole JSONSchema standard, and in some places in fastify (i.e., routes response schemas), references (`$ref`) are not allowed.
+ * in the app and in this module, our schemas are defined according to the full Fastify implementation, to use the schemas everywhere, we need to convert them.
+ *
+ * conversion primarily means converting all `$ref` references to external schemas to the JsonSchemas referenced.
+ *
+ * JSONSchema has a recursive data model in which a root schema contains  nested schemas in a tree structure. in turn, our conversion function is recursive.
+ *
+ * NOTE: our conversion function DOES NOT DO ALL CONVERSIONS, only what we need.
+ * for example, we suppose that our schemas are built using $ref's to external schemas, and not defining sub-schemas in the `definitions` field.
+ *
+ * see: https://www.mongodb.com/docs/manual/reference/operator/query/jsonSchema/#omissions
+ */
+function schemasResolver (fastify, schema) {
+  const funcName = schemasResolver.name;
+
+  // no need to process strings, booleans or numbers
+  if (typeof schema==="string" || typeof schema==="number" || typeof schema==="boolean") {
+    return schema
+  }
+  // convert each item in arrays
+  else if (Array.isArray(schema)) {
+    return schema.map((item) => schemasResolver(fastify, item));
+  }
+  // convert each key-value pair. this is actually the main part that will delta to the above branches.
+  else if (schema.constructor === Object) {
+    const out = {};
+
+    for (let [ k,v ] of Object.entries(schema)) {
+      // $id is not allowed => remove it
+      if (k==="$id") {
+        continue
+      }
+      // $refs must be resolved => replace the kv pair { $ref: schemaUri } with the corresponding schemas and process convert those schemas to mongo.
+      else if (k==="$ref") {
+        return schemasResolver(fastify, fastify.getSchema(v))
+      }
+      // convert JsonSchema integer types to bsonType: int
+      else if (k==="type" && v==="integer")
+        out.bsonType = "int";
+      // failsafe for other JsonSchema fields that are unimplemented by Mongo.
+      // NOTE: "format" is also a JsonSchema keyword, but the "format" keyword
+      // is used in our annotations, so we don't raise if it is encounetered.
+      // this filter could be fine-tuned to work only at top-level of schemas. for now, we allow "format¨.
+      else if ([ "$schema", "$default", "definitions" ].includes(k)) {
+        throw new Error(`${funcName}: JSONSchema field '${k}' conversion to Mongo schema is not implemented ! in schema: ${schema}`);
+      }
+      // it's a "normal" value => process it.
+      else {
+        out[k] = schemasResolver(fastify, v);
+      }
+    }
+
+    return out;
+  }
+  else {
+    throw new Error(`${funcName}: cannot process unexpected type: '${typeof k}' in schema ${schema}`);
+  }
+}
+
+function schemasResolverPlugin(fastify, options, done) {
+  fastify.decorate("schemasResolver", (schema) => schemasResolver(fastify, schema));
+  done();
+}
+
+export default fastifyPlugin(schemasResolverPlugin);
+