citeproc-js

CSL-m Specification Supplement

citationstyles.org

CitationStylist.org

Frank Bennett

November 23, 2013


This supplement is a companion to the CSL 1.0.1 Specification. It is aimed at style authors, and documents differences between official CSL and the CSL-m schema recognised by Multilingual Zotero.

The changes are of two types:


Table of Contents


Item Types

classic (extension)

Use the classic type for sources commonly cited within a field. Cites of this type do not appear in the bibliography, and can be completely reformatted to a compact, style-specific form using the Classic abbreviation list in the Abbreviation Filter.

When a short form is supplied for a Classic item, the title variable is suppressed, and the short form entirely replaces the author variable. When a volume number or other details are included, these can be rendered on either side of the composite abbreviated form, but not of course within it.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<choose>
  <if type="classic">
    <group delimiter=" ">
      <text variable="volume"/>
      <group delimiter=", ">
        <names variable="author"/>
        <text variable="title"/>
      </group>
  </if>
</choose>

gazette (extension)

Use the gazette type for instruments published through an official gazette. Typical use cases would be cites to amending acts, to the initial version of legislation, or to orders and other instruments that are not available from other official sources. For consolidated acts or codified statutes or regulations, use the legislation (MLZ Statute) or regulation (MLZ Regulation) types instead.

1
2
3
4
5
<choose>
  <if type="gazette">
     <text macro="gazette-mac"/>
  </if>
</choose>

The format of gazette citations may vary among jurisdictions. Test the jurisdiction variable (see below) to discriminate between citation forms.

hearing (extension)

The hearing type is primarily intended for transcripts of official hearings by government committees and the like (other documents produced by a committee should be cast as the report type instead). The body conducting a hearing is set in the authority variable (Legis. Body in MLZ).

1
2
3
4
5
<choose>
  <if type="hearing">
     <text macro="hearing-mac"/>
  </if>
</choose>

regulation (extension)

Use the regulation type for administrative orders at all levels of government.

1
2
3
4
5
<choose>
  <if type="regulation">
     <text macro="hearing-mac"/>
  </if>
</choose>

video (extension)

The video type is appropriate for video works that are not disseminated through an access-restricted distribution channel. For example, content hosted on YouTube should be set to video, while a DVD release of "The Wizard of Oz" should be set to motion_picture.

1
2
3
4
5
<choose>
  <if type="regulation">
     <text macro="hearing-mac"/>
  </if>
</choose>

Elements

cs:conditions (extension)

Condition statements in official CSL take a single "match" attribute, which determines how the tests will be combined. The match attribute value (all, any, none) applies to all tests within the statement: grouping of tests with separate match values is not possible. To simplify the coding of complex styles, CSL-m introduces an optional alternative syntax for condition statements.

The alternative syntax may be applied to cs:if or cs:else-if elements (the "parent node" in this description). The parent node must have no attributes, and a single cs:conditions node as its first child element. The cs:conditions node must have one or more cs:condition children. The cs:condition children each define a conditional statement with attributes specified in the CSL 1.0.1 schema and in this Supplement. The cs:condition statements are joined according to a mandatory "match" attribute on cs:conditions.

Note that CSL-m adds a "nand" match value (true if at least one of the tests or condition statements to which it applies returns false), in addition to "all", "any", and "none".

1
2
3
4
5
6
7
8
9
<choose>
  <if>
    <conditions match="any">
      <condition type="chapter"/>
      <condition variable="container-title collection-title" match="nand"/>
    </conditions>
    <text macro="some-chapter-mac"/>
  </if>
</choose>

cs:institution (extension)

Institutional names are fundamentally different in structure from personal names. CSL provides quite robust support for the presentation and sorting of personal names, but in CSL 1.0.1, institutional names have just one fixed form, and are otherwise treated the same as personal names in a list of creators.

