Locators for Web Publications

Abstract

Selecting part of a resource on the Web is an ubiquitous action. Over the years several selection techniques have been developed, usually in conjunction with the media type of the resource. Many of these approaches are also expressed in terms of a fragment identifiers [ url ], but that is not always the case.

This document does not define any new approach to selection. Instead, it relies on existing techniques, providing a common model and syntax to express and possibly combine selections. Although defined in conjunction with Web Publications, the techniques described in this document can be used for any type of Web Resources

The formal specification and the semantics originate from a separate W3C Recommendation, namely the Web Annotation Data Model [ annotation-model ], where it is used to select targets of annotations. That model has been extended by adding two more selector types (see the Introduction for further details.)

Issue 6 : Do we need fragment ids?

The document consists of two parts: a description of, essentially, the Selector Model as defined by the Web Annotation Data Model, and a reformulation of that data model in the form of Fragment ID-s. It is not clear, at this moment, whether the standardization of fragment identifiers is necessary, or whether the JSON based structure fulfills the needs of the requirements. If the latter, we can remove the relevant section, and the only possible normative extension in the document is described in issue #4 .

Term	Type	Description
id	Property	The identity of the Locator A Locator SHOULD have exactly 1 URL that identifies it.
source	Relationship	The relationship between a Locator and the resource that it is a more specific representation of, i.e., the Source . There MUST be exactly 1 `source` relationship associated with a Locator. The source resource MAY be described in detail as in the core data model or be just the resource’s URL.
scope	Relationship	The relationship between a Locator and the resource that provides the scope or context in this selection. There MAY be 0 or more scope relationships for each Locator. Conceptually, if no scope is provided, the value of the `source` relationship can be considered as the scope.

4. Selectors §

This section is non-normative.

Selection of part of a Web Resource requires two distinct entities:

the URL of the overall resource; we will refer to this as the Source .
the identification for the part of that resource; we will refer to this as the Segment (of Interest) .

A Selector object is used to describe how to determine the Segment from within the Source resource. The nature of the Selector is dependent on the type of resource, as the methods to describe Segments from various media-types differ. These two entities are encapsulated in a Locator .

Example Use Case: Qitara wants to associate a selection of text in a web page with a slice of a dataset. She selects both using her client, and creates Locators with Selectors for both entities before associating them with one another.

Model §

Term	Type	Description
selector	Relationship	The relationship between a Locator and a Selector. There MAY be 0 or more `selector` relationships associated with a Locator. Multiple Selectors SHOULD select the same content, however some Selectors will not have the same precision as others. User Agents MUST pick one of the described segments , if they are different.

Example §

Example 1 : Selectors

{
        "source": "http://example.org/page1",
        "selector": "http://example.org/paraselector1"
}

4.1 Fragment Selector §

As the most well understood mechanism for selecting a Segment is to use the fragment part of a URL 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 Locators 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 Locator with a FragmentSelector.

Model §

Term	Type	Description
type	Relationship	The class of the Selector. FragmentSelectors MUST have exactly 1 `type` and the value MUST be `FragmentSelector`.
value	Property	The contents of the fragment component of a URL that describes the Segment. The FragmentSelector MUST have exactly 1 `value` property.
conformsTo	Relationship	The relationship between the FragmentSelector and the specification that defines the syntax of the URL fragment in the `value` property. The Fragment Selector SHOULD have exactly 1 `conformsTo` link to the specification that defines the syntax of the fragment and MUST NOT have more than 1.

It is RECOMMENDED to use FragmentSelector as a consistent method compatible with other means of describing Locators, rather than using the URL with a fragment directly. User Agents SHOULD be aware of both.

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

Name	Fragment Specification	Description
HTML	http://tools.ietf.org/rfc/rfc3236	[ rfc3236 ] Example: `namedSection`
PDF	http://tools.ietf.org/rfc/rfc3778	[ rfc3778 ] Example: `page=10&viewrect=50,50,640,480`
Plain Text	http://tools.ietf.org/rfc/rfc5147	[ rfc5147 ] Example: `char=0,10`
XML	http://tools.ietf.org/rfc/rfc3023	[ rfc3023 ] Example: `xpointer(/a/b/c)`
CSV	http://tools.ietf.org/rfc/rfc7111	[ rfc7111 ] Example: `row=5-7`
Media	http://www.w3.org/TR/media-frags/	[ media-frags ] Example: `xywh=50,50,640,480`
SVG	http://www.w3.org/TR/SVG/	[ svg11 ] Example: `svgView(viewBox(50,50,640,480))`

