aiiinotate 0.2.0

package/docs/endpoints.md

@@ -0,0 +1,48 @@
+# Endpoints
+
+---
+
+## URL prefixes
+
+URL anatomy is a mix of [SAS endpoints](./specifications/4_sas.md) and IIIF specifications. In turn, we define the following prefixes:
+
+- `data`: for all IIIF URIs: URIs of annotations and annotation lists
+- `annotations`: operations on annotations
+- `manifests`: operations on manifests
+- `search-api`: endpoint to access the IIIF search API
+
+In turn, URL anatomy is:
+
+```
+{host}/{prefix}/{iiif_version}/{slug}
+```
+
+Where:
+- `host`: the host of your app
+- `prefix`: `data | annotations | manifests`
+- `iiif_version`:
+    - if `prefix` is `search-api`, `1 | 2`: IIIF Search API version used
+    - otherwise, `2 | 3`, the IIIF Presentation API version your data is in
+- `slug`: the rest of the qurty URI
+
+There is an extra URL prefix: `schemas`. It is only used internally (not accessible to clients or accessible through HTTP) to define the IDs of all JsonSchemas, so we won't talk about it here.
+
+---
+
+## IIIF URIs
+
+IIIF URIs in the Presentation 2.1 API are:
+
+```
+Collection 	         {scheme}://{host}/{prefix}/collection/{name}
+Manifest 	         {scheme}://{host}/{prefix}/{identifier}/manifest
+Sequence 	         {scheme}://{host}/{prefix}/{identifier}/sequence/{name}
+Canvas 	                 {scheme}://{host}/{prefix}/{identifier}/canvas/{name}
+Annotation (incl images) {scheme}://{host}/{prefix}/{identifier}/annotation/{name}
+AnnotationList           {scheme}://{host}/{prefix}/{identifier}/list/{name}
+Range 	                 {scheme}://{host}/{prefix}/{identifier}/range/{name}
+Layer 	                 {scheme}://{host}/{prefix}/{identifier}/layer/{name}
+Content 	         {scheme}://{host}/{prefix}/{identifier}/res/{name}.{format}
+```
+
+

package/docs/progress.md

