Hypothesis uses common metadata conventions to identify and alias documents (a process called “establishing document equivalence”). Publishers and website owners can use these conventions in order to make sure annotations remain visible on documents, even if they are moved, syndicated, or hosted at multiple locations. Hypothesis can also record which version of a document an annotation was made on, so that a set of versions remains a single document while readers see only the annotations belonging to the version in front of them. See Multiple versions of the same document below.
This help article contains recommendations for establishing or troubleshooting document equivalence. For a more detailed look at the concepts discussed here, see our help article on how Hypothesis interacts with document metadata.
Resilience to URL change
There are three change-resilient ways for Hypothesis to associate annotations with documents:
-
- For DOI-equipped HTML documents: If an annotation’s target document declares a DOI, Hypothesis will bind the annotation to all documents that declare the same DOI. An example URL-independent identifier: doi:10.1126/science.51.1305.8 doi:
- For PDF files: If an annotation’s target document is a PDF, Hypothesis will bind it to all copies of that PDF. An example URL-independent identifier: urn:x-pdf:db49e0a7b073bbadeb889a910835b716
- For other HTML documents: If the target is neither an HTML page with a DOI nor a PDF, Hypothesis can use the dc.identifier / dc.relation.ispartof syntax. An example URL-independent identifier: urn:x-dc:elifesciences.org/blog-article/e3d858b3.
See a full example here.
Keep reading for more details on how these methods work.
HTML pages
Scholarly publishers: use Highwire Press tags or Dublin Core metadata to establish document equivalence.
The Hypothesis system can map a DOI to a URL or multiple URLs. Including a document’s DOI in the metadata of a web page will ensure that annotations appear on that document regardless of where it’s hosted.
For example, an article published by Cell includes the tag
<meta name="citation_doi" content="10.1016/j.ajhg.2017.02.007">.
That same article at PubMed Central includes the same tag. Annotations made on this article over at Cell will show when you view the article at PubMed Central and vice versa.
There are two ways for a scholarly web page to declare its URL as an alias for a DOI. The most common method is a de facto standard known as the Highwire Press tag set, popular because it’s supported by Google Scholar. Another way comes from the Dublin Core Metadata Initiative. It’s common for both of these to be included in scholarly metadata. For the Hypothesis system, either is sufficient to establish a DOI/URL mapping for the purpose of annotation.
If you’re using Dublin Core metadata to establish URL aliases for DOIs and the annotations are not syncing as expected, check the formatting of your tags to ensure that http://doi.org/ or https://doi.org/ is not included in the value attribute of the dc.identifier tag.
Other publishers and website owners: be careful with canonical link relations and use Dublin Core metadata
Hypothesis unifies documents that contain the same <link rel="canonical"> tag and does not unify documents that contain the same <link rel="alternate"> tag (except when the alternate link points to mobile vs desktop versions of the same page – in that case, Hypothesis will unify those two documents). Be careful applying one canonical URL across a set of pages that should keep their annotations separate. If the individual chapters of a book all declare the same work-level canonical URL, Hypothesis will treat every chapter as one document, and annotations from one chapter will be served on all the others. Giving each chapter its own DOI will not prevent this, but versioning information potentially can help. See our metadata help article for a fuller explanation.
Note: There is currently no way to remove aliases interactively or by means of the Hypothesis API— meaning once a document has been associated with a canonical URL, there isn’t a way to “un-associate” it.
If annotations made on one page are showing on another page where you would not expect them to, check the <head> of each page for a <link rel="canonical"> tag or a <link rel="alternate"> tag pointing to a desktop or mobile version of a web page.
If you would like annotations to “follow” a page to a new URL, you could use <link rel="canonical"> tags, but this is not recommended because it is still URL-dependent. Instead, we recommend using Dublin Core metadata to create future-proof, URL-independent identifiers. Note one exception: if you plan to use version filtering, a <link rel="canonical"> tag is required. Version detection reads the canonical link and does not read Dublin Core metadata.
See our help article on how Hypothesis interacts with metadata for information on using Dublin Core metadata on documents that do not have DOIs.
Multiple versions of the same document
If you publish more than one version of a document — a revised preprint, for example — you have two options, and they produce different results.
Keep versions separate
Give each version its own DOI. Hypothesis will treat each version as a separate document with its own annotations.
If you take this approach and your pages use <link rel=”canonical”> tags, make sure each version’s canonical URL is distinct. Versions that share a canonical URL will be treated as the same document even when their DOIs differ, because Hypothesis unifies documents on a match of any identifier they declare.
The tradeoff is that separate documents can’t be queried together. There’s no way to view annotations across every version of the document through the API.
Use the same DOI and filter by version
Use the same DOI across every version, and add version information to your page metadata. All versions remain a single Hypothesis document, but the client shows readers only the annotations made on the version they’re viewing.
To do this, append the version to all three of the following, using the same version number in each:
<meta name="citation_id"><meta name="citation_public_url"><link rel="canonical">
Note that a <link rel="canonical"> tag is required for version detection. Version information is not read from Dublin Core metadata.
The version goes at the very end of each value, preferably in the form _v1 or .v1. All three must carry it and all three must agree, or no version is recorded. For the full rules see Document versions in our metadata help article.
Version filtering comes entirely from your page metadata — it isn’t a control readers can turn on or off. It also applies to HTML documents only, not PDFs.
PDFs
If you want annotations to sync across multiple copies of a PDF, check the fingerprint of each copy to ensure they’re all the same. If you want to prevent annotations from syncing across copies of a PDF, save new copies of the PDF with unique fingerprints. Version filtering does not apply to PDFs.
HTML and PDF versions of the same document
If you want to sync annotations between HTML and PDF versions of a document, use <meta name="citation_pdf_url"> and make sure the value of the tag’s content attribute is a URL that points to a PDF directly, not to an HTML page that embeds the PDF. For guidance on using <meta name="citation_pdf_url"> see the section of our metadata help article on PDF-related HTML metadata.