compose_page_jsonld

documenteer.citations.compose_page_jsonld(citations, *, page_url=None, self_citation=None, site_title=None, site_url=None)

Compose the citations that claim one page as that page’s own schema.org JSON-LD document, serialized ready to embed in a <script type="application/ld+json"> element.

Parameters:

• citations (Sequence[Mapping[str, Any]]) – The citations whose landing page this page is — the entries whose GuideCitation.page names it — each as the mapping GuideCitation.to_html_context composes, in declaration order.

• page_url (str | None, default: None) – The page’s own absolute URL, without a fragment. Each node’s url is this URL plus that citation’s own fragment. None when the site declares no base URL, in which case each node keeps the location its record already carries (the doi.org redirect).

• self_citation (Mapping[str, Any] | None, default: None) – The site’s own citation, as the same kind of mapping. Each node names it as the work it is isPartOf. None for a site that marks no citation self, whose parts name the site itself instead.

• site_title (str | None, default: None) – The site’s own title, and site_url its base URL. Together they describe the site as a WebSite node, which is what a part names under isPartOf on a site with no self citation. Both are ignored when self_citation is given, whose work is the whole instead.

• site_url (str | None, default: None) – See site_title.

Returns:

The serialized JSON-LD document, or None when no citation claims the page — such a page keeps the site-wide block instead.

Return type:

str | None

Notes

This is the per-page counterpart of compose_landing_page_jsonld. Where that one describes the site, this one describes only the works registered against this page, because those works’ landing page is this page and a consumer arriving from doi.org must find the DOI it came for at the top of the document.

A single claiming citation is the document’s own subject. Several are emitted as a @graph: they are peers on the page, told apart by their fragments, and subordinating one to the others would misstate the page.

Each node also points back at the whole it is a part of, which is the other half of the hasPart relation compose_landing_page_jsonld states site-wide. Both ends are stated so that a consumer arriving at either one can reach the other, and both are stated by reference so that neither repeats a record the other already carries in full. The whole is the site’s own citation where it marks one self, and the site’s own WebSite node — the subject of the site-wide block — where it marks none; see _part_of_node.