|
@@ -0,0 +1,147 @@
|
|
|
+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
|
|
|
+[CitationStyles.org](http://citationstyles.org/).
|
|
|
+
|
|
|
+# CSL Schema
|
|
|
+
|
|
|
+The CSL schema is written in the compact syntax of [RELAX
|
|
|
+NG](http://relaxng.org/), 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](http://www.schematron.com/)
|
|
|
+rules to make sure all macros called in a CSL style are actually defined.
|
|
|
+Since the popular [Jing](https://code.google.com/p/jing-trang/) 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](http://json-schema.org/),
|
|
|
+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](http://gsl-nagoya-u.net/http/pub/citeproc-doc.html#data-input)
|
|
|
+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
|
|
|
+ http://citationstyles.org/downloads/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://github.com/citation-style-language/schema/raw/master/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
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|