Note

The URL that uses the fragment may be reconstructed by concatenating the


source

, a

, and the


value

. For example, the URL from the example below would be


http://example.org/video1#t=30,60

Example §

Example 2 : Fragment Selector

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

4.2 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 one of the chapters of a Web Publication that she wishes bookmark. Her client calculates a CSS path that cleanly identifies that element and stores CSS Selector in its local bookmark store. Because the selection is made as part of a Web Publication (e.g., through the WP aware User Agent), a reference to the Web Publication’s address is also added to the bookmark.

Model §

Term	Type	Description
type	Relationship	The class of the Selector. CssSelectors MUST have exactly 1 `type` and the value MUST be `CssSelector`.
value	Property	The CSS selection path to the Segment. There MUST be exactly 1 `value` associated with a CSS Selector.

Note

Implementers SHOULD use only commonly supported features of CSS that directly contribute to selection of an element or content, rather than styling or transformation, in order to maximize interoperability between systems.

Example §

Example 3 : CSS Selector

{
        "scope": "https://dauwhe.github.io/html-first/MobyDick.wpub",
        "source": "https://dauwhe.github.io/html-first/MobyDickNav/html/c001.html",
        "selector": {
                "type": "CssSelector",
                "value": "#elemid > .elemclass + p"
        }
}

4.3 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.

Note

Implementers should note that the HTML5 specification allows parsers to add elements into the DOM that are considered to be missing. XPaths SHOULD be constructed to include these elements, rather than from the element structure in the document.

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 §

Term	Type	Description
type	Relationship	The class of the Selector. XPath Selectors MUST have exactly 1 `type` and the value MUST be `XPathSelector`.
value	Property	The xpath to the selected segment. There MUST be exactly 1 `value` associated with an XPath Selector.

Note

Implementers SHOULD use only commonly supported features of XPath that directly contribute to selection of an element or content in order to maximize interoperability between systems.

Example §

Example 4 : XPath Selector

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

4.4 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 §

Term	Type	Description
type	Relationship	The class of the Selector. Text Quote Selectors MUST have exactly 1 `type` and the value MUST be `TextQuoteSelector`.
exact	Property	A copy of the text which is being selected, after normalization. Each TextQuoteSelector MUST have exactly 1 `exact` property.
prefix	Property	A snippet of text that occurs immediately before the text which is being selected. Each TextQuoteSelector SHOULD have exactly 1 `prefix` property, and MUST NOT have more than 1.
suffix	Property	The snippet of text that occurs immediately after the text which is being selected. Each TextQuoteSelector SHOULD have exactly 1 `suffix` property, and MUST NOT have more than 1.

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 ]. Also, The text MUST be normalized for the purpose of selection. Thus HTML/XML tags SHOULD be removed, and character entities SHOULD be replaced with the character that they encode.

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.

Note

If the content is under copyright or has other rights asserted on its use, then this method of selecting text is potentially dangerous. For example, a user might select the entire text of the document to annotate, which would not be desirable to copy into the Annotation and share. For static texts with access and/or distribution restrictions, the use of the Text Position Selector is perhaps more appropriate.

Example §

Example 5 : Text Quote Selector

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

4.5 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 §

Term	Type	Description
type	Relationship	The class of the Selector. Text Position Selectors MUST have exactly 1 `type` and the value MUST be `TextPositionSelector`.
start	Property	The starting position of the segment of text. The first character in the full text is character position 0, and the character is included within the segment. Each TextPositionSelector MUST have exactly 1 `start` property, and the value MUST be a non-negative integer.
end	Property	The end position of the segment of text. The character is not included within the segment. Each TextPositionSelector MUST have exactly 1 `end` property, and the value MUST be a non-negative integer.

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.

Note

The use of this Selector does not require text to be copied from the Source when storing, e.g., a bookmarks, unlike the Text Quote Selector, but is very brittle with regards to changes to the resource. Any edits or dynamically transcluded content may change the selection, and thus it is RECOMMENDED that a State be additionally used to help identify the correct representation.

Example §

Example 6 : Text Position Selector

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

4.6 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 as part of her publication. She calculates the start and end positions from the binary stream and stores that as a reference using the DataPositionSelector.

