Relationships to RDF

The definitions in this documents also follow the extra syntactic rules of JSON-LD [[json-ld]]. This means that, through the usage of the JSON-LD Context defined in Appendix A of the Web Annotation Vocabulary [[annotation-vocab]], also available online as http://www.w3.org/ns/anno.jsonld, Selectors and States can be seen as RDF Graphs [[rdf11-concepts]] that can be linked to, or used from within, other RDF graphs. Using the mapping defined in that Context Selectors and States can be expressed in other RDF serializations like Turtle [[turtle]]. The formal specification of the corresponding vocabulary is provided by [[annotation-vocab]]. To make the equivalences easier for the reader, contains all JSON-LD examples of this document serialized in Turtle, too.

It must be noted that applications unrelated to RDF and/or Linked Data can safely ignore the context as well as the vocabulary mapping, and work exclusively with the JSON objects and keys as defined below.

Terminology

IRI

An IRI, or Internationalized Resource Identifier, is an extension to the URI specification to allow characters from Unicode, whereas URIs must be made up of a subset of ASCII characters. There is a mapping algorithm for translating between IRIs and the equivalent encoded URI form. IRIs are defined by [[rfc3987]].

Resource

An item of interest that MAY be identified by an IRI.

Web Resource

A Resource that MUST be identified by an IRI, as described in the Web Architecture [[webarch]]. Web Resources MAY be dereferencable via their IRI.

Specific Resource

A Resource that serves as a wrapper around the selection of part of another Web Resource. A Specific Resource identifies the relevant Web Resource (the Source) through a source term, and MAY contain other terms to refine the selection.

Source

The overall Web Resource whose selection is refined through the usage of Selectors or States.

Segment (of Interest)

The part of the Resource that is selected using a Selector.

External Web Resource

A Web Resource which is not part of the representation the selection, such as a web page, image, or video. External Web Resources are dereferencable from their IRI.

Property

A feature of a Resource, that often has a particular data type. In the model sections, the term "Property" is used to refer to only those features which are not Relationships and instead have a literal value such as a string, integer, or date. The valid values for a Property are thus any data type other than object, or an array containing members of that data type if more than one is allowed.

Relationship

In the model sections, the term "Relationship" is used to distinguish those features that refer to other Resources, either by reference to the Resource's IRI or by including a description of the Resource in the representation. The valid values for a Relationship are: a quoted string containing an IRI, an object that has the "id" property, or an array containing either of these if more than one is allowed.

Class

Resources may be divided, conceptually, into groups called "classes"; members of a class are known as Instances of that class. Resources are associated with a particular class through typing. Classes are identified by IRIs, i.e., they are also Web Resources themselves.

Type

A special Relationship that associates an Instance of a class to the Class it belongs to.

Instance

An element of a group of Resources represented by a particular Class.

Fragment Selector

As the most well understood mechanism for selecting a Segment is to use the fragment part of an IRI defined by the representation's media type, it is useful to allow this as a description mechanism via a Selector. This allows existing and future fragment specifications to be used with Specific Resources in a consistent way. To be clear about which fragment type is being used, the Selector may refer to the specification that defines it.

Example Use Case: Ramona wants to associate part of a video as the description of an image. She selects the time range within the video and clicks that it is describing the target. Her client then creates the Annotation using a SpecificResource with a FragmentSelector.

Model

It is RECOMMENDED to use FragmentSelector as a consistent method compatible with other means of describing SpecificResources, rather than using the IRI with a fragment directly. Consuming applications SHOULD be aware of both.

The following IRIs are some of the specifications that define the semantics of fragments, and hence may be used with the conformsTo relationship. Other IRIs MAY also be used.

Example

                {
                    "source": "http://example.org/video1",
                    "selector": {
                      "type": "FragmentSelector",
                      "conformsTo": "http://www.w3.org/TR/media-frags/",
                      "value": "t=30,60"
                    }
                }
                

CSS Selector

One of the most common ways to select elements in the HTML Document Object Model is to use CSS Selectors [[css3-selectors]]. CSS Selectors allow for a wide variety of well supported ways to describe the path to an element in a web page, and thus cover many of the basic use cases for selection. Results are not defined for when a CSS Selector is applied to a representation that does not conform to the Document Object Model.

Example Use Case: Sally selects a paragraph in a web page that she wishes remove. Her client calculates a CSS path that cleanly identifies that element to be deleted.

Model

