What is Scholarly HTML?

File & Supporting Structure

The document must be encoded in UTF-8, and transmitted with a media type of text/html. It must feature a DOCTYPE as its preamble.

The html root element must feature a valid lang attribute.

The head element of the document must contain a <meta charset="utf-8"> element (preferable as its first child), a <meta name="viewport" content="width=device-width"> element (and no other viewport meta), and a title element. All the other content of the head is ignored.

The body element must have a prefix attribute, which must declare the following mapping:

Having to declare prefixes is undoubtably an annoyance and it does hurt the human authorability of the format (since hand-creating a document essentially requires a boilerplate prefix declaration). This trade-off is made for several reasons. The most important motivation is that having predictable prefixes means that the content can be styled with CSS using reliable attribute selectors on the semantic information that describes the document’s structure. The alternative would be to use URLs everywhere, such that instead of sa:Abstract we would have https://ns.science.ai/Abstract; but in practice that approach is more painful since the content then becomes bloated with URLs that are longer than is comfortable.

The RDFa content of the article must systematically make use of these prefixes when the values match their URLs as prefixes. Authors may declare other prefix-URL mappings in the prefix attribute of the body element (or prefix attributes elsewhere), including other prefixes mapping to the same URLs if needed, but inside of the article’s content these prefixes must be used for these URLs.

Article Structure

The article content is everything that is contained inside the first article element in document order that has a typeof="schema:ScholarlyArticle". Everything part of the body outside of that subtree is ignored. This enables publishers to surround the article content with any amount of supporting markup, for instance for headers, footers, or navigation, as well as to wrap the article inside arbitrary markup that may be needed for stylistic reasons.

The article element should have a resource attribute, usually with a value of #. The reason for that is to grant it a URL that can be targeted by other properties. The resource attribute can take any value, but it must then be matched by the about attributes of the properties targeting it. If resource is omitted, the only way in which those properties can target it is by knowing the URL from which the document was retrieved.

The first element child of the article element must be an h1 heading that serves as the primary title for the document. It may itself contain markup. The white-space-normalised text value of the h1 must appear as a substring of the white-space-normalised text value of the title element. This ensures semantic alignment between the two, while enabling publishers to add their name to the title so as to identify themselves there alongside the content.

Any children of article that are not section elements are ignored.

The first section child element of the article must be the Authors and Affiliations section. It has no typeof and its specific rules are outlined in its own chapter below.

The section elements can be nested arbitrarily deep. Each section element must have as its first element child an hX heading element the numeric part of which must be the number of section ancestor elements that heading elements has up to the article element, plus one. If the numeric part is greater than 6, then h6 must be used but an aria-level attribute must be added that reflects the accurate depth. (The aria-level attribute can be used at lower depths but is not required there.)

Each section element may contain an arbitrary number of hunk elements, followed by an arbitrary number of section elements being subsections. Note that hunk elements must imperatively appear before the subsections.

Sections are expected to be typed using the typeof attribute. The following typeof values are currently understood:

• sa:Funding (which has its specific structure)
• sa:Abstract
• sa:MaterialsAndMethods
• sa:Results
• sa:Conclusion
• sa:Acknowledgements
• sa:ReferenceList

Hopefully these types are largely self-documenting, they are described further in the Scholarly Article ontology (Science.AI, 2015a).

The section typed sa:ReferenceList has special processing rules described in the References section.

Hunk Elements

Hunk elements are the meaningful blocks from which sections are built. They contain text and inline elements. There are several types of hunk elements.

The most common hunk element is p, which is used to capture paragraphs. It requires no special processing.

The blockquote, ul, ol, and dl elements can be used as they typically would and require no special treatment.

The aside hunk element is used to capture text boxes. If it contains an hX heading element, that element must be its first element child and its numeric part must reflect its depth, making use of aria-level according to the same rules as apply for section. The other children of aside must all be hunk elements.

The figure element is a general container for content units that are embedded inside the main body of the text. It can come in several flavours that are dictated by its typeof attribute.

If figure has typeof="sa:Image" then it is an image container. It must contain an img child element and should contain a figcaption labelling that image. An example of an image figure would be:

If figure has typeof="sa:Table" then it is a table container. It must contain nothing other than a table element. If a caption is available, it should be included using the caption child element of the table, and not the figcaption child of the figure.

If figure has typeof="sa:Formula" then it is a formula container. It must contain a math element and optionally a figcaption describing the formula. The math element must be valid MathML 3. Additionally, given the dismal state of support for MathML in Web browser the math element must contain an annotation descendant with the TeX equivalent of the formula.

