Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adds annotations #172

Draft
wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Conversation

hbcarlos
Copy link
Contributor

@hbcarlos hbcarlos commented Jun 28, 2023

Fixes: jupytercad/JupyterCAD#126

Creates a generic interface for annotations and adds annotations to the notebook's cells.

Description

The model I'm using for the annotations is based on the recommendations exposed in the W3C. An example of a notebook comment could be the following:

{
  "@context": "https://www.w3.org/ns/anno.jsonld",
  "id": "annotation_id",
  "type": "Annotation",
  "motivation": "commenting",
  "created": "2023-7-5T10:00:00Z",
  "creator": {
    "id": "user_0_id",
    "type": "Person",
    "name": "Jovyan 0",
    "nickname": "jovyan_0"
  },
  "body": [
    {
      "id": "body_id",
      "type": "TextualBody",
      "value": "Simple text comment",
      "purpose": "commenting",
      "created": "2023-7-5T10:00:00Z",
      "creator": {
        "id": "user_0_id",
        "type": "Person",
        "name": "Jovyan 0",
        "nickname": "jovyan_0"
      },
    },
    {
      "id": "body_id",
      "type": "TextualBody",
      "value": "Simple text comment",
      "purpose": "commenting",
      "created": "2023-7-5T10:00:00Z",
      "creator": {
        "id": "user_1_id",
        "type": "Person",
        "name": "Jovyan 1",
        "nickname": "jovyan_1"
      },
    }
  ],
  "target": {
    "source": "path/to/notebook",
    "selector": {
      "type": "FragmentSelector",
      "value": "cell_id",
      "refinedBy": {
        "type": "TextQuoteSelector",
        "exact": "selected text",
        "prefix": "text before the selection ",
        "suffix": " text after the selection"
      },
    }
  }
}

Attributes description

@context

Points to the definition of the schema used for the annotation

motivation and purpose

It is used to indicate the type of the annotation or body. We can use commenting to add comments threads and editing to add a change request.

created and creator

Identifies who created the annotation or body and when.

body

The body represents a resource that a user added to the annotation. For example, it can be a simple text comment or an audio, video, or image attachment. In this case, the body is a list of bodies to create a thread of comments or suggestions mixed with comments.

When the purpose of a body is tagged as editing, it is a change suggestion and can be applied to the document on the target position.

target

The target represents the position on the document where the annotation is pointing to.

Regarding the target, each document will have a different type selector. For the notebook, there are two possibilities. The above example assumes we store the annotation in the notebook's metadata (it also allows us to keep it outside the document, for example, a DB) and includes the path of the notebook, the cell, and the position of the selection in the text. Another possibility would be to use a simple TextQuoteSelector and store the annotation in the metadata of the cell.

Other attributes that we can use

generator

To indicate what client created the annotation. Moreover, this is optional for now since only jupyterlab will support annotations. See the example of the generator attribute:

{
  "@context": "https://www.w3.org/ns/anno.jsonld",
  "id": "annotation_id",
  ...,
  "generator": {
    "id": "client_id",
    "type": "Software",
    "name": "JupyterLab v4",
    "homepage": "https://jupyter.org"
  },
  ...
}

@hbcarlos hbcarlos added enhancement New feature or request api-change Pull requests introducing an API change labels Jun 28, 2023
@hbcarlos hbcarlos self-assigned this Jun 28, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
api-change Pull requests introducing an API change enhancement New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Extract annotations into its separate package
1 participant