@@ -0,0 +1,159 @@
+# Dev progress
+
+We mostly talk about which routes are done here
+
+---
+
+## Done
+
+### Routes
+
+Routes are only implemented with IIIF Presentation API 2.x, not with the 3.0 version.
+
+#### Generic routes
+
+- `GET /search-api/:iiifSearchVersion/manifests/:manifestShortId/search`: search API
+
+#### Annotations routes
+
+- `GET /annotations/:iiifPresentationVersion/search`: get all annotations for a canvas URI
+- `POST /annotations/:iiifPresentationVersion/create`: create 1 annotation
+- `POST /annotations/:iiifPresentationVersion/createMany`: create several annotations
+- `POST /annotations/:iiifPresentationVersion/update`: update 1 annotation
+- `DELETE /annotations/:iiifPresentationVersion/delete`: delete annotations, either by their `@id`, trget canvas URI (`on.full`), or their `on.manifestShortId`
+
+=> all create/update/delete annotation routes are done !
+
+#### Manifests routes
+
+- `POST /manifests/:iiifPresentationVersion/create`: create a single manifest, either by including the manifest in the body or its URI
+- `DELETE /manifests/:iiifPresentationVersion/delete`: delete a single manifest
+- `GET /manifests/:iiifPresentationVersion`: return an index of all manifests as a collection
+
+### Non-routes
+
+- `manifests2`: `insert`, `insertMany` internal behaviours
+- fetching and inserting manifests related to an annotation when using inserting annotations.
+
+---
+
+## Notes
+
+### Uniqueness
+
+As of writing (09.10.25), there are no uniqueness constraints on annotations. There is only a uniqueness constraint on collection `manifest2` on field `manifest2.@id` (the ID of a manifest).
+
+Ideally, we would want to avoid having duplicate annotations in the database. This is more complicated in practice: at least for `annotions2`, an annotation's `@id` field is re-generated and a random part (an UUID) is generated at insert time. This means that, when trying to store the same annotation (with the same `@id`), the `@id` is changed, and so a different value is inserted.
+
+This means that we can't have a uniqueness constraint on `@id` or `id` fields of annotations. Another option would be to have a uniqueness constraint on annotation targets (no 2 annotations can annotate the same region), but this behaviour seems brittle in practice, so it's not yet implemented.
+
+### Concurrency
+
+For clients, concurrency/parrallelization (i.e., with JS `Promise.all()`) on insert/update should be avoided because it can cause a data race: several processes can attempt to write the same thing in parrallel.
+
+For example, when inserting annotations, the manifests related to each annotation are inserted in parrallel. Since this is a side effect, 2 processes may unknowingly try to insert the same manifest in the database, which causes a uniqueness constraint to fail. This error can be hard to debug, so it's best to avoid concurrency at write time.
+
+---
+
+## Dev quirks
+
+Sometimes, node/fastify can be weird. When scratching your head at dev errors, look here:)
+
+### Error swallowing at app build
+
+Errors that happen when a plugin is being registered will cause the app's startup to fail, without necessarily throwing an error.
+
+This is especially true for test cases that build the fastify app:
+
+```
+test
+=> build fastify app
+=> build step fails silently
+=> test fails
+```
+
+#### Troubleshooting
+
+- normal behaviour: when a runtime error happens, the failing test will log the error on the console
+- what this error looks like:
+    - tests fail **very quickly**,
+    - without throwing an error, seemingly without even running the test suite
+    - the proces doesn't exit, although all tests have failed
+- when `npm run test` fails like this, run `npm run start`. See if normal startup throws an error
+    - NOTE: normal startup not throwing does NOT mean that the build step necessarily worked
+
+#### Possible help/solutions
+
+- find a way to stisfyingly use `try...catch` at plugin registration.
+- look into these issues: [2694](https://github.com/fastify/fastify/issues/2694)
+    - in particular, it may be an issue specific to async plugins ?
+
+### Route response schema definition
+
+For some reason, route schema definition is much less flexible for responses than for queries.
+
+#### The problem
+
+**Query schemas**: In queries (`schema.params` or `schema.querystring`), fastify is very permissive. You can use unresolved schemas (with `$ref`), save entire schemas as JsonSchemas ...
+
+**Response schemas**: Response schemas have more constraints.
+- **response schemas are defined at route level** and cannot be stored as full JsonSchemas:
+    ```js
+    // this will be an invalid response schema: it is trying to store a complete response schema as a JsonSchema
+    fastify.addSchema({
+        $id: makeSchemaUri("routeResponsePost"),
+        properties: {
+            200: { ... },
+            500: { ... },
+        }
+    })
+
+    // this is a fixed version: an object containing schemas, not a full JsonSchema, to be used inside a Route definition
+    schema: {
+        response: {
+            200: { ... },
+            500: { ... }
+        }
+    }
+    // if you want to reuse a schema, store it as a JS object and import it.
+    ```
+- **unresolved response schemas (`$ref`) are forbidden**. You cannot use `$ref`. In the app, use `fastify.schemasResolver` to resolve the schema to a plain `JsonSchema` without `$ref`.
+
+#### The fix
+
+In short, here's **how to use shared schemas in responses**:
+1. Define payload schemas for different response cases:
+    ```js
+    // in case of a POST success
+    fastify.addSchema({
+        $id: makeSchemaUri("routeResponseInsert"),
+        type: "object",
+        // ...properties
+    });
+
+    // in case of a POST error
+    fastify.addSchema({
+        $id: makeSchemaUri("routeResponseError"),
+        type: "object",
+        // ...properties
+    });
+    ```
+2.
+2. Resolve schemas and use in responses
+    ```js
+    const routeResponseInsert = fastify.getSchema("...");
+    const routeResponseError = fastify.getSchema("...");
+    fastify.post(
+        "/annotations/:iiifPresentationVersion/create",
+        {
+            schema: {
+                body: routeAnnotations2Or3Schema,
+                response: {
+                    200: routeResponseInsert,
+                    500: routeResponseError
+               }
+            }
+        },
+        async (req, rep) => {}
+    )
+    ```

package/docs/specifications/0_w3c_open_annotations.md

@@ -0,0 +1,332 @@
+# Open annotations data model
+
+[https://web.archive.org/web/20220119101135/http://www.openannotation.org/spec/core](https://web.archive.org/web/20220119101135/http://www.openannotation.org/spec/core)
+
+[https://web.archive.org/web/20221225112722/http://www.openannotation.org/spec/core/core.html](https://web.archive.org/web/20221225112722/http://www.openannotation.org/spec/core/core.html)
+
+[https://www.w3.org/TR/annotation-vocab/](https://www.w3.org/TR/annotation-vocab/)
+
+
+The IIIF 2.x standard relies on the W3C Open annotations (OA) standard. Established in 2013, it has since been deprecated in favour of the W3C's Web annotations model, described in the next section. To make things fun, the site is not longer available and must be accessed through the wayback machine.
+
+---
+
+## In general
+
+- an Annotation is **a set of interconnected resources**, made mostly of a `Body` and a `Target`
+- the data model is **implementation independant** and can be implemented in JSON, RDF-XML, Turtle...
+- the standard extamples are in RDF, while IIIF uses JSON-ld. In  turn, keys vary from the IIIF standard. When there are differences, I indicate both what is in the OA examples, and what is used in IIIF.
+
+---
+
+## Vocabulary
+
+- `Annotation`: a set of interconnected resources, with at its core a `Body` and a `Target`, where the `Body` is about the `Target`.
+- `Target`: the object being annotated
+- `Body`: the annotation's contents
+- `Motivation`: the motivation further describes the relationship between `Body` and `Target`
+
+--- 
+
+## Namespaces
+
+<table>
+<tbody><tr><th>Prefix</th><th>Namespace</th><th>Description</th></tr>
+<tr><td>oa</td><td>http://www.w3.org/ns/oa#</td> <td>The Open Annotation ontology</td></tr>
+
+<tr><td>cnt</td><td>http://www.w3.org/2011/content#</td><td><a href="https://web.archive.org/web/20220119101135/http://www.w3.org/TR/Content-in-RDF10/">Representing Content in RDF</a></td></tr>
+<tr><td>dc</td><td>http://purl.org/dc/elements/1.1/</td><td><a href="https://web.archive.org/web/20220119101135/http://dublincore.org/documents/dces/">Dublin Core Elements</a></td></tr>
+<tr><td>dcterms</td><td>http://purl.org/dc/terms/</td><td><a href="https://web.archive.org/web/20220119101135/http://dublincore.org/documents/dcmi-terms/">Dublin Core Terms</a></td></tr>
+<tr><td>dctypes</td><td>http://purl.org/dc/dcmitype/</td><td><a href="https://web.archive.org/web/20220119101135/http://dublincore.org/documents/dcmi-type-vocabulary/">Dublin Core Type Vocabulary</a></td></tr>
+<tr><td>foaf</td><td>http://xmlns.com/foaf/0.1/</td><td><a href="https://web.archive.org/web/20220119101135/http://xmlns.com/foaf/spec/">Friend-of-a-Friend Vocabulary</a></td></tr>
+<tr><td>prov</td><td>http://www.w3.org/ns/prov#</td><td><a href="https://web.archive.org/web/20220119101135/http://www.w3.org/TR/prov-o/">Provenance Ontology</a></td></tr>
+<tr><td>rdf</td><td>http://www.w3.org/1999/02/22-rdf-syntax-ns#</td><td><a href="https://web.archive.org/web/20220119101135/http://www.w3.org/TR/rdf-syntax-grammar/">RDF</a></td></tr>
+<tr><td>rdfs</td><td>http://www.w3.org/2000/01/rdf-schema#</td><td><a href="https://web.archive.org/web/20220119101135/http://www.w3.org/TR/rdf-schema/">RDF Schema</a></td></tr>
+<tr><td>skos</td><td>http://www.w3.org/2004/02/skos/core#</td><td><a href="https://web.archive.org/web/20220119101135/http://www.w3.org/TR/skos-reference/">Simple Knowledge Organization System</a></td></tr>
+<tr><td>trig</td><td>http://www.w3.org/2004/03/trix/rdfg-1/</td><td><a href="https://web.archive.org/web/20220119101135/http://www.w3.org/2004/03/trix/">TriG Named Graphs</a></td></tr>
+
+</tbody></table>
+
+---
+
+## Annotations
+
+An annotation has 1+ `Targets` and 0+ `Bodies`
+- IIIF `@id`: `URI`
+    - is used to identify with an URI the `Annotation`, `Body` and `Target`
+    - in Turtle, there is no specific key because the standard is different.
+- `a` (IIIF `@type`): `oa:Annotation`
+    - this indicates that the resource is an `Annotation`
+- `oa:hasBody` (IIIF `resource`): `Body | Body[]`
+    - the relationship between `Annotation` and `Body`
+    - the body MAY be omitted if there is no content to annotate
+- `oa:hasTarget` (IIIF `on`): `Target | Target[]`
+    - the relationship between `Annotation` and `Target`
+- `oa:Motivation` (IIIF `motivation`): `string[]` (in IIIF, `oa:commenting | sc:painting` are frequent)
+    - the motivation, or role of the annotation
+    - `all allowed values are: `oa:bookmarking | oa:classifying | oa:commenting | oa:describing | oa:editing | oa:highlighting | oa:identifying | oa:linking | oa:moderating | oa:questionning | oa:replying | oa:tagging` 
+    - in IIIF, `sc:painting` is also allowed to indicate a painting annotation. The most useful values are `sc:painting | oa:commenting`.  
+
+```js
+// basic structure
+{
+    "@id": "<URI>",
+    "@type": "oa:Annotation",
+    "motivation": "sc:painting" || "oa:commenting",  // or an array of values
+    "resource": {
+        "@id": "<URI?>",
+        "@type": "<dctype>",
+        // other keys
+    },
+    "on": "<URI>" || SpecificResource  // `on` can be either specified as the URI to a canvas, or as a SpecificResource
+}
+```
+### Bodies and targets
+
+- `a` (IIIF `@type`): `dctypes:Dataset | dctypes:Image | dctypes:MovingImage | dctypes:Sound | dcTypes:Text`
+    - SHOULD be used to describe the type of a `Body` or `Target`
+- IIIF `@id`: `URI`
+
+Special cases:
+- an annotation may have **no `Body`**
+- an annotation may have **multiple `Bodies` or `Targets`**.
+    - in that case, **each body is related to each target individually**. If we have 2 bodies and 2 targets, we have the following situation:  
+    ```
+    body1 <-> target1
+    body1 <-> target2
+    body2 <-> target1
+    body2 <-> target2
+    ```
+    - you may have 1 `Target` and N `Bodies` (several annotations apply to a single body), or N `Target` and 1 `Bodies` (1 annotation applies to several images) or an N to N relationship. 
+
+### Embedded textual body (ETB)
+
+ETBs are used to embed textual content directly in an annotation instead of referencing it by an `id`.
+- `a` (IIIF `@type`): `cnt:ContentAsText | dctypes:Text`
+    - MUST be used to indicate that this is an ETB. MAY contain both values described above.
+- `cnt:chars` (IIIF `chars`): `string`
+    - MUST Be used to contain the contents of the ETB.
+- `dc:format` (SAS `format`): `mimetype`
+    - SHOULD be used to describe the mimetype of the ETB
+    - for example, it can distinguish plain text form HTML.
+- `dc:language`: `string`
+    - the language the ETB is in
+    - language codes SHOULD follow [RFC 3066](https://www.ietf.org/rfc/rfc3066.txt)
+
+```js
+{
+    "@type" : "dctypes:Text",
+    "format" : "text/html",
+    "chars" : "<p>This is en embedded textual content from SAS</p>",
+}
+```
+
+### Tags
+
+A tag is a specific type of `Body`: a keyword or label used to annotate a `Target`. There are 2 types of tags: "normal" and "semantic" tags
+- `a` (IIIF `@type`): `oa:Tag | oa:SemanticTag`
+    - `oa:Tag` describes a non-semantic tag. In that case, the tag functions like an ETB
+    - `oa:SemanticTag` describes a semantic tag. Instead of containing the contents of the tag, the `Body` references an external URI.
+- `oa:Motivation` (IIIF `motivation`): `oa:tagging`
+    - `oa:tagging` should be added to the `oa:Motivation` of the annotation to indicate it's a tag
+
+### Fragment URIs
+
+Fragment URIs can be used to target part of a resource.
+- fragments ARE NOT COMPATIBLE with `SpecificResources`. Either use one or the other.
+
+```js
+{
+    "@id": "http://example.com/image.jpg#xywh=1,1,1,1"
+}
+```
+
+---
+ 
+## Specific Resources
+
+[https://web.archive.org/web/20221225112722/http://www.openannotation.org/spec/core/specific.html](https://web.archive.org/web/20221225112722/http://www.openannotation.org/spec/core/specific.html)
+
+`SpecificResources` are an extension of the core data model to reference part of a resource with more precision than Fragment URIs. They can be used either in `Bodies` or `Targets` (though in IIIF they are used mostly in `Targets`).
+
+```js
+// basic IIIF structure for a SpecificResource
+{
+    "@id": "<annotationId>",
+    "@type": "oa:SpecificResource",
+    "full": {
+        // link to the full image
+    },
+    "selector": {
+        "@type": "<selectorType>",
+        "value": "<selectorValue>"
+    },
+    "within": {
+        // extra context, such as the IIIF manifest in which to include the annotation 
+    },
+}
+```
+
+### Basic units
+
+3 conceptual units are present in the Specific Resource model:
+- `Source resource`: the complete target , i.e. an entire image that we want to select a section of.
+- `SpecificResource`: the segment of the resource described by the `Specifier`
+- `Specifiers`: describes how to determine the aspects of the `Source` that constitute the Specific Resource. 
+
+### Specifiers
+
+There are 3 types of specifiers:
+- `oa:State`: specifies the state of a `Body` or a `Target` applicable to an `Annotation` in order to retrieve the proper representation of the resource. For example, 
+    - the timestamp at which a `Body` was created (if there are several versions of the same resource with different timestamps)
+- `oa:Selector`: specifies the segment of a resource relevant to the `Annotation`: text range, image section, SVG selector...
+- `oa:Style`: a description of how to style an `Annotation`
+
+If `State` and `Selector` are present in a annotation, the `State` will be processed before `Selector` to be sure that we have the proper state.
+
+Keys:
+- `a` (IIIF `@type`) `oa:SpecificResource`: the specific resource
+- `oa:hasSource` (SAS `full`): the `Source Resource` being specified by the `Specific Resource`.
+    - MUST be used: the `Specific Resource` is defined relatively to the `Source Resource`, and so the renderer will fetch the `Source` before targeting the `Specific resource` part.
+
+I'll only present selectors, not `states` or `styles` that aren't used in IIIF.
+
+### Selectors
+
+A `Selector` is a `Specifier` which describes how to determine the segment of interest from within the retrieved representation of the Source resource. There MUST be only 1 `Selector` per specifier, otherwise use the [multiplicity module](https://web.archive.org/web/20221225112718/http://www.openannotation.org/spec/core/multiplicity.html).
+
+- `oa:hasSource` (IIIF `full`): the `Source resource`
+- `oa:hasSelector` (IIIF `selector`): the `Selector`'s content
+
+There are selectors other than those presented below: `RangeSelector`, `TextPositionSelector`, `TextQuoteSelector`... but they are out of scope with IIIF so I won't talk about them
+
+#### FragmentSelector
+
+- `a` (IIIF `@type`): `oa:FragmentSelector`
+- `rdf:value` (IIIF `value`): `string'
+- `dcterms:conformsTo`: the specification that defines the syntax of the fragment.
+    - for IIIF, targets can only be targeted using IIIF-specific `ImageApiSelector` or W3C media fragments (`xhwh=int,int,int,int`).
+    - SHOULD be used
+    - SHOULD be one of: 
+
+<table>
+<tbody><tr><th>Fragment Specification</th><th>Description</th></tr>
+<tr><td>http://tools.ietf.org/rfc/rfc3236</td><td><a href="https://web.archive.org/web/20221225112722/http://tools.ietf.org/rfc/rfc3236">XHTML, and HTML</a>. Example: #namedSection </td></tr>
+<tr><td>http://tools.ietf.org/rfc/rfc3778</td><td><a href="https://web.archive.org/web/20221225112722/http://tools.ietf.org/rfc/rfc3778">PDF</a>. Example: #page=10&amp;viewrect=50,50,640,480</td></tr>
+<tr><td>http://tools.ietf.org/rfc/rfc5147</td><td><a href="https://web.archive.org/web/20221225112722/http://tools.ietf.org/rfc/rfc5147">Plain Text</a>. Example: #char=0,10</td></tr>
+<tr><td>http://tools.ietf.org/rfc/rfc3023</td><td><a href="https://web.archive.org/web/20221225112722/http://tools.ietf.org/rfc/rfc3023">XML</a>. Example: #xpointer(/a/b/c) </td></tr>
+<tr><td>http://www.ietf.org/rfc/rfc3870</td><td><a href="https://web.archive.org/web/20221225112722/http://www.ietf.org/rfc/rfc3870">RDF/XML</a>. Example: #namedResource </td></tr>
+<tr><td>http://www.w3.org/TR/media-frags/</td><td><a href="https://web.archive.org/web/20221225112722/http://www.w3.org/TR/media-frags/">W3C Media Fragments</a>. Example: #xywh=50,50,640,480</td></tr>
+<tr><td>http://www.w3.org/TR/SVG/</td><td><a href="https://web.archive.org/web/20221225112722/http://www.w3.org/TR/SVG/">SVG</a>. Example: #svgView(viewBox(50,50,640,480))</td></tr>
+</tbody></table>
+
+```js
+{
+    // ...
+    selector: {
+        "@type": "oa:FragmentSelector",
+        "value": "xywh=int,int,int,int"  // so here we use the W3C media fragments selector
+    }
+
+}
+```
+
+#### SVG selectors
+
+`SvgSelectors` define an area through an SVG.
+- the `SvgSelector`'s value MUST be a valid and complete SVG document
+- the SVG SHOULD be a single shape: `path|rect|circle|ellipse|polyline|polygone|g`
+- dimensions in the SVG MUST be relative to the `Source resource`. 
+    - For example, given an image which is 600 pixels by 400 pixels, and the desired section is a circle of 100 pixel radius at the center of the image, then the SVG element would be: `<circle cx="300" cy="200" r="100"/>`
+
+
+### Examples
+
+
+`Specific resource` structure in IIIF 2.x.
+```js
+{
+    "@type" : "oa:SpecificResource",
+    "within" : {
+      "@id" : "https://aikon.enpc.fr/aikon/iiif/v2/wit9_man11_anno165/manifest.json",
+      "@type" : "sc:Manifest"
+    },
+    "selector" : {
+        "@type" : "oa:FragmentSelector",
+        "value" : "xywh=0,31,1865,1670"
+    },
+    "full" : "https://aikon.enpc.fr/aikon/iiif/v2/wit9_man11_anno165/canvas/c16.json"
+} 
+```
+
+`Specific resource` that uses the IIIF `ImageApiSelector` extension
+```js
+{
+    // `@id` uses the IIIF Image api to describe the fragment
+    "@id": "http://www.example.org/iiif/book1-page1/50,50,1250,1850/full/0/default.jpg",
+    "@type": "oa:SpecificResource",
+    
+    // `full` describes the full image.
+    "full": {
+        "@id": "http://example.org/iiif/book1-page1/full/full/0/default.jpg",
+        "@type": "dctypes:Image",
+        "service": {
+            "@context": "http://iiif.io/api/image/2/context.json",
+            "@id": "http://example.org/iiif/book1-page1",
+            "profile": "http://iiif.io/api/image/2/level2.json"
+        }
+    },
+    
+    // `selector` describes the region targeted in `@id`
+    "selector": {
+        "@context": "http://iiif.io/api/annex/openannotation/context.json",
+        "@type": "iiif:ImageApiSelector",
+        "region": "50,50,1250,1850"
+    }
+}
+```
+
+---
+
+## Multiplicity
+
+[https://web.archive.org/web/20221225112718/http://www.openannotation.org/spec/core/multiplicity.html](https://web.archive.org/web/20221225112718/http://www.openannotation.org/spec/core/multiplicity.html)
+
+In IIIF, this module is useful if we want to specify more than 1 `SpecificResource`. In OA, the multiplicity module is used to have multiple bodies or targets in an annotation (IE: 3 bodies in 3 languages). Options for multiplicity are:
+
+- `oa:Choice`: only one of several bodies/targets will be rendered at once. Done by defining 1 default value and other alternative values
+- `oa:Composite`: when all resources are required for an annotation to function properly.
+- `oa:List`: like a composite, but ordered
+
+`Bodies` and `Targets` can use `multiplicity` by setting their `@type` to `oa:Choice | oa:Composite |oa:List`.
+
+I have only ever seen `oa:Choice` be used in IIIF so that's the one I'll present.
+
+### `oa:Choice`
+
+```js
+{
+    "@type": "oa:Choice",
+    "default": /** default choice */,
+    "item": /** one or several other available items */
+}
+```
+
+Example: a choice between a `FragmentSelector` and an `SvgSelector`
+```js
+{
+    "@type" : "oa:Choice",
+    "default" : {
+        "@type" : "oa:FragmentSelector",
+        "value" : "xywh=0,31,1865,1670"
+    },
+    "item" : {
+        "@type" : "oa:SvgSelector",
+        "value" : "<svg xmlns=\"http://www.w3.org/2000/svg\"><path xmlns='http://www.w3.org/2000/svg' d='M0 31 h 932 v 0 h 932 v 835 v 835 h -932 h -932 v -835Z' id='rectangle_wit9_man11_anno165_c16_5ebd8bc8044b45b58aae2a508ca75eed' 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>"
+    }
+}
+```
+
+
+
+