If figure has typeof="schema:SoftwareSourceCode" then it is a code container. It must contain a pre element and optionally a figcaption. The pre element must contain as its only child a code element.

If you wish to specify the type of the language used in the code, the figure needs to have a schema:programmingLanguage property containing a type schema:Language, itself with a schema:name containing the the lowercase name of one of the languages from the list of programming languages. Canonically, this would look like the following source:

<figure typeof="schema:SoftwareSourceCode">
  <pre property="schema:programmingLanguage" typeof="schema:Language">
    <meta property="schema:name" content="python">
    <code>import foo</code>
  </pre>
  <figcaption>
    How to import foo.
  </figcaption>
</figure>
            

Inline Elements

Inline elements essentially decorate, describe, and enrich text. Inside of hunk elements, of heading elements, and of captioning elements (caption and figcaption) the following inline elements can be used (and where applicable they can nest within one another):

• a
• abbr
• bdi
• bdo
• cite
• code
• data
• del
• dfn
• em
• img (for small, contextual images that should not be figures)
• ins
• kbd
• mark
• math (for inline equations that should not be figures; they must also contain a TeX annotation)
• meter
• q
• ruby (with embedded rb, rt, rtc, and rp)
• samp
• span
• strong
• sub
• sup
• svg (for small, contextual images that should not be figures)
• time
• var
• wbr

If an a element is linking to a citation, then it must have property="schema:citation"; if it is linking to a figure or another creative work, it must have property="schema:hasPart" or property="schema:isBasedOnUrl". These are known as flavoured links, they can be used to enhance the user experience by treating their behaviour differently from regular links.

The References Section

The references section is a special type of section element with typeof="sa:ReferenceList".

Apart from its heading element, it must contain nothing other than an ol or a dl element.

If using a dl element, its content must be exclusively a strictly alternating sequence of dt then dd elements, with the latter being the citation-bearing element. The dt is used as a label in some citation formats.

If using an ol, then its content is only li elements that are the citation-bearing elements.

