zuphilip / schema

Citation Style Language schema

Schemas describing the Citation Style Language

This is the official repository for schemas describing the Citation Style Language (CSL). Current schemas include:

• CSL schema - describes CSL style and locale XML files
• CSL-JSON schema - describes a commonly used JSON data model for storing CSL processor input (such as bibliographic metadata).

For more information about CSL, visit https://citationstyles.org.

CSL Schema

The CSL schema is written in the compact syntax of RELAX NG, and currently consists of the following files:

• csl.rnc
• csl-categories.rnc
• csl-terms.rnc
• csl-types.rnc
• csl-variables.rnc

CSL style and locale files should be validated against csl.rnc, which incorporates the content of the other files.

The CSL schema contains several Schematron rules to make sure all macros called in a CSL style are actually defined. Since the popular Jing XML validator currently ignores embedded Schematron rules, we also provide the csl.sch Schematron schema, which contains the Schematron rules extracted from the CSL schema. Jing users can use csl.sch to perform a secondary validation of CSL styles.

CSL-JSON Schema

The CSL-JSON schema is written in JSON Schema, and currently consists of the following files:

• csl-data.json
• csl-citation.json

To render citations and bibliographies, CSL processors not only require CSL style and locale files, but also bibliographic metadata. The citeproc-js CSL processor introduced a JSON format to store such metadata, and this format has since been adopted by various other software products. The format, also known as "citeproc-JSON", has been codified in the CSL-JSON Schema.

At this point the CSL-JSON schema is not yet fully normative, and care must be taken to ensure compatibility with other tools built around CSL-JSON.

Whereas csl-data.json describes how the metadata of bibliographic items can be stored, csl-citation.json incorporates csl-data.json and adds an additional layer of information to also describe the context in which bibliographic items are cited. This includes information such as the order in which items are cited, which items are cited together in a single citation, etc.

Mendeley CSL-JSON

Mendeley provided the following documentation on their use of CSL-JSON:

Support for the CSL Embedded Citation Object format is available in Mendeley Desktop 1.0 and later.

The CSL citation data object consists of:

• a required "schema" element of type "string", set to the URI of the schema
• a required "citationID" element of type "string" or "number", set to ???
• a "citationItems" element of type "array", containing "objects" with the data of the individual cites. The individual cite object are structured as:
  • a required "id" element of type "string" or "number", set to an unique cite ID
  • a "itemData" element of type "object", described in csl-data.json/#/items , containing the metadata of a single bibliographic item (this object is returned in citeproc-js by sys.retrieveItem() )
  • an "uris" element of type "array", which can contain any number of URIs (of type "string") to the bibliographic item
  • a "prefix" element of type "string"
  • a "suffix" element of type "string"
  • a "locator" element of type "string"
  • a "label" element of type "string", set to one of the CSL locator types (see https://docs.citationstyles.org/en/1.0.1/specification.html#locators)
  • a "suppress-author" element of type "string", "boolean" or "number"
  • a "author-only" element of type "string", "boolean" or "number"
• a "properties" element of type "object" containing:
  • a "noteIndex" element of type "number", set to the index of the footnote or endnote
• (Mendeley-specific) a "mendeley" element of type "object" containing:
  • a "previouslyFormattedCitation" element of type "string", set to the rendered output of the cite of the previous rendering round (this can be used to determine if the user manually altered the output)
  • a "manualFormatting" element of type "string", set to the user-customized output of the cite (this output will be used in favor of the generated output)

The method to embed metadata for citations and bibliographies typically varies between word processors. Currently Mendeley uses:

• For Word for Windows: in-text citations and bibliographies are represented by a field code of type wdFieldAddin or temporarily represented as a bookmark if exporting to OpenOffice.

• For OpenOffice: in-text citations are of type com.sun.star.text.ReferenceMark. Bibliographies are of type com.sun.star.text.TextSection or temporarily represented as a bookmark if exporting to Word.

An example of an embedded citation object from Mendeley:

{
    "schema": "https://resource.citationstyles.org/schema/latest/input/json/csl-citation.json",
    "citationID": "12rsus7rlj",
    "citationItems": [
        {
            "id": "ITEM-1",
            "itemData": {
                "id": "ITEM-1",
                "issued": {
                    "date-parts": [
                        [
                            "2007"
                        ]
                    ]
                },
                "title": "My paper",
                "type": "journal-article"
            },
            "locator": "21",
            "label": "page",
            "uris": [
                "http://www.mendeley.com/documents/?uuid=970e7ce0-8a21-482e-b7d6-e77794a2d37d",
                "http://www.zotero.org/uniqueDocumentId"
            ]
        }
    ],
    "mendeley": {
        "previouslyFormattedCitation": "(2007)",
        "manualFormatting": "2007b"
    },
    "properties": {
        "noteIndex": 1
    }
}

Licensing

This repository is released under the MIT license.