Example

                {
                    "source": "http://example.org/page1.html",
                    "selector": {
                      "type": "CssSelector",
                      "value": "#elemid > .elemclass + p"
                    }
                }
                

XPath Selector

Another common method of selecting elements and content within a resource that supports the Document Object Model (DOM), such as documents in XML or HTML, is to use an XPath selection [[dom-level-3-xpath]]. XPath allows a great deal of flexibility when describing the path through the structure to the selected content. Results are not defined for when an XPath Selector is applied to a representation that does not conform to the DOM.

Example Use Case: Teynika selects a span within a table in an HTML page and writes a note about the content. To refer explicitly to this element, her client carefully constructs an XPath to identify the relevant element.

Model

Example

                {
                    "source": "http://example.org/page1.html",
                    "selector": {
                      "type": "XPathSelector",
                      "value": "/html/body/p[2]/table/tr[2]/td[3]/span"
                    }
                }
                

Text Quote Selector

This Selector describes a range of text by copying it, and including some of the text immediately before (a prefix) and after (a suffix) it to distinguish between multiple copies of the same sequence of characters.

For example, if the document was "abcdefghijklmnopqrstuvwxyz", one could select "efg" by a prefix of "abcd", the match of "efg" and a suffix of "hijk".

Example Use Case: Ulrika selects a typo ('anotation') in a web page and adds a comment that it should be replaced with the correct spelling ('annotation').

Model

The selection of the text MUST be in terms of unicode code points (the "character number"), not in terms of code units (that number expressed using a selected data type). Selections SHOULD NOT start or end in the middle of a grapheme cluster. The selection MUST be based on the logical order of the text, rather than the visual order, especially for bidirectional text. For more information about the character model of text used on the web, see [[charmod]].

The text MUST be normalized before recording in the Annotation. Thus HTML/XML tags SHOULD be removed, and character entities SHOULD be replaced with the character that they encode. Note that this does not affect the state of the content of the document being annotated, only the way that the content is recorded in the Annotation document.

If, after processing the prefix, exact, and suffix, the user agent discovers multiple matching text sequences, then the selection SHOULD be treated as matching all of the matches.

Example

                {
                    "source": "http://example.org/page1",
                    "selector": {
                      "type": "TextQuoteSelector",
                      "exact": "anotation",
                      "prefix": "this is an ",
                      "suffix": " that has some"
                    }
                }
                

Text Position Selector

This Selector describes a range of text by recording the start and end positions of the selection in the stream. Position 0 would be immediately before the first character, position 1 would be immediately before the second character, and so on. The start character is thus included in the list, but the end character is not.

For example, if the document was "abcdefghijklmnopqrstuvwxyz", the start was 4, and the end was 7, then the selection would be "efg".

Example Use Case: Valeria writes a review of an ebook that does not allow its content to be extracted and copied. Her client describes the selection using its start and end position in the content.

Model

The text MUST be selected and normalized in the same way as for the Text Quote Selector before counting the number of characters to determine the start and end positions.

Example

            {
                "source": "http://example.org/ebook1",
                "selector": {
                  "type": "TextPositionSelector",
                  "start": 412,
                  "end": 795
                }
            }
            

Data Position Selector

Similar to the Text Position Selector, the Data Position Selector uses the same properties but works at the byte in bitstream level rather than the character in text level.

Example Use Case: Wendy produces visualizations of regions of online disk images for forensic purposes. Her client generates the start and end positions from the binary stream, rather than the more human readable display she is using.

Model

Example

            {
                "source": "http://example.org/diskimg1",
                "selector": {
                  "type": "DataPositionSelector",
                  "start": 4096,
                  "end": 4104
                }
            }
            

SVG Selector

An SvgSelector defines an area through the use of the Scalable Vector Graphics [[svg11]] standard. This allows the user to select a non-rectangular area of the content, such as a circle or polygon by describing the region using SVG. The SVG may be either embedded or referenced as an External Web Resource.

Note that the SvgSelector uses SVG to select an area of a resource. Segments of an SVG representation may also be selected using selectors, including the FragmentSelector or even an SvgSelector.

Example Use Case: Xena is tagging an old map online with a diagonal region for a historical road. Her client creates SVG polygon to highlight the region by overlaying a transparent area with a different color.

Model

The dimensions of the SVG shape or canvas MUST be relative to the dimensions of the Source, such that scaling the shape's size to the full size of the image correctly describes the desired area.