The citation-bearing element will have an id and be schema:Book for books or typeof="schema:ScholarlyArticle" (or its subclass schema:MedicalScholarlyArticle, with probably more to come). Its content follows the «flexcite» format (being defined as part of this document, see #4). The references section of this document is an example.

<li id="ref-something" typeof="schema:ScholarlyArticle"
       resource="http://dx.doi.org/10.1000/182">
  <span property="schema:author" typeof="schema:Person">
    <span property="schema:familyName">Jones</span>
    <span property="schema:givenName">K</span><span
             property="schema:additionalName">E</span>
  </span>,
  <span property="schema:author" typeof="schema:Person">
    <span property="schema:familyName">Patel</span>
    <span property="schema:givenName">N</span>
  </span>.
  <cite property="schema:name">Global trends in emerging infectious diseases.</cite>
  <span property="schema:isPartOf" typeof="schema:PublicationVolume">
    <span property="schema:isPartOf" typeof="schema:Periodical">
      <span property="schema:name">Nature.</span>
    </span>
    <time about="http://dx.doi.org/10.1000/182" property="schema:datePublished"
             datetime="2008-01" datatype="xsd:gYearMonth">2008 Jan</time>;
    <span property="schema:volumeNumber">451</span>
  </span>:<span property="schema:pageStart">990</span>-<span
                      property="schema:pageEnd">4</span>
</li>
            

At the semantics level, a citation is a schema:ScholarlyArticle (or subtype) with an id to reference it internally in the document and a resource that is a URL identifying it (its DOI for instance, preferable in HTTP-retrievable form).

That schema:ScholarlyArticle has any number of schema:author which are schema:Person (with the usual schema:givenName, schema:familyName, etc.). A child cite element, with property="schema:name" (and optionally a link child) provides the title of the article.

The publisher is described using a nested schema:isPartOf structure of schema:PublicationIssue, schema:PublicationVolume, and schema:Periodical (with only those that are known being used). Both schema:volumeNumber and schema:issueNumber may be used on the volume and issue.

A time element with property="schema:datePublished" provides the publication date, which is expressed in text in human-readable form and in the datetime attribute in standard form. A datatype attribute matching the date format must be provided.

Both schema:pageStart and schema:pageEnd may be provided.

Beyond the semantics, a more specific serialisation known a «Flexcite» is in the works and will be added here soon. Its properties are simple: when unstyled it reads linearly in a human-friendly manner (so as to be accessible), and it can be styled with CSS to be turned into arbitrary citation style preferences.

The Authors & Affiliations Section

Capturing authors, the affiliations and their relationship to the article is the most intricate part of Scholarly HTML. Care was taken to avoid repetition and to keep the markup density as reasonable as possible, but the data to content ratio remains relatively high.

It is probably best to start from an example and then to explain it:

<!-- The author and contributor list -->
<article resource="#">
  …
  <section>
    <ol>
      <!-- The first author, Robin Berjon -->
      <li property="schema:author" typeof="sa:ContributorRole">
        <a property="schema:author" href="http://berjon.com/" typeof="schema:Person">
          <span property="schema:givenName">Robin</span>
          <span property="schema:familyName">Berjon</span>
        </a>
        <a href="#scienceai" property="sa:roleAffiliation" resource="http://science.ai/">a</a>
        <sup property="sa:roleContactPoint" typeof="schema:ContactPoint">
          <a property="schema:email" href="mailto:robin@berjon.com" title="corresponding author">✉</a>
        </sup>
      </li>
      <!-- A contributor, Sebastien Ballesteros -->
      <li property="schema:contributor" typeof="sa:ContributorRole">
        <a property="schema:contributor" href="https://github.com/sballesteros" typeof="schema:Person">
          <span property="schema:givenName">Sebastien</span>
          <span property="schema:familyName">Ballesteros</span>
        </a>
        <a href="#scienceai" property="sa:roleAffiliation" resource="http://science.ai/">a</a>
      </li>
    </ol>
    <!-- The affiliation list -->
    <ol>
      <li id="scienceai">
        <a href="http://science.ai/" typeof="schema:Corporation">
          <span property="schema:name">science.ai</span>
        </a>
      </li>
    </ol>
  </section>
  …
</article>
            

The markup is relatively convoluted, but the data model is rich:

This section has no typeof and no heading element. It contains a first ol which lists authors, and optionally a second ol to list affiliations.

Each li in the authors ol has property="schema:author" or property="schema:contributor" and a typeof="sa:ContributorRole".

A sa:ContributorRole type (following the semantic of schema.org Role) is used so that affiliations or contact informations (email address, etc.) relevant to this specific scholarly article (and this specific scholarly article only) can be specified. This is important as authors may have different affiliations and contact points at the time they are publishing a scholarly article but may want to specify only a subset of those. Readers not familiar with the semantic of schema.org Role can consult the introductory blog post.

Inside of that li, arbitrary properties of schema:Person, filling the schema:author property of the sa:ContributorRole can be specified, but providing at least schema:givenName and schema:familyName. It is recommended that these properties are wrapped into an hyperlink identifying the person with a URL to their home page, their ORCID, or an email address.

If there is an affiliations ol and a given author is affiliated, there must be an a element with its href pointing to that affiliation, a resource matching the URL identifying the affiliation, and property="schema:roleAffiliation". The content of that a element must be a string that matches the one that will be generated by CSS to label the affiliation; Latin lowercase being recommended. (This is a hack, but we can only do so much within the limits of CSS — better counter would be needed.)

If an author (or contributor) is a corresponding author, a last sup element needs to be added to its li with property="sa:roleContactPoint", typeof="schema:ContactPoint" (or subclass). Inside the sup element, there must be at least a link to the contributor email address (mailto:). More contact information such as properties of schema:PostalAddress may be added using meta tags.

If there is an affiliations ol, each li in it must have an id which the authors link to. In turn it contains an a element linking to the affiliation with typeof set to either schema:Organization or one of its subtypes. Inside the a needs to sit a span (or any acceptable element, really) with property="schema:name", containing the name.

The Funding Section

The funding information attached to an article involves a list of sponsors each of which offers a list of funding sources. Again, an example probably makes the idea clearer:

<article resource="#">
  <!-- This work was sponsored by the Child Detection Agency (CDA) under the grant grantId -->
  <section typeof="sa:Funding">
    <h2>Funding</h2>
    <p about="#" rel="schema:sponsor">
      <span typeof="sa:SponsorRole">
        This work was sponsored by the
        <a
         property="schema:sponsor"
         href="http://pixar.wikia.com/wiki/CDA"
         typeof="schema:Organization"
        >
          <span property="schema:name">Child Detection Agency</span>
          (<span property="schema:alternateName">CDA</span>)
        </a> under the grant
        <a
         property="sa:roleOffer"
         typeof="sa:FundingSource"
         href="http://pixar.wikia.com/wiki/CDA#grantId"
        >
          <span property="schema:serialNumber">grantId</span>
        </a>
      </span>
    </p>
  </section>
</article>
            

The section has typeof="sa:Funding" and an arbitrary heading title, like other sections.

It contains a series of hunks that are rel="schema:sponsor" (there can also be other content, it is ignored for our purposes). The example above uses a p and a narrative style for its content, but you have freedom to use other encodings.

As for contributor affiliations, source of fundings are expressed using a subclass of schema:Role (sa:SponsorRole). The usage of schema.org Role type is needed to describe the source of fundings specific to a scholarly article as opposed to all the source of funding of an organization (relevant or not to our scholarly article of interest).

The funder will be typeof="schema:Organization" (or a subtype thereof), as the object of a schema:sponsor property on the sa:SponsorRole. It will be identified through its URL (as in the a above), and will typically have schema:name and often schema:alternateName.

The specific source of funding is of type sa:FundingSource, as the object of a sa:roleOffer property on the sa:SponsorRole. It should have a URL identifying it and a schema:serialNumber that is its labeled identity.

Data rich scholarly articles

Scholarly Articles are often part of a larger network of creative works containing dataset, code, additional figures, tables or media (audio, video). Even within a scholarly article, some creative works can be encoded in different ways (for instance, figures typically comes in different resolutions). Scholarly HTML aims to formally describe (and help archive) this larger context.

Further data about a scholarly graph can be exposed within the article in RDFa or as JSON-LD islands. When JSON-LD is used, it is recommended not to duplicate the data already serialized in RDFa. JSON-LD should be reserved to expose data not directly present in the HTML markup.

{
  "@context": "http://schema.org",
  "@id": "http://example.com/graph",
  "@graph": [
    {
      "@id": "http://example.com/article",
      "@type": "ScholarlyArticle",
      "isPartOf": "http://example.com/graph",
      "isBasedOnUrl": ["http://example.com/code"],
      "hasPart": {
        "@id": "http://example.com/image",
        "@type": "Image",
        "encoding": [
          {
            "@id": "http://example.com/encodingsmall",
            "@type": "ImageObject",
            "contentUrl": "http://example.com/small"
            "height": "400px",
            "width": "400px",
            "isBasedOnUrl": ["http://example.com/encodinglarge"]
          },
          {
            "@id": "http://example.com/encodinglarge",
            "@type": "ImageObject",
            "contentUrl": "http://example.com/large",
            "height": "1200px",
            "width": "1200px"
          }
        ]
      }
    },
    {
      "@id": "http://example.com/code",
      "@type": "SoftwareSourceCode",
      "codeRepository": "http://example.com/repository",
      "isPartOf": "http://example.com/graph"
    }
  ]
}
            

A scholarly graph provides a manifest for a scholarly article listing all the creative works, their encodings and the relationship between these objects (expressed with schema:hasPart and schema:isBasedOnUrl).

Semantic context of a scholarly article

Scholarly Articles (and their associated resources) are frequently tagged to improve their discoverability. For instance, the National Library of Medicine uses the Medical Subject Headings (MeSH) controlled vocabulary to index journal articles in the life sciences. Scholarly HTML leverages schema.org and the schema:about property to efficiently expose this information to search engines. When possible, schema.org MedicalEntity (and subclasses) should be used to describe biomedical concepts.

{
  "@context": "http://schema.org",
  "@id": "http://example.com/article",
  "@type": "ScholarlyArticle",
  "about": {
    "@id": "http://id.nlm.nih.gov/mesh/D007251",
    "@type": "InfectiousDisease",
    "name": "Influenza, Human",
    "description": "An acute viral infection in humans involving the respiratory tract. It is marked by inflammation of the NASAL MUCOSA; the PHARYNX; and conjunctiva, and by headache and severe, often generalized, myalgia.",
    "code": {
      "@type": "MedicalCode",
      "codeValue": "D007251",
      "codingSystem": "MeSH"
    },
    "mainEntityOfPage": {
      "@id": "#Discussion",
    }
  }
}
            

Hypermedia controls

A Scholarly Article (or any resource part of a scholarly graph) can be made actionable with the addition of hypermedia controls provided through schema.org actions. Readers not familiar with schema.org Actions should refer to the actions overview document for a quick introduction.

{
  "@context": "http://schema.org",
  "@id": "http://example.com/article",
  "@type": "ScholarlyArticle",
  "potentialAction": {
    "@type": "ReviewAction",
    "agent-input": {
      "@type": "PropertyValueSpecification",
      "valueRequired": true
    },
    "resultReview-input": {
      "@type": "PropertyValueSpecification",
      "valueRequired": true
    },
    "target": {
      "@type": "EntryPoint",
      "httpMethod": "PUT",
      "urlTemplate": "http://example.com/review"
    }
  }
}