Model §

Term	Type	Description
type	Relationship	The class of the Selector. Data Position Selectors MUST have exactly 1 `type` and the value MUST be `DataPositionSelector`.
start	Property	The starting position of the segment of data. The first byte is character position 0. Each DataPositionSelector MUST have exactly 1 `start` property.
end	Property	The end position of the segment of data. The last character is not included within the segment. Each DataPositionSelector MUST have exactly 1 `end` property.

Example §

Example 7 : Data Position Selector

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

4.7 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 §

Term	Type	Description
type	Relationship	The class of the Selector. SVG Selectors MUST have exactly 1 `type` and the value MUST include `SvgSelector`.
value	Property	The character sequence of the SVG content. There MAY be exactly 1 `value` property associated with the Selector, and if so the value of the property MUST be well-formed SVG XML.

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.

Note

Implementers SHOULD use only commonly supported features of SVG that directly contribute to describing a region, rather than styling or transformation, in order to maximize interoperability between systems. It is NOT RECOMMENDED to include style information within the SVG element, nor Javascript, animation, text or other non-shape oriented information. Clients SHOULD ignore such information if present.

Example §

Example 8 : SVG Selector

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

Example 9 : SVG Selector, embedded

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

4.8 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 text in a Web Publication that spreads over several paragraphs. She selects the start and the end of the selection; her User Agent calculates the Range Selector using the first selection as a start and the second selector as the end.

Model §

Term	Type	Description
type	Relationship	The class of the Selector. Range Selectors MUST have exactly 1 `type` and the value MUST be `RangeSelector`.
startSelector	Relationship	The Selector which describes the inclusive starting point of the range. There MUST be exactly 1 `startSelector` associated with a Range Selector.
endSelector	Relationship	The Selector which describes the exclusive ending point of the range. There MUST be exactly 1 `endSelector` associated with a Range Selector. Both `startSelector` and `endSelector` SHOULD be of the same class.

Example §

Example 10 : Range Selector

{
        "source": "https://dauwhe.github.io/html-first/MobyDickNav/html/c001.html",
        "selector": {
                "type": "RangeSelector",
                "startSelector": {
                        "type": "TextQuoteSelector",
                        "exact": "Call me Ishmael.",
                        "suffix": "Some years ago"
                },
                "endSelector": {
                        "type": "TextQuoteSelector",
                        "exact": "He desires to paint you the dreamiest, ",
                        "prefix": "But here is an artist. ",
                        "suffix": "shadiest, quietest"
                }
        }
}

4.9 Multi Resource Selector §

This section is normative

For some use cases it is required to identify a fragment that spans, possibly, over multiple contiguous members of a group of resources (e.g., a subset in order of the resources which comprise a Web Publication [ wpub ]). A Multi Resource Selection can be used to identify this span by creating an ordered list of Locators. The selection consists of everything from the beginning of the starting selector in the first Locator, all selections identified by the intermediate Locators in the list (if any), through to the beginning of the ending selector, but not including it.

Note

A Range Selector may be considered as a special case for a Multi Resource Selector, albeit defined much more succinctly.

Example Use Case: Előd wants to comment on a text in a Web Publication that spreads over several resources within the Web Publication. He selects the start and the end of the selection in two different constituent resoruces; his User Agent calculates the Multi Resource Selector using the first selection as a start, the second selector as the end, and the resources listed in the default reading order of the Web Publication as intermediate selections.

Editor's note

The reference to the TR version of the WPUB document must be used, when available.

Issue 11 : Is there a need for multi-resource selectors?

The definition is complex, and we have to be sure that the selector really has reasonable use cases. Selection of 2 consecutive resources is covered by the usage of the Embedded Resource Selector (combined with refinement).

Model §

Term	Type	Description
type	Relationship	The class of the Selector. Range Selectors MUST have exactly 1 `type` and the value MUST be `MultiResourceSelector`.
locators	Relationship	A list of Locators. There MUST be exactly 1 `locators` associated with a Multi Resource Selector. The list MUST have at least 1 element.

Example §

Example 11 : Multi Resource Selector