Some publishing environments require greater flexibility. Institution names can consist of multiple subunits. Individuals may be credited together with the institution to which they belong. Unaffiliated personal authors may be cited together with an institution or with individuals affiliated with it. Some examples:

  1. Research & Pub. Policy Dep't, Nat'l Urban League
  2. United Nations - ECLAC
  3. ECLAC (Economic Commission for Latin America and the Carribean)
  4. Canadian Conservation Institute (CCI)
  5. Nolan J. Malone and others, U.S. Bureau of the Census
  6. World Trade Organization and World Health Organization
  7. Smith with Jones, Bureau of Sloth, Ministry of Fear
  8. Doe et al. with Roe et al., Ministry of Fear & Noakes, Ministry of Destruction

Examples 3 and 4 render both the full form and the acronym of a single institution name, with arbitrary ordering of the two name parts. Example 1 begins with the smallest subunit in a list of related institutions, and example 2 does the opposite. Examples 1 and 2 are pure organizations, while example 5 is a mix of personal and institutional names. Examples 1, 2, 3 and 4 would be entered as literal strings currently, which has obvious drawbacks. Example 5 would require that the authorship information be spread across two variables, although all parties listed are equally authors of the resource. Example 6 can be produced in CSL 0.8, but examples 7 and 8 cannot.

The MLZ extensions to CSL 1.0.1 provide a cs:institution element, which can be used to produce any of the above forms, without interfering with the formatting of ordinary personal names. The extension is always enabled in citeproc-js, but the application calling citeproc-js (i.e. Zotero) must specially flag institutional names for it to take effect. MLZ provides this flag, while the official Zotero client does not. For this reason, this extension only works with the multilingual client at present.

Entry conventions

In multilingual Zotero, names entered in two-field mode are personal, and those entered in single-field mode are treated as organizations. Names should be entered in the order in which they should appear in citations, with one (extremely rare) exception: when an unaffiliated author is included in a list of names that includes one or more institutions, the name of the unaffiliated author(s) should come after that of the last institution in the list.

Subunits of an organizational name should be separated with a field separator character |.

Affiliated authors

Single or multiple personal Names that are co-authors with an organization would be entered above the relevant organization name.

affiliated-authors.png

In a very simple style, the sample above might be rendered as: Clarke, Ministry of Fear and Smith & Brown, Large Corporation.

Unaffiliated authors

Authors with no affiliation would be listed after any organizational names:

unaffiliated-authors.png

In a very simple style, the sample above might be rendered as: Doe & Roe with Clarke, Ministry of Fear and Smith & Brown, Large Corporation (note the reverse ordering in this case, with the names at the end placed at the front of the rendered list of names).

The structure of mixed personal and organizational names can thus be expressed in the current Zotero UI. We now turn to the extended CSL syntax used to control the appearance of such names.

CSL Extension

Element: cs:institution

A cs:institution element can be placed immediately after the cs:name element to control the formatting of organization names.

Attributes: delimiter and and

The value of the delimiter attribute on cs:institution is used in the following locations:

  • between organization names;
  • between the subunits of an organization;
  • between affiliated authors and their institution.

The and attribute on cs:institution, if any, is used for the final join between two or more author/organization units.

A simple use of cs:institution might read as follows:

1
2
3
4
<names variable="author">
  <name and="symbol" initialize-with=". "/>
  <institution and="text" delimiter=", ">
</names>

With this CSL, all of the delimiters in the following string would be drawn from attributes on cs:institution: R. Smith, Small Committee, Large Corporation, G. Brown, Busy Group, Active Laboratory, and S. Noakes, Powerful Ministry.

Attributes: use-first, substitute-use-first and use-last

To control the omission of names from the middle of the list of organizational subunits, either of use-first or substitute-use-first may be used to pick names from the front of the list. The use-last attribute picks names from the end. The substitute-use-first attribute includes the leading (smallest) subunit if and only if no personal names are associated with the organization.

The following CSL code would format both example 1 and example 5 from the list of samples at the top of this section:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<names variable="author" delimiter=", ">
    <name
      and="symbol"
      delimiter-precedes-last="never"
      et-al-min="3"
      et-al-use-first="1"/>
    <et-al term="and others"/>
    <institution
      delimiter=", "
      substitute-use-first="1"
      use-last="1"/>
</names>
Attribute: reverse-order

By convention, organizational names are rendered in "big endian" order, from the smallest to the largest organizational unit. To provide for cases such as example 2 in the list of samples, a reverse-order attribute can be applied on cs:institution:

