Merge branch 'main' of github.com:Systemik-Solutions/Glycerine_API

Author: yangli0516

JupyterBook/1. Server API/8. Annotations.md

@@ -6,12 +6,14 @@
 Each annotation returned from the API is a JSON object with the following properties:
 
 - `id`: (read only) The ID of the annotation.
-- `annotation_type_id`: The ID of the type of the annotation. To use the default type, set it to `1`.
+- `annotation_type_id`: The ID of the type of the annotation.
 - `annotation_set_id`: The ID of the annotation set which the annotation belongs to.
-- `image_id`: The ID of the image which the annotation belongs to. Only applies to annoations from image annotation
-  sets.
+- `image_id`: The ID of the image which the annotation belongs to. Only applies to annoations from image annotation sets.
 - `target`: the Web Annotation target. See [Annotation target](annotation-target) for details.
+- `line_color`: The HEX color code used for outline color of the annotation. E.g. `#000000`.
+- `line_weight`: The outline color shade of the annotation. The value should be one of the values of `light`, `medium`, and `dark`.
 - `fields`: the field data of the annotation. See [Annotation fields](annotation-fields) for details.
+- `tags`: list of tags applied to the annotation. See [Annotation Tags](annotation-tags) for details.
 - `created_at`: (read only) The datetime when the annotation is created.
 - `updated_at`: (read only) The datetime when the annotation is updated.
 
@@ -36,51 +38,66 @@ Example:
 (annotation-fields)=
 ## Annotation fields
 
-### General format
+The `fields` property of an annotation is an array of objects containing the following properties:
 
-The `fields` property of an annotation is an object with field names as keys. The value of each field is an object with
-the language codes as keys to support field values in multiple languages. The value of each language code is an object
-with the property `values` which is an array of field values in that language. For example:
+- `field`: The field information of the value. It can be the field ID or an object with the basic field information:
+  - `id`: The ID of the field.
+  - `name`: The name of the field.
+  - `type`: The type of the field. The value should be one of the following: `text`, `long_text`, `link`, `choice`, `date`.
+- `values`: The values of the field. It is an object where each key is a language code and the value is an
+array of field values in that language. Each item of the array is a string value, except for the link field
+where each item is an object with the `url` and `text` properties.
+
+Example of a `text` field:
 
 ```json
 {
-    "title": {
-        "en": {
-            "values": [
-                "Title in English"
-            ]
-        },
-        "zh": {
-            "values": [
-                "中文标题"
-            ]
-        }
+    "field": {
+        "id": 1,
+        "name": "Title",
+        "type": "text"
     },
-    "link": {
-        "en": {
-            "values": [
-                {
-                    "url": "https://example.com",
-                    "text": "Link 1"
-                },
-                {
-                    "url": "https://example.com",
-                    "text": "Link 2"
-                }
-            ]
-        },
-        "zh": {
-            "values": [
-                {
-                    "url": "https://example.com",
-                    "text": "链接 1"
-                },
-                {
-                    "url": "https://example.com",
-                    "text": "链接 2"
-                }
-            ]
-        }
+    "values": {
+        "en": [
+            "Title in English"
+        ],
+        "zh": [
+            "中文标题"
+        ]
+    }
+}
+```
+
+Example of a `link` field:
+
+```json
+{
+    "field": {
+        "id": 2,
+        "name": "Link",
+        "type": "link"
+    },
+    "values": {
+        "en": [
+            {
+                "url": "https://example.com",
+                "text": "Link 1"
+            },
+            {
+                "url": "https://example.com",
+                "text": "Link 2"
+            }
+        ],
+        "zh": [
+            {
+                "url": "https://example.com",
+                "text": "链接 1"
+            },
+            {
+                "url": "https://example.com",
+                "text": "链接 2"
+            }
+        ]
     }
 }
 ```
@@ -121,31 +138,17 @@ The following is the list of supported language codes:
 |tr    |Turkish    |
 |zh    |Chinese    |
 
-### Title field
-
-A value of the `title` field is a string which is the title of the annotation.
-
-### Description field
-
-A value of the `description` field is a string which is the description of the annotation.
-
-### Link field
+(annotation-tags)=
+## Annotation Tags
 
-A value of the `link` field is an object with the following properties:
-
-- `url`: The URL of the link.
-- `text`: The text of the link.
-
-### Tag field
-
-A value of the `tag` field is an object with the following properties:
+The `tags` property of an annotation is an array of objects containing the following properties:
 
+- `term_label`: (required) The label of the tagging term.
+- `term_id`: The ID of the tagging term.
 - `vocabulary_id`: The ID of the vocabulary which the tag belongs to.
 - `vocabulary_name`: The name of the vocabulary which the tag belongs to.
-- `term_id`: The ID of the tagging term.
-- `term_label`: The label of the tagging term.
-- `data`: An object containing additional data of the tagging term such as the description and hierarchy information
-  of the term. For example:
+- `extended_data`: An object containing additional data of the tagging term such as the description and hierarchy 
+information of the term. For example:
 
 ```json
 {
@@ -159,28 +162,6 @@ A value of the `tag` field is an object with the following properties:
 }
 ```
 
-### Note field
-
-A value of the `note` field is a string which is the note of the annotation.
-
-### Attribution field
-
-A value of the `attribution` field is a string which is the attribution of the annotation.
-
-### Date field
-
-A value of the `date` field is a string in the format of `YYYY-MM-DD` which is the date of the annotation. For example:
-`2021-01-01`.
-
-### Line color field
-
-A value of HEX color code (start with `#`) used for outline color of the annotation. E.g. `#000000`.
-
-### Line weight field
-
-A value of the `line_weight` field is a string which is the outline color shade of the annotation. The value should be 
-one of the values of `Light`, `Medium`, and `Dark`.
-
 ## Get all annotations
 
 ```