{
        "source": "https://dauwhe.github.io/html-first/MobyDick.wpub",
        "selector": {
                "type": "MultiResourceSelector",
                "locators": [{
                        "source": "https://dauwhe.github.io/html-first/MobyDickNav/html/c001.html",
                        "selector": {
                                "type": "TextQuoteSelector",
                                "exact": "Call me Ishmael.",
                                "suffix": "Some years ago"                           
                        }
                },{
                        "source": "https://dauwhe.github.io/html-first/MobyDickNav/html/c002.html"
                },{
                        "source": "https://dauwhe.github.io/html-first/MobyDickNav/html/c003.html",
                        "selector": {
                                "type": "TextQuoteSelector",
                                "exact": "The opposite wall of this entry",
                                "suffix": " was hung"                          
                        }
                }]
        }    
}

4.10 Embedded Resource Selector §

This section is normative

For some use cases it is required to identify a resource that part of a group of resources, where that group has its own identity on the Web (and can be identified via its own URL). An example may be resource representing a chapter as part of a Web Publication [ wpub ]). An Embedded Resource Selector can be used to identify that resource through the value relationship. This Selector is usually used in conjunction with other Selectors, e.g., through a refinement .

Example Use Case: Janine wants to select the cover image of a Web Publication, which is linked to the Web Publication as a whole. She uses an Embedded Resource Selector to designate the image, with the Web Publication’s address as the Source for the selector.

Model §

Term	Type	Description
type	Relationship	The class of the Selector. Range Selectors MUST have exactly 1 `type` and the value MUST be `EmbeddedResourceSelector`.

value	Relationship	The URL of the resource within the collection or resources identified by the Source . An EmbeddedResourceSelector MUST have exactly 1 `value` property.

Example §

Example 12 : Embedded Resource Selector

{
        "source": "https://dauwhe.github.io/html-first/MobyDick.wpub",
        "selector": {
                "type": "EmbeddedResourceSelector",
                "value": "https://dauwhe.github.io/html-first/MobyDickNav/images/moby-dick-book-cover.jpg"
        }
}

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. Her client records the phrase as a TextQuoteSelector that further modifies a FragmentSelector used to identify the paragraph that the phrase is part of.

Example Use Case: Brianne wants to comment on a text in a Web Publication that spreads over two consecutive resources in a Web Publication. The user agent cannot use the Range Selector with, e.g., Text Quote Selectors directly, because those Selectors would rely on the same Source . Instead, Embedded Resource Selectors are used for the start and the end, each using the Selector Refinement to identify the necessary quote.

Model §

Term	Type	Description
refinedBy	Relationship	The relationship between a broader selector and the more specific selector that should be applied to the results of the first. A Selector MAY be `refinedBy` 1 or more other Selectors. If more than 1 is given, then they are considered to be alternatives that will result in the same selection.

Examples §

Example 13 : Selector Refinement

{
        "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"
                }
        }
}

Example 14 : Embedded Resource Selector used with Refinement

{
        "source": "https://dauwhe.github.io/html-first/MobyDick.wpub",
        "selector": {
                "type": "RangeSelector",
                "startSelector": {
                        "type": "EmbeddedResourceSelector",
                        "value": "https://dauwhe.github.io/html-first/MobyDickNav/html/c001.html",
                        "refinedBy": {
                                "type": "TextQuoteSelector",
                                "exact": "Call me Ishmael"
                        }
                },
                "endSelector": {
                        "type": EmbeddedResourceSelector",
                        "value": "https://dauwhe.github.io/html-first/MobyDickNav/html/c002.html",
                        "refinedBy": {
                                "type": "TextQuoteSelector",
                                "exact": "A hundred black faces turned around"
                        }
                }
        }
}

5. States §

A State describes the intended state of a resource when selected, and thus provides the information needed to retrieve the correct representation of that resource. Web resources change over time, and a State might be used to describe how to recover the intended previous version. Web resources also have multiple formats, and a State might equally be used to describe how to retrieve that particular format.

The state aspect of a Web Resource requires two distinct entities:

the URL of the overall resource; this is the same Source as used for Selectors (see 4. Selectors ).
the identification for the state of the resource.

A State object is used to describe how to determine the state of interest from within the Source resource. These two entities are encapsulated in a Locator .

Example Use Case: Alexandra visualizes data on a web page that changes frequently. Her client records information to allow other clients to hopefully reconstruct the original visualization.

Model §

Term	Type	Description
state	Relationship	The relationship between the Locator and the State . There MAY be 0 or more `state` relationships for each Locator. Multiple States SHOULD select the same content, however some States will not have the same precision as others. Consuming user agents MUST pick one of the described segments , if they are different.