1
2
3
4
5
6
7
8
<names variable="author" delimiter=", ">
    <name/>
    <institution
      delimiter=" - "
      use-first="1"
      use-last="1"
      reverse-order="true"/>
</names>
Attribute: institution-parts

The components of organization names are normally rendered in their long form only. When the Zotero Abbreviations Gadget is used with Zotero, abbreviated forms for these names may be available to the processor.

To use the short form, or combinations of the long and short form, an institution-parts attribute is available on cs:institution. The attribute accepts values of long, short, short-long and long-short. This attribute would be used to produce examples 3 and 4 in the list of samples, with values of short-long and long-short respectively. A value of short behaves in the same way as form="short" in other contexts in CSL, using the short form if it is available, and falling back to the long form otherwise.

Element: cs:institution-part

One or more cs:institution-part elements can be used to control the formatting of long and short forms of organization names. Like cs:name-part, these elements are unordered, and affect only the formatting of the target name element, specified (as on cs:name-part) with a required name attribute.

Attribute: if-short

In example 3, the parentheses should be included only if a short form of the institution name is available. The if-short attribute, available on cs:institution-part only when applied to the long form of an organization name, makes the formatting in the element conditional on the availability of a short form of the name. The following CSL would render example 3 in the list of samples:

1
2
3
4
5
6
<names variable="author">
    <name/>
    <institution institution-parts="short-long">
        <institution-part name="long" if-short="true" prefix=" (" suffix=")"/>
    </institution>
</names>

Element: cs:with

In rendered output, unaffiliated personal names are joined to a following organizational name using an implicit localizable term with. Styling of this term is permitted through an optional cs:with element, placed immediately above cs:institution:

1
2
3
4
5
6
7
<names variable="author">
    <name/>
    <with font-style="italic" prefix=" " suffix=" "/>
    <institution institution-parts="short-long">
        <institution-part name="long" if-short="true" prefix=" (" suffix=")"/>
    </institution>
</names>

Simple style example

The simple style used in the illustrated examples in the Entry conventions section above would look like this in CSL:

1
2
3
4
<names variable="author">
    <name form="short" and="symbol" delimiter=", "/>
    <institution use-last="1" and="text" delimiter=", "/>
</names>

cs:layout (extension)

In publishing outside of the English language domain, citation of foreign material in the style of the originating language is the norm. For example, a Japanese publication might include the following references in a single work:

  • D. H. McQueen, "Patents and Swedish University Spin-off Companies: Patent Ownership and Economic Health", Patent World, March 1996, pp.22–27.
  • 北川善太郎「著作権法100年記念講演会/著作権制度の未来像」コピーマート No.465, 7頁 (2000年)。

To meet such requirements, the MLZ extensions to CSL permit multiple cs:layout elements within cs:citation and cs:bibliography. Each cs:layout element but the last must include a locale attribute specifying one or more recognized CSL locales, and the final element must not carry a locale attribute. The locale applied to an item is determined by matching it against the locale set in the language variable of the item (this value is passed by Zotero). An example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<citation>
  <layout locale="en es de">
      <text macro="layout-citation-roman"/>
  </layout>
  <layout locale="ru">
      <text macro="layout-citation-cyrillic"/>
  </layout>
  <layout>
      <text macro="layout-citation-ja"/>
  </layout>
</citation>

In the example above, an item with en, es or de (or de-AT) set in the language variable will be render by the layout-citation-roman macro, with locale terms set to the appropriate language.

Variables

authority (modification)

In CSL-m, authority is handled as an institutional creator, not as an ordinary variable. It is rendered with a cs:names element.

1
2
3
4
5
6
<macro name="std-authority-child">
  <names variable="authority">
    <name suppress-min="0"/>
    <institution institution-parts="short" use-first="1"/>
  </names>
</macro>

The use of suppress-min="0" in this example is documented below under suppress-min (extension).

available-date (extension)

The CSL-m available-date variable is appropriate for the date on which a treaty was made available for signing.

1
2
3
4
<group delimiter=" ">
  <text value="opened for signature" font-style="italic"/>
  <date date-parts="year-month-day" form="text" variable="available-date"/>
</group>

dummy (extension)