Example

            {
                "source": "http://example.org/map1",
                "selector": {
                  "type": "SvgSelector",
                  "id": "http://example.org/svg1"
                }
            }
            

            {
                "source": "http://example.org/map1",
                "selector": {
                  "type": "SvgSelector",
                  "value": "<svg:svg> ... </svg:svg>"
                }
            }
            

Range Selector

Selections made by users may be extensive and/or cross over internal boundaries in the representation, making it difficult to construct a single selector that robustly describes the correct content. A Range Selector can be used to identify the beginning and the end of the selection by using other Selectors. In this way, two points can be accurately identified using the most appropriate selection mechanisms, and then linked together to form the selection. The selection consists of everything from the beginning of the starting selector through to the beginning of the ending selector, but not including it.

Example Use Case: Yadira wants to comment on two adjacent cells in a table that is part of a web page. She selects the two cells and her client constructs XPaths to the the first cell, and the cell that immediately follows the second. Her client then creates a Range Selector with the first XPath Selector as the start, and the second XPath selector as the end.

Model

Example

            {
                "source": "http://example.org/page1.html",
                "selector": {
                  "type": "RangeSelector",
                  "startSelector": {
                    "type": "XPathSelector",
                    "value": "//table[1]/tr[1]/td[2]"
                  },
                  "endSelector": {
                    "type": "XPathSelector",
                    "value": "//table[1]/tr[1]/td[4]"
                  }
                }
            }
            

Refinement of Selection

It may be easier, more reliable or more accurate to specify the segment of interest of a resource as a selection of a selection, rather than as a selection of the complete resource. Particularly for resources that contain other resources, such as various packaging formats, this also allows decomposition of the selection mechanisms when the components do not have unique identifiers. This is accomplished by having selectors chained together, where each refines the results of the previous one.

Example Use Case: Zara selects a paragraph of text and then a short phrase within it to remove. Her client records the phrase as a TextQuoteSelector that further modifies a FragmentSelector used to identify the paragraph that the phrase is part of.

Model

Example

            {
                "source": "http://example.org/page1",
                "selector": {
                  "type": "FragmentSelector",
                  "value": "para5",
                  "refinedBy": {
                    "type": "TextQuoteSelector",
                    "exact": "Selected Text",
                    "prefix": "text before the ",
                    "suffix": " and text after it"
                  }
                }
            }
            

Time State

A Time State resource records the time at which the resource is when the intended selection occurs, typically the time that the resource was created and/or a link to a persistent copy of the current version. The timestamp for the resource could be resolved via the Memento protocol, described in RFC 7089 [[rfc7089]].

Example Use Case: Britney makes a note about the current state of the front page of a news website, and flags that the page is likely to change often. Her client adds in a State with the current time to describe the version of the page.

Model

Example

            {
                "source": "http://example.org/page1",
                "state": {
                  "type": "TimeState",
                  "cached": "http://archive.example.org/copy1",
                  "sourceDate": "2015-07-20T13:30:00Z"
                }
            }
            

Request Header State

As there are potentially many representations that can be delivered from a resource with a single IRI, and a selection may only apply to one of them, it is important to be able to record the HTTP Request headers that need to be sent to retrieve the correct representation. The HttpRequestState resource maintains a copy of the headers to be replayed when obtaining the representation.

Example Use Case: Carla retrieves a PDF representation of a web resource that can deliver HTML, PDF or plain text and then writes a description about it. She signals that her description is only about the PDF representation. Her client then includes a State to describe how to retrieve the target representation.

Model

Example

            {
                "source": "http://example.org/resource1",
                "state": {
                  "type": "HttpRequestState",
                  "value": "Accept: application/pdf"
                }
            }
            

Refinement of State

Similar to the refinement of selection, it may be easier, more reliable or more accurate to specify the appropriate state of the resource as a hierarchy of atomic State resources. This is particularly appropriate for representing the combination of a State that reflects an internal transformation along with the results of a State that describes an external request. This decomposition is accomplished by having the states chained together in the same way as Selectors.

Further, given that the State(s) will likely result in a specific representation, there may be specific Selectors that are appropriate for describing the segment of the representation. In order to accommodate this, States may also be refined by Selectors.

Example Use Case: Devina writes a comment about a travel e-book which has many versions available over time, and is available in different formats. She is particularly commenting on a specific version and format, so her client adds both a TimeState to capture the time and an HttpRequestState to capture the format.