States MUST be processed before processing Selector information.

Example §

Example 15 : State

{
        "source": "http://example.org/page1",
        "state": {
                "id": "http://example.org/state1"
        }
}

5.1 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 §

Term	Type	Description
type	Relationship	The class of the State. Time States MUST have exactly 1 `type` and the value MUST be `TimeState`.
sourceDate	Property	The timestamp at which the Source resource should be interpreted. There MAY be 0 or more `sourceDate` properties per TimeState. If there is more than 1, each gives an alternative timestamp at which the Source may be interpreted. The timestamp MUST be expressed in the `xsd:dateTime` format, and MUST use the UTC timezone expressed as "Z". If `sourceDate` is provided, then `sourceDateStart` and `sourceDateEnd` MUST NOT be provided.
sourceDateStart	Property	The timestamp that begins the interval over which the Source resource should be interpreted. There MAY be exactly 1 `sourceDateStart` property per TimeState. The timestamp MUST be expressed in the `xsd:dateTime` format, and MUST use the UTC timezone expressed as "Z". If `sourceDateStart` is provided then `sourceDateEnd` MUST also be provided.
sourceDateEnd	Property	The timestamp that ends the interval over which the Source resource should be interpreted. There MAY be exactly 1 `sourceDateEnd` property per TimeState. The timestamp MUST be expressed in the `xsd:dateTime` format, and MUST use the UTC timezone expressed as "Z". If `sourceDateEnd` is provided then `sourceDateStart` MUST also be provided.
cached	Relationship	A link to a copy of the Source resource's representation, appropriate for the application. There MAY be 0 or more `cached` relationships per TimeState. If there is more than 1, each gives an alternative copy of the representation.

Example §

Example 16 : Time State

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

5.2 Request Header State §

As there are potentially many representations that can be delivered from a resource with a single URL, 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 §

Term	Type	Description
type	Relationship	The class of the State. Request Header States MUST have exactly 1 `type` and the value MUST be `HttpRequestState`.
value	Property	The HTTP request headers to send as a single, complete string. An HttpRequestState MUST have exactly 1 `value` property.

Note

The representation retrieved from the server by the original annotator's client might not be completely determined by request headers alone. For example, the IP address of the client might also determine the language of the representation, based on the language of the country the user was present in at the time. If the server returns a


Content-Location

header, then the client might instead use it as the


target

of the Annotation, rather than the URL that was requested.

Example §

Example 17 : HTTP Request State

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

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 §

Term	Type	Description
refinedBy	Relationship	The relationship between a broader State and either a more specific State or a Selector that SHOULD be applied to the results of the first. Each State MAY be `refinedBy` 1 or more other States or Selectors. If more than 1 is given, then they are considered to be alternatives that will result in the same result.

Example §

Example 18 : Refinement of States

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

6. Selectors and States as Fragment Identifiers §

Although Selectors and States provide a flexible way of identifying, e.g., a suitable Segment of a Resource, the fact that this is defined through an indirection using a Locator may be an obstacle for some applications.

Editor's note

We must add a good example. The original one referred to RDF, which is not relevant in this context.

To mitigate this issue, a mapping of Selectors and States on URL fragments [ url ] is defined below. As a result of this mapping the targeted Segment , or the relevant state, is expressed in a single (albeit complex) URL. In that URL the Selector , respectively the State , is expressed as a single string and serves as a fragment combined with the URL of the Source . Note that this representation is valid only if the URL for the Source does not contain a fragment identifier of its own (a URL may contain at most one fragment identification).

The syntax for mapping a Selector , respectively a State , follows the same, “functional” syntax as used, for example, by the XPointer Framework [ xptr-framework ]:

The fragment uses the selector(…), respectively the state(…), functional syntax
The (comma separated) “parameters” of the functional notation are:
- For the keys refinedBy, startSelector, and endSelector the syntax is key=selector(…), respectively key=state(…) when appropriate, with the value following, recursively, the same syntax as the full fragment;
- For the key locators the content is a comma separated list of locators;
- otherwise the key, and the corresponding value, follows the simple key=value syntax, e.g., type=FragmentSelector.

(see the examples below.)

Editor's note

The reference to the Web Publication Resources should be changed to use the short name of the WP specification, as opposed to the editor's draft like now.