The dummy name variable is always empty. Use it to force all name variables called through a cs:names node to render through cs:substitute, and so suppress whichever is chosen for rendering to be suppressed through the remainder of the current cite.

1
2
3
4
5
6
7
8
<names variable="dummy">
  <name/>
  <label/>
  <substitute>
    <names variable="author"/>
    <names variable="editor"/>
  </substitute>
</names>

hereinafter (extension)

The hereinafter variable is a backreference form specific to a particular item and style. In MLZ, it can be set only through the Abbreviation Filter. The role of the variable in a given cite (i.e. whether it provides an alternative title, an acronym or a more complete formatted citation) depends on the the style and context.

1
2
3
4
5
6
7
8
<choose>
  <if match="all" type="bill gazette legislation" variable="hereinafter">
    <text variable="hereinafter"/>
  </if>
  <else>
    <text variable="title" form="short"/>
  </else>
</choose>

The Abbreviation Filter will offer an entry in the hereinafter list for every item cited in the document. It is not necessary to use form="short" on the cs:text node that renders the variable.

locator (modification)

In CSL-m, locator is a numeric variable. Validation requires that it be rendered with cs:number.

1
<number variable="locator"/>

The locator variable will render exactly once in a citation; subsequent attempts will render nothing. As with variables suppressed via cs:substitute, the test for variable="locator" will continue to return true after the variable is suppressed from further output.

locator-date and locator-extra (extension)

The variable "locator-date" is parsed out from the user-supplied locator, using the following syntax:

1
123|2010-12-01

In this example, "123" is the value of the locator variable (a page or other pinpoint string), the | character marks the end of the pinpoint, and the ten-character string immediately following is a full date. If supplied, dates must be given as shown above, zero-padded, in year-month-day order, and with no space between the date and the | character. Non-conforming strings following the | marker will be treated as a locator-extra variable.

The locator-extra variable consists of a string that is not a date, following the locator-date string (if any) as described above. If supplied without a locator-date, the locator-extra string must be preceded by a | field separator character. This variable can be used for version descriptions associated with some looseleaf services.

These extensions are useful with looseleaf services, because the dates of the content in these services varies depending on the page cited and the time at which the resource was referenced. These extensions permit a single item in the calling application's database to represent the volume on the library shelf, the page date being optionally supplied by the user when citing into a document.

page and page-first (modification)

The page and page-first variables are numeric in CSL-m. The validator requires that they be rendered with cs:number.

1
<number variable="page"/>

publication-date (extension)

CSL-m adds a publication-date variable to the language schema. It is available on the gazette, legal_case, legislation, patent and regulation types, and provides the date on which the instrument was published in the given reporter. On the patent type, it represents the date on which the patent was published for opposition (applicable only in certain jurisdictions).

1
<date date-parts="year-month-day" form="text" variable="publication-date"/>

publication-number (extension)

The publication-number variable is available on the patent type, and provides the number assigned to a patent published for opposition. It is a numeric variable, and validation requires that it be rendered with cs:number.

1
<number variable="publication-number"/>

supplement (extension)

The supplement variable and its associated locale term are useful for secondary sources that are regularly updated between fresh editions. Such fine-grained updates are found in secondary legal publications. Although a supplement may be identified by number or by name, supplement is a numeric variable, and validation requires that it be rendered with cs:number.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<choose>
  <if is-numeric="supplement">
    <group delimiter=" ">
      <label variable="supplement"/>
      <number variable="supplement"/>
    </group>
  </if>
  <else>
    <number variable="supplement"/>
  </else>
</choose>

volume-title (extension)