Model

Example

        {
            "source": "http://example.org/ebook1",
            "state": {
              "type": "TimeState",
              "sourceDate": "2016-02-01T12:05:23Z",
              "refinedBy": {
                "type": "HttpRequestState",
                "value": "Accept: application/epub+zip"
              }
            }
        }
        

JSON examples converted to fragment identifiers

This section contains a mapping of all examples used in the definion of Selectors and States onto full IRI-s with fragment identifiers. Note that the examples below have been, in some cases, broken into several lines for a greater readability; in real usage such new lines are not allowed in an IRI.

A simple converter tool is also available to test the conversion of the JSON format to fragment and back.

Example for a

            http://example.org/video1
                #selector(type=FragmentSelector,conformsTo=http://www.w3.org/TR/media-frags,
                          value=t%3D30%2C60)
            

Example for a

            http://example.org/page1.html
                #selector(type=CssSelector,value=%23elemid%20>%20.elemclass%20+%20p)
            

Example for a

            http://example.org/page1.html
                #selector(type=XPathSelector,value=/html/body/p[2]/table/tr[2]/td[3]/span)
            

Example for a

            http://example.org/page1
                #selector(type=TextQuoteSelector,exact=annotation,prefix=this%20is%20an%20,
                          suffix=%20that%20has%20some)
            

Example for a

            http://example.org/ebook1
                #selector(type=TextPositionSelector,start=412,end=795)
            

Example for a

            http://example.org/diskimg1
                #selector(type=DataPositionSelector,start=4096,end=4104)
            

First example for a

            http://example.org/map1
                #selector(type=SvgSelector,id=http://example.org/svg1)
            

Second example for a

                http://example.org/map1
                    #selector(type=SvgSelector,
                              value=<svg:svg>%20...%20</svg:svg>)
            

Please note that long SVG representations will produce very long URLs when produced according to this pattern. Care should be taken in environments where there is a character limit to URLs, and implementers should consider publishing the SVG as a separate resource and using its IRI as shown in Example 22.

Example for a

            http://example.org/page1.html
                #selector(type=RangeSelector,
                          startSelector=selector(type=XPathSelector,value=//table[1]/tr[1]/td[2]),
                          endSelector=selector(type=XPathSelector,value=//table[1]/tr[1]/td[4]))
            

Example for a

            http://example.org/page1
                #selector(type=FragmentSelector,value=para5,
                          refinedBy=selector(type=TextQuoteSelector,exact=Selected%20Text,
                                    prefix=text%20before%20the%20,suffix=%20and%20text%20after%20it))
            

Example for a

            http://example.org/page1
                #state(type=TimeState,cached=http://archive.example.org/copy1,
                       sourceDate=2015-07-20T13:30:00Z)
            

Example for a

            http://example.org/resource1
                #state(type=HttpRequestState,value=Accept:%20application/pdf)
            

Example for a

            http://example.org/ebook1
                #state(type=TimeState,sourceDate=2016-02-01T12:05:23Z,
                       refinedBy=state(type=HttpRequestState,value=Accept:%20application/epub+zip))
            

Serializing IRI to URL

Care should be taken that to make use of a Selectors and States IRIs as URLs (i.e., not only as identifiers but as locators), each segment of the IRI must be mapped to a corresponding URL segment following [[rfc3987]]. Applying percent encoding method for entire IRI string might also cause unnecessary troubles. Some examples:

				http://jp.example.org/page1
				    #selector(type=TextQuoteSelector,
					      exact=ペンを,
					      prefix=私は、,
					      suffix=持っています)

				http://jp.example.org/page1
				    #selector(type=TextQuoteSelector,
					      exact=%E3%83%9A%E3%83%B3%E3%82%92,
					      prefix=%E7%A7%81%E3%81%AF%E3%80%81,
					      suffix=%E6%8C%81%E3%81%A3%E3%81%A6%E3%81%84%E3%81%BE%E3%81%99)
			

				http://example.org/page1
				    #selector(type=TextQuoteSelector,exact=annotation,
					      prefix=this%20is%20an%20,suffix=%20that%20has%20some)

				http://example.org/page1
				    #selector(type=TextQuoteSelector,exact=annotation,
					      prefix=this%2520is%2520an%2520,suffix=%2520that%2520has%2520some)
			

Note that the IRI may also contain an internationalized domain name, which must be encoded as well (see [[rfc3490]]).