The values SHOULD be percent encoded [ rfc3986 ]; the encoding is a MUST for characters that may make the fragment ambiguous, namely:

character	code
space	%20
`=`	%3D
`,`	%2C
`#`	%23

Note

A fragment identifier is defined for a specific media type. This means that, formally, the fragment identifier syntax and semantics defined in this section should be registered for each media type separately by IANA . Until such a registration is done, these fragment identifiers have the potential to conflict with other fragments possibly specified by the media type registrations. Consequently, this pattern should only be used when the implementation cannot produce or manage the full representation described above.

6.1 JSON examples converted to fragment identifiers §

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

Example for a 4.1 Fragment Selector

Example 19 : Fragment Selector as Fragment

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

Example for a 4.2 CSS Selector

Example 20 : CSS Selector as Fragment

https://dauwhe.github.io/html-first/MobyDickNav/html/c001.html#selector(
        type=CssSelector,
        scope=https://dauwhe.github.io/html-first/MobyDick.wpub
        value=%23elemid%20>%20.elemclass%20+%20p,
)

Example for a 4.3 XPath Selector

Example 21 : XPath Selector as Fragment

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

Example for a 4.4 Text Quote Selector

Example 22 : Text Quote Selector as Fragment

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

Example for a 4.5 Text Position Selector

Example 23 : Text Position Selector as Fragment

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

Example for a 4.6 Data Position Selector

Example 24 : Data Position Selector as Fragment

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

First example for a 4.7 SVG Selector

Example 25 : SVG Selector as Fragment, referring to an external SVG

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

Second example for a 4.7 SVG Selector

Example 26 : SVG Selector as Fragment, using embedded SVG

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 URL as shown in Example 22 .

Example for a 4.8 Range Selector

Example 27 : Range Selector as Fragment

https://dauwhe.github.io/html-first/MobyDickNav/html/c001.html#selector(
type=RangeSelector,
startSelector=selector(
        type=TextQuoteSelector,
        exact=Call%20me%20Ishmael.,
        suffix=Some%20years%20ago
),
startSelector=selector(
        type=TextQuoteSelector,
        exact=He%20desires%20to%20paint%20you%20the dreamiest,%20, 
        prefix=But%20here%20is%20an%20artist.%20, 
        suffix=shadiest%2C%20quietest
)
                                )

Example for a 4.9 Multi Resource Selector

Example 28 : Multi Resource Selector as Fragment

https://dauwhe.github.io/html-first/MobyDick.wpub#selector(
        type=MultiResourceSelector,
        selector(
                source=https://dauwhe.github.io/html-first/MobyDickNav/html/c001.html
                type=TextQuoteSelector,
                exact=Call%20me%20Ishmael.,
                suffix=Some%20years%20ago
        ),
        selector(
                source=https://dauwhe.github.io/html-first/MobyDickNav/html/c002.html
        ),
        selector(
                source=https://dauwhe.github.io/html-first/MobyDickNav/html/c003.html
                type=TextQuoteSelector,
                exact=The%20opposite%20wall%20of%20thi%20entry, 
                suffix=%20was%20hung
        )
)

Example for an

Example 29 : Embedded Resource Selector as Fragment

https://dauwhe.github.io/html-first/MobyDick.wpub#selector(
        type=EmbeddedResourceSelector,
        value=https://dauwhe.github.io/html-first/MobyDickNav/images/moby-dick-book-cover.jpg
)

Example for a 4.11 Refinement of Selection

Example 30 : Selector Refinement as Fragment

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 4.11 Refinement of Selection

Example 31 : Embedded Resource Selector Refined in a Range Selector

https://dauwhe.github.io/html-first/MobyDick.wpub#selector(
        type=RangeSelector,
        startSelector=selector(
                type=EmbeddedResourceSelector,
                value=https://dauwhe.github.io/html-first/MobyDickNav/html/c001.html
                refinedBy=selector(
                        type=TextQuoteSelector,
                        exact=Call%20me%20Ishmael.
                )
        ),
        endSelector= selector(
                type=EmbeddedResourceSelector,
                value=https://dauwhe.github.io/html-first/MobyDickNav/html/c002.html
                refinedBy=selector(
                        type=TextQuoteSelector,
                        exact=A%20hundred%20black%20faces%20turned%20around,                                                                    
                )
        )
)

Example for a 5.1 Time State

Example 32 : Time State as Fragment

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