The volume-title variable is available on items of the book and chapter type. Use it to identify the name of a volume within a larger work known by an umbrella title (which may in turn be a part of a publisher's series, described by collection-title).

1
<text variable="volume-title"/>

Attributes

default-locale-sort (extension)

Use the default-locale-sort attribute on the cs:style node to specify the language collation to govern sorting behaviour. The sort locale has no effect on the language of standard terms and labels.

1
2
3
4
<style xmlns="http://purl.org/net/xbiblio/csl"
       class="note" version="1.1mlz1"
       default-locale="en-US"
       default-locale-sort="zh-TW">

If this attribute is not set, the sort locale is aligned with the default locale of the style or processor instance.

form="imperial" (modification)

CSL-m allows conversion of ordinary Gregorian dates to the Japanese form often used in legal citations and other government records. The conversion is only valid for dates after 1873. Prior dates on the traditional lunar calendar are not supported, and should be written as literal strings in the input.

1
<date variable="issued" form="imperial" date-parts="year-month-day"/>

form="short" (modification)

In CSL 1.0.1, rendering the title variable with the attribute form="short" produces the same result with any item type: if the title-short variable has a value, that it used; otherwise the title variable is rendered as a fallback.

In CSL-m, on the legal_case type only, the form="short" attribute does not attempt to render title-short, but instead renders the title variable, transformed by the Abbreviation Filter if an entry for it exists in the list there. This permits the application of style-specific abbreviation rules, as required by law-specific style guides such as The Bluebook: A Uniform System of Citation.

1
<text variable="title" form="short"/>

is-parallel (extension)

Set on a cs:group node, the is-parallel attribute includes or suppresses the content of the group node depending on whether it is rendered in a trailing parallel cite. Four values are recognised on the attribute:

false
Renders when the cite is not one of a series of parallel cites.
true
Renders when the cite is one of several cites in a parallel series.
master
Renders when the cite is one of several in a parallel series, and is the first cite in the series.
servant
Renders when the cite is one of several in a parallel series, and is not the first in the series.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<group delimiter=" ">
  <text font-style="italic" value="supra"/>
  <text value="note"/>
  <text variable="first-reference-note-number"/>
</group>
<group delimiter=" " is-parallel="false">
  <text value="at"/>
  <number variable="page-first"/>
</group>
<group delimiter=" " is-parallel="true">
  <number variable="volume"/>
  <text variable="container-title"/>
  <number variable="page-first"/>
</group>

label-form (extension)

The label-form attribute can be used on cs:number and on cs:text with the macro attribute. It accepts the same arguments as the form attribute for localised terms: long, verb, short, verb-short and symbol. Its effect is to override the form attribute applicable to terms called via the parent cs:text or cs:number node. This can be useful where macros are copied across styles that require different label forms.

1
<text macro="locator-mac" label-form="symbol"/>

leading-noise-words (extension)

When set on a cs:style-options node in a locale file or in a style, the leading-noise-words attribute takes a comma-delimited list of words as its argument.

When a list is set, the same attribute on a cs:text node with variable="title" takes an argument of ``demote or drop. With the demote attribute, noise words at the start of the field are rendered after the remainder of the title field, delimited by a comma. With the drop attribute the leading noise words are simply removed.

1
<style-options leading-noise-words="a,an,the"/>

and

1
<text variable="title" leading-noise-words="demote"/>

match="nand" (extension)

With the nand argument to the match attribute, a node test is true if at least one of the tests it invokes is false.

1
2
3
4
5
<choose>
  <if variable="volume issue" match="nand">
    <text macro="volume-issue-mac"/>
  </if>
</choose>

name-as-reverse-order (extension)

This is the counterpart of name-as-sort-order, available on cs:style-options only. Its operation is identical to its counterpart, but has the opposite effect of forcing reverse-order rendering of all names bearing the specified language tags. The name-as-sort-order attribute is described immediately below.

name-as-sort-order (extension)

A name-as-sort-order attribute is available on the cs:style-options locale element, taking a list of space-delimited country codes as its argument. Country codes in the argument should be limited to a single element (i.e. the language only, without a country or other specifier): other elements will be ignored.

When the first element of the field language (either explictly set, or defaulting to the item language field value, if any) matches one of the specified locales, the name is forced to "sort order", regardless of its character set.

1
<style-options name-as-sort-order="kr ja zh"/>

The example above will force names tagged as Korean, Japanese, and Chinese to sort order (i.e. family name first). This attribute does not interfere with short-form rendering or abbreviation (see the next heading below for that setting).

name-never-short (extension)

The name-never-short attribute on the cs:style-options locale element takes a list of space-delimited country codes as its argument. Country codes in the argument should be limited to a single element (i.e. the language only, without a country or other specifier): other elements will be ignored.

When the first element of the field language (either explictly set, or defaulting to the item language field value, if any) matches one of the specified locales, the effect of form="short" is suppressed when rendering the name concerned.

1
<style-options name-never-short="hu kr ja my vi zh"/>

The example above suppresses form="short" on names tagged as Hungarian, Korean, Japanese, Myanmar, Vietnamese, or Chinese.

oops (extension)

This attribute is deprecated. Use is-parallel instead.

prefix and suffix (modification)

Ordinary affixes in CSL-m are subject to a restriction: a prefix attribute may not begin with a space, and a suffix attribute may not end with a space. Affixes on cs:label within a cs:names element, and affixes within the scope of a cs:date element are not subject to this constraint.

The purpose of this requirement is to assure that styles are incapable of rendering cites with stray punctuation or multiple spaces. Where spaces are required between elements, they should be applied using a delimiter attribute value on a cs:group element.

1
2
3
4
<group delimiter=", ">
  <number variable="volume"/>
  <text variable="container-title"/>
</group>

skip-words (extension)

The processor carries a list of prepositions and other terms that will not be capitalised when rendering a field with text-case="title". Within a locale, the skip-words attribute on cs:style-options can be used to replace this list of terms with another. The attribute value should be a comma-delimited list of words or phrases.

1
<style-options skip-list="a,an,the,or,and,over,under"/>

subgroup-delimiter, subgroup-delimiter-precedes-last, and (extension)

The subgroup-delimiter attribute is a field-parsing hack coded into the citeproc-js processor, enabled when the processor is run in CSL-m mode. In a group containing only cs:text elements rendering the publisher and publisher-place variables, the processor will split the content of both fields on a semicolon. If the length of the resulting list objects is equal, each publisher/publisher-place pair will be joined with the delimiter string set on the enclosing cs:group element. The composed pairs are then joined using the subgroup-delimiter value.

The subgroup-delimiter-precedes-last attribute controls the use of the delimiter between the last and the penultimate pair in the same manner as delimiter-precedes-last on a cs:name element. The and attribute with an argument of text or symbol may be used on the cs:group element to join the final item with the specified term.

1
2
3
4
5
<group delimiter=" " subgroup-delimiter=", "
       subgroup-delimiter-precedes-last="always">
  <text variable="publisher"/>
  <text variable="publisher-place"/>
</group>

or

1
2
3
4
5
6
<group delimiter=" " subgroup-delimiter=", "
       subgroup-delimiter-precedes-last="never"
       and="symbol">
  <text variable="publisher"/>
  <text variable="publisher-place"/>
</group>

suppress-min (extension)

In the MLZ extended schema, names can be suppressed in two ways. First, using suppress-min and suppress-max with values of 1 or above, names rendered via a cs:name element can be suppressed entirely when the number of individual names is at or below a minimum, or at or above a maximum.

Second, with a value of 0, suppress-min can be used on a cs:name or cs:institution element to suppress only names of that type. See the description of suppress-min below for an example of how that works and why it might sometimes be useful.

An example of suppress-min with a value of 4:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
<locale xml:lang="en">
  <terms>
    <term name="and others"></term>
  </terms>
</locale>
<macro name="first-position-author">
  <names variable="author">
    <name et-al-min="2" et-al-use-first="1"
          suppress-min="4"
          name-as-sort-order="first"/>
    <et-al term="and others"/>
  </names>
</macro>
<macro name="second-position-author">
  <names variable="author">
    <name et-al-min="4" et-al-use-first="1" delimiter=", "/>
  </names>
</macro>
<citation>
  <layout>
    <group delimiter=" / ">
      <group delimiter=" ">
        <text macro="first-position-author"/>
        <text variable="title"/>
      </group>
      <text macro="second-position-author"/>
    </group>
  </layout>
</citation>

In the above example, an item with two authors will render as follows:

Stamou, A.I. Title of the Article / A.I. Stamou, I. Katsiris

An item with four authors, however, will render as follows:

Title of the Article / A.I. Stamou et al.

suppress-min with a value of 0

When set to zero, the suppress-min attribute is specific to the cs:name or cs:institution node only (for clarity, the attribute with this value should always be set directly on the affected node, rather than relying on inheritance). The effect of the setting is to suppress all institution or all personal names, leaving a list of the remaining names in place. This can be useful where personal and institutional authors must be listed in separate places in a citation—one example of such formatting being Rule 21.7.3 of the Bluebook 18th ed. (applicable to U.N. reports) which provides the following guidance and example:

If a personal author is given along with the institutional author, the author [sic] should be included in a parenthetical at the end of the citation.

U.N. Econ. & Soc. Council [ECOSOC], Sub-Comm. on Prevention of Discrimination & Prot. of Minorities, Working Group on Minorities, Working Paper: Universal and Regional Mechanisms for Minority Protection, ¶ 17, U.N. Doc. E/CN.4/Sub.2/AC.5/1999/WP.6 (May 5, 1999) (prepared by Vladimir Kartashkin).

suppress-max (extension)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
<macro name="authors">
  <group delimiter=" ">
    <names variable="author">
      <name name-as-sort-order="all"
            et-al-min="11" et-al-use-first="3"
            and="text"/>
    </names>
    <group delimiter=" " prefix="(" suffix=")">
      <names variable="author">
        <name suppress-max="10" form="count"/>
      </names>
      <text value="co-authors"/>
    </group>
  </group>
</macro>
<citation>
  <layout>
    <text macro="authors"/>
  </layout>
</citation>

In this example, an item with four authors would render as follows:

Doe, J, Roe, J, Noakes, R, and Snoakes, H

An item with eleven authors, on the other hand, would render like this:

Doe, J, Roe, J, Noakes, R, et al. (11 co-authors)

text-case (extension)

CSL-m adds a normal argument to the possible values of text-case. This is mainly useful when rendering a cs:number element in the scope of an element that applies a text-case transform, to prevent text content in the rendered variable from being affected by the transform.

(The need for this attribute value is open to question.)

1
<number variable="number" text-case="normal"/>

year-range-format (extension)

CSL-m offers a year-range-format attribute on cs:style, as a complement to page-range-format. It takes the same arguments: expanded, minimal, minimal-two, and chicago. When used, this attribute specifies a collapsing format for year ranges separate from that applied to page ranges.

1
2
3
<style xmlns="http://purl.org/net/xbiblio/csl" class="note" default-locale="en-GB"
       page-range-format="chicago"  year-range-format="expanded"
       version="1.1mlz1">

Conditions

context (extension)

The context test attribute takes exactly one of the arguments bibliography or citation. It does exactly what its name and value suggest, returning true when the condition is executed in the relevant context. This test is useful where complex logic is needed to compose a particular element, which changes only slightly in the other context.

1
2
3
4
5
6
7
8
<choose>
  <if context="citation">
    <text variable="title" font-variant="small-caps"/>
  </if>
  <else>
    <text variable="title" font-variant="small-caps" form="short"/>
  </else>
</choose>

genre (extension)

The genre test attribute takes one of five arguments: email, instant-message, podcast, radio-broadcast, or television-broadcast. These correspond to strings automatically inserted into the genre variable by MLZ (where no value is set manually by the user) on the Email, Instant Message, Podcast, Radio Broadcast and Television Broadcast types respectively.

This is obviously a hack, and mimicks the effect of having five separate types for these items in CSL, as opposed to two (i.e. personal_communication and broadcast).

1
2
3
4
5
<choose>
  <if genre="podcast">
    <text macro="podcast-mac"/>
  </if>
</choose>

has-day (extension)

The has-day condition attribute tests whether the date variable given as argument has a value that includes a day.

1
2
3
4
5
6
7
8
<choose>
  <if has-day="issued">
    <date variable="issued">
      <date-part name="month" form="text"/>
      <date-part name="day" form="numeric" prefix=" "/>
    </date>
  </if>
</choose>

has-to-month-or-season (extension)

The has-to-month-or-season condition attribute tests whether the date variable given as argument has a month or season (and no day).

1
2
3
4
5
6
7
<choose>
  <if has-to-month-or-season="issued">
    <date variable="issued">
      <date-part name="month"/>
    </date>
  </if>
</choose>

has-year-only (extension)

The has-year-only condition attribute test whether the date variable given as argument has only a year (and no day, month or season).

1
2
3
4
5
6
7
<choose>
  <if has-year-only="issued">
    <date variable="issued"
          date-parts="year" form="text"
          prefix="[" suffix="]"/>
  </if>
</choose>

jurisdiction (extension)

When citing primary legal resources, the form of citation is often fixed, for ease of reference, by the issuing jurisdiction— "jurisdiction" referring in this case to international rule-making bodies as well as national governments. CSL 1.0.1 provides a jurisdiction variable, but it cannot be used because Zotero does not currently have a corresponding field.

The particular requirement for this variable is that it be tested in a cs:if and cs:else-if condition, so that citations can be varied according to the issuing jurisdiction. Testing of field content is contrary to the design of CSL, so the approach of the MLZ extended CSL schema is strictly circumscribed to address this particular need, without opening a door to uncontrolled general testing of field content.

The solution is in two parts, described below.

Jurisdiction constraint list

The CSL schema has been extended in accordance with the proposed URN:LEX standard for a uniform resource namespace for sources of law. This standard provides a concept of "jurisdiction" that suits the requirements of legal citation, including both national jurisdictions and international rule-making bodies. Following URN:LEX, the schema has been extended with an explicit list of the national jurisdictions of the world, plus selected rule-making international organizations designated by their permanent domain name. The former are drawn from ISO 3166 Alpha-2. The latter do not yet have official sanction, as URN:LEX is still at the proposal stage, but the list in the schema extension is conservative, including only a few of the most stable (and widely cited) organizations.

Controlled list

The list of acceptable jurisdictions codes is coupled with an extension of the cs:if and cs:else-if elements, providing a jurisdiction test attribute. In styles, the value set on the attribute must be present in the list of acceptable jurisdiction values. A style that uses other values is invalid.

When the jurisdiction test attribute is used, its value is compared with the value of the jurisdiction variable on the item being processed. If the values match, the test returns true, otherwise false. Matching is done at the granularity of the argument provided in the test.

1
2
3
4
5
<choose>
  <if jurisdiction="us">
    <text macro="us-mac"/>
  </if>
</choose>

The test above will be true for items with a jurisdiction value of jp or de, and false for values of us, us;federal;oh or us;ny.

locale (extension)

In CSL-m, alternative cs:layout nodes can be set by giving each a separate locale attribute. See the description of cs:layout (extension) above for further details.

page (extension)

In CSL-m, the page variable can be tested in the same way as locator. The test evaluates the label value, if any, set at the start of the field using a recognized locator abbreviation. See Locator Terms below for a list of recognised abbreviations and their corresponding CSL-m label values.

1
2
3
4
5
<choose>
  <if page="page" match="none">
    <label form="symbol" variable="page"/>
  </if>
</choose>

The cs:label element in this example will render the localised term for the label set in the page field (e.g. "para. 3" will render in English as "¶ 3").

subjurisdictions (extension)

The CSL-m jurisdiction variable contains a juridiction specifier divided into subfields, with a colon as the subfield delimiter.

The subjurisdictions test attribute takes an integer as argument. It returns true if the jurisdiction field on the item contains a value with at least the specified number of subjurisdictions.

1
2
3
4
5
<choose>
  <if subjurisdictions="2">
    <text variable="jurisdiction" form="short"/>
  </if>
</choose>

The example above will render the value of the jurisdiction field, "abbreviated" according the any mapping set for the style in the Abbreviation Filter. In the example, a value of us or us;ca will return false, while a value of us;federal;ny will return true.

Terms

unpublished (extension)

The unpublished localised term is available for use by CSL-m styles.

1
<text term="unpublished"/>

Locator Terms

Label Abbreviation Label Abbreviation
article art. paragraph para.
book bk. subparagraph subpara.
chapter ch. part pt.
subchapter subch. rule r.
column col. section sec.
figure fig. subsection subsec.
folio fol. sub-verbo sv.
line l. schedule sch.
note n. title tit.
issue no. verse vrs.
opus op. volume vol.
page p. or pp.    

In addition to the extended terms (article, rule, and title), CSL-m styles automatically set the special alternative terms Chapter and Section when rendering the corresponding terms in the context of the first item in a parallel reference.