Example for a 5.2 Request Header State

Example 33 : HTTP Request State as Fragment

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

Example for a 5.3 Refinement of State

Example 34 : Refinement of States as Fragment

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

	Fragment	CSS	XPath	Text Quote	Text Position	Data Position	Svg
HTML (text/html)	✔︎	✔︎	✔︎	✔︎	✔︎	✘	✘
CSV (text/csv)	✔︎	✘	✘	✔︎	✔︎	✘	✘
Plain Text (text/plain)	✔︎	✘	✘	✔︎	✔︎	✘	✘
Other text files (text/*)	?	✘	✘	✔︎	✔︎	✘	✘
PDF (application/pdf)	✔︎	✘	✘	✔︎	✔︎	✘	✘
XML (application/xml, application/*+xml)	✔︎	✔︎	✔︎	✔︎	✔︎	✘	✘
SVG (image/svg+xml)	✔︎	✔︎	✔︎	✔︎	✔︎	✘	✔︎
Image, other than SVG (image/gif, image/jpeg, image/png, image/tiff)	✔︎	✘	✘	✘	✘	?	✔︎
Video (video/*)	✔︎	✘	✘	✘	✘	?	✔︎
Binary Data Files	?	✘	✘	✘	✘	✔︎	✘

	Fragment	CSS	XPath	Text Quote	Text Position	Data Position	Svg
CSS (text/css)	✘	✘	✘	✔︎	✔︎	✘	✘
TSV (text/tab-separated-values)	✔︎ ^✝	✘	✘	✔︎	✔︎	✘	✘
JSON (application/json, application/*+json)	✘	✘	✘	✔︎	?	✘	✘
Programming languages (application/javascript, python files, etc.)	✘	✘	✘	✔︎	?	✘	✘
^✝ Fragments are not formally defined through IETF, though there are well-known connections to existing fragments or practices.

Term	Usage
cached	Time State
conformsTo	Fragment Selector
end	Text Position Selector , Data Position Selector
endSelector	Range Selector
exact	Text Quote Selector
locators	Multi Resource Selector
prefix	Text Quote Selector
refinedBy	Selector , State
selector	Locator
scope	Locator
source	Locator
sourceDate	Time State
sourceDateEnd	Time State
sourceDateStart	Time State
start	Text Position Selector , Data Position Selector
startSelector	Range Selector
state	Locator
suffix	Text Quote Selector
type	Locator , Fragment Selector , CSS Selector , XPath Selector , Text Quote Selector , Text Position Selector , Data Position Selector , SVG Selector , Embedded Reosource Selector , Multiple Resource Selector , Time State , Request Header State
value	Fragment Selector , CSS Selector , SVG Selector , XPath Selector , Embedded Resource Selector , Request Header State

Locators for Web Publications

W3C Editor's Draft 23 24 October 2017 §

Abstract

Status of This Document

1. Conformance §

1.1 Handling Undefined JSON Properties §

1.2 Conformance requirements related to specific selectors §

2. Introduction §

2.1 Terminology §

3. Locators §

Model §

4. Selectors §

Model §

Example §

4.1 Fragment Selector §

Model §

Example §

4.2 CSS Selector §

Model §

Example §

4.3 XPath Selector §

Model §

Example §

4.4 Text Quote Selector §

Model §

Example §

4.5 Text Position Selector §

Model §

Example §

4.6 Data Position Selector §

Model §

Example §

4.7 SVG Selector §

Model §

Example §

4.8 Range Selector §

Model §

Example §

4.9 Multi Resource Selector §

Model §

Example §

4.10 Embedded Resource Selector §

Model §

Example §

4.11 Refinement of Selection §

Model §

Examples §

5. States §

Model §

Example §

5.1 Time State §

Model §

Example §

5.2 Request Header State §

Model §

Example §

5.3 Refinement of State §

Model §

Example §

6. Selectors and States as Fragment Identifiers §

6.1 JSON examples converted to fragment identifiers §

7. Correspondence Among Media Types and Selectors §

7.1 Additional Media Types/Selector Combination §

A. Changes from Previous Versions §

A.1 Changes from the “Selectors and States” Note §

B. Index of JSON Terms §

C. Relationships to the Web Annotation Model §

D. Issue Summary §

D. E. Acknowledgements §

E. F. References §

E.1 F.1 Normative references §

E.2 F.2 Informative references §