Code Monkey home page Code Monkey logo

schema's Introduction

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. For general quesions and discussions have a look at the CSL-forum.

CSL Schema

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

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:

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. This same schema can be used to validate YAML.

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.

Licensing

This repository is released under the MIT license.

schema's People

Contributors

abdealikhurrum avatar bdarcus avatar bwiernik avatar denismaier avatar dhimmel avatar dwhieb avatar hoijui avatar klortho avatar lukesmurray avatar nichtich avatar rmzelle avatar robertknight avatar thewilkybarkid avatar zuphilip avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

schema's Issues

Locale: add some metadata

As discussed in the thread titled "locale specification" from 2010-07-30:

http://sourceforge.net/mailarchive/forum.php?thread_name=AANLkTindVv9AzPaUvtH2KWbv3U9W9-Dc1FWOOJoDw%3Dq2%40mail.gmail.com&forum_name=xbiblio-devel

It could be nice to add some more information to the locale files. The information that I propose after the comments on that thread is:

<info>
  <last-translator>
    <name>The Name1</name>
    <email>The email1</email>
    <uri>Some URI1</uri>
  </last-translator>
  <translator>
    <name>The Name2</name>
    <email>The email2</email>
    <uri>Some URI2</uri>
  </translator>
  <translator>
    <name>The Name3</name>
    <email>The email3</email>
    <uri>Some URI3</uri>
  </translator>
  <updated>timestamp</updated>
</info>

So:
a) Each relevant translator adds the name there.
b) The last-translator has a specific entry (usually it's convenient to contact him if there are some bugs, will have access to the repository, etc.).
c) Updated element to know when was last updated.

(I'll prepare a patch to the documentation soon)


Support multiple items per citation-number (for chemistry journals)

We need to be able to support compound reference styles with output like:

(21) (a) Childs, A. F.; Goldsworthy, L. J.; Harding, G. F.; King, F. E.; 
Nineham, A. W.; Norris, W. L.; Plant, S. G. P.; Selton, B.; Tompsett, 
A. L. L. J. Chem. Soc. 1948, 2174–2177. (b) Chase, B. H.; Downes, 
A. M. J. Chem. Soc. 1953, 3874–3877.

My understanding is this conceptually like a footnote citation, where the individual references simply get labeled based on their position in the list.

If I understand that right, then all we need to be able to get the index number for the position within the citation, and then format that using cs:number. Does that mean we need to add something like reference-in-citation-index to the cs-numbers pattern?

Aside: we have first-reference-note-number as a simple variable (not on number). Two things:

  1. well, should it have been under number?
  2. we probably need to establish consistent naming of three things:
    • the full citation as a whole
    • the individual references within the full citation
    • the item in the bibliography

delimiter-precedes-et-al

As discussed on the xbiblio mailing list[*], I'd like to propose a new backwards-compatible hierarchical name attribute, delimiter-precedes-et-al, that would function similarly to delimiter-precedes-last.

By default, the delimiter between the et-al term and the preceding name(s) is contextual (a space for a single preceding name, the name delimiter for multiple names). With the delimiter-precedes-et-al attribute (default of "contextual"), it would be possible to force (value of "always") or prevent (value of "never") the use of the name delimiter for the two cases.

[*] http://sourceforge.net/mailarchive/message.php?msg_id=A97B942C-DF3C-4AB7-81E1-4F91DB7C6568%40simonster.com

Modified spec description:
http://bitbucket.org/bdarcus/csl-docs/changeset/7a2bc6389c2d


proposal: add variables "scale" and "dimensions"

As suggested at http://sourceforge.net/mailarchive/message.php?msg_name=fbb7c5df0909211630o1848677bi85c4dc13df012ee2%40mail.gmail.com

"scale" is a Zotero field for the Zotero Map item type, but doesn't have a matching CSL variable. "dimensions" is probably also a useful addition (I prefer "dimensions" over "format", as the latter might be confused with the "medium" variable).


new creator variable: nobody?

In some styles, the position of a variable within the citation varies across item types (or according the the availability of other data). If we had a reserved creator variable "nobody" in CSL that always returned nil, cs:substitute could be used to render the target variable when appropriate, forcing its suppression later in the citation.

I'm not sure whether I like this idea, actually, since it would involve abusing cs:names as a vehicle for rendering non-name variables, simply to take advantage of the suppression facility of cs:substitute. But having the ability to render a variable once and only once would make it possible to avoid the use of (fragile) parallel condition statements that would otherwise be necessary, so I thought I would raise the possibility, for consideration when we get to CSL 1.1.

Extend scope of et-al settings to cs:name

I'm authoring a style, and it requires different et-al settings for authors (min=3, use-first=1) and editors (min=2, use-first=1) in case of book chapters. This is not a widely used style, but I found that EndNote also offers separate et-al-settings for this precise case, so there probably is some demand for it.

The recent changeset that introduced the initialize-with-hyphen attribute also added a more hierarchical attribute structure for cs:name and cs:names (see discussion at <<issue 1>>). If possible, I'd like to squeeze in another modification for CSL 1.0: to allow the et-al-attributes to be set not only on cs:style, cs:bibliography and cs:citation (the current situation), but also on cs:name. That seems more logical than using cs:et-al, since the cs:et-al element was introduced to set et-al formatting, and not et-al behavior. Also, the attribute names would be rather repetitive ().


Add range-delimiter option to date-part element

The date element of citeproc-js is able to recognize and gracefully collapse ranged date input. The character used to delimit ranged date elements is a hyphen, but there are situations (with numeric dates and some foreign languages) where a different character is appropriate. The appropriate delimiter may also vary according to the level (year, month, day) that triggers the range split.

Accordingly, I would like to propose that a range-delimiter option be added to the date-part element. A patch to illustrate the change is attached. This has been coded and tested in citeproc-js. It covers the intended use cases, with CSL code that validates against the schema as modified by the patch.


Make cs:name optional

I can't think of any reason why cs:name couldn't be made an optional child element of cs:names.

add 'status' metadata

I'm realizing that this sort of convention ...
<title>Annals of Neurology (dev)</title>

... is an incredible hack of a way to indicate an unfinished style. How about we add a metadata element to address this? Any recommendations?

proposal: allow more variables to be rendered with cs:number

cs:number is currently limited to the variables "edition", "issue", "number", "number-of-volumes" and "volume". It probably makes sense to also allow "collection-number" and "chapter-number".

The other variables that can be expected to have (easily parsable) numeric content ("first-reference-note-number", "page", "page-first" and "number-of-pages") probably won't benefit from cs:number that much, as it is unlikely that they need ordinal formatting, so we might want to leave those alone.


Rename variables, types and terms to use consistent punctuation

The editortranslator term was a product of the flurry of activity in the push toward CSL 1.0. Since it's meant to be called internally by the processor, and is not normally used directly in CSL style files, it should be possible to change its name without creating serious confusion.

For consistency with the hyphenating convention use in other variables and terms, it could changed to editor-translator, or (possibly more clear) editor-and-translator.


Add options for author substitution

In CSL 1.0, subsequent-author-substitute only takes effect when an entire name list matches with that of the preceding bibliographic entry. Then, its value is rendered instead of names in the name list.

However, some styles also use substitution for partial matches (e.g. when only the first author matches), and some styles use a substitution string for each name, instead of for the whole name list. So we might wish to add an bibliography-specific option to switch between the different behaviors.

See also http://forums.zotero.org/discussion/13564/subsequentauthorsubstitute-for-multiple-authorcitations/?Focus=66721#Comment_66721


Settle input values for fuzzy dates

Two descriptions of fuzziness, LOC and MHRA, which each recognize two kinds of fuzziness. Unfortunately, they are not congruent with one another. We should decide whether to provide for all three, for only one of the two paris, or for none.


Provide a csl label term for each name variable

While testing for the deployment of style previews, Faolan is getting a processor error against two styles that call the "composer" variable with a label.

The cause turns out to be that "composer" is missing from the locale, so the immediate request is that it be added. Looking further, though, I see that the other name variables that are partnered with locale terms are not in the csl-terms locale schema. I don't know how it's handled in validation, but it seems as though they should be listed in the schema.

(If there are no objections, I'll go ahead and add "composer" to the English locale in a bit to get things going.)

Allow locale element in style with no xml:lang attribute

Using a locale element with no xml:lang attribute to lay down locale-wide defaults for specific values would be a useful thing to do. This proposal, suggested by Rintze, would revert a recent change that made the xml:lang attribute mandatory on in-style locale elements.

A patch is attached for illustration.


adding support for reviews

I don't think we can currently properly support reviews. I'd like to be able to support the expansive support I mention later in this thread:

http://forums.zotero.org/discussion/97/book-reviews-another-item-type/#Item_41

Might it be enough to add variables like:

  • reviewed-title
  • reviewed-author
  • reviewed-editor
  • reviewed-issued
  • reviewed-publisher

...?


Independent formatting of cs:number variable and ordinal suffix

This issue has been raised on xbiblio-devel here, and on the Zotero forums here.

As a possible solution for discussion, an approach similar to the cs:et-al node could be used:

<number variable="edition" form="ordinal"> 
  <ordinal-suffix vertical-align="sup"/> 
  <numeral font-weight="bold"/> 
</number> 

With numeral being required, and ordinal-suffix being optional. The sub-elements would not affect ordering, but would permit independent styling of the elements (so if the form= was not ordinal, ordinal-suffix in the example above would have no effect. If number is a singleton, it would just work the way it does now.

scale variable

We don't seem to have a variable to hold the scale of a map. It is similar to the resolution of an image or the bit-rate of a digital audio recording, which I suppose might also be included in a reference. "Scale" is specific to maps, but as that seems to be the most common need, and as the name is less ambiguous than "resolution", I'll put that forward as an initial suggestion.

If there is another variable that is used for this value by convention, let me know. The only guidance I could find on the Zotero forums was a note from Rick, suggesting that the value be written into the "note" field for the present. That was two years ago. Maybe with schema changes on the horizon in Zotero it would be possible to add something more specific for this data.

http://forums.zotero.org/discussion/8793/geological-society-of-america-journals/#Comment_40840

Decide how to handle fuzzy dates in CSL

There are three possibilities:

add a fixed "fuzzy" term implicitly always

provide a fuzzy-term-and-format attribute of some sort on the date element

add a condition (or conditions) that return(s) true for date variables that have (the relevant) fuzzy value set.

As there seems to be quite a bit of variation between styles in the treatment of fuzzy dates, 3 seems like the best route, if a satisfactory way to cast the condition can be arrived at.


Make it easier to identify the style license

Currently, independent CSL styles may use the cs:rights element to specify the license, e.g.:

<rights>This work is licensed under a Creative Commons Attribution-Share Alike 3.0 License: http://creativecommons.org/licenses/by-sa/3.0/</rights>

To make it easier to automatically identify under which license a style is licensed, I think we should consider adding a "license" attribute, with options to set it to some of the most popular licenses. E.g.

<rights license="cc-by-sa" />

would license the style under the most recent version of the Creative Commons Attribution-Share Alike license.

Define how to express "anonymous" and "et al" as names

Beside normal names (either literal or build of given, familiy etc.) there are two special cases:

  • Unknown names ("anonymous")
  • Abbreviated lists of names ("et al")

In combination with normal names you can have the following cases

Alice and Bob.

Alice, Bob et al.

anonymous.

anonymous et al.

Alice, Bob, and anonymous

Alice, Bob, anonymous et al. (maybe)

It is not clearly defined how to express this in CSL data input format.
Existing CSL styles typically test whether a name variable is empty. If it is, the "anonymous" term can be used. Here is a guess how to express the cases above (question marks = unclear):

"author" : [ {"given":"Alice"}, {"given":"Bob"} ]

"author" : [ {"given":"Alice"}, {"given":"Bob"}, ??? ]

"author" : [ ] or "author" : [ { } ] or no author field at al ???

"author" : [ ??? ]

"author" : [ {"given":"Alice"}, {"given":"Bob"}, { } ] ???

"author" : [ {"given":"Alice"}, {"given":"Bob"}, ??? ]

The "et al" case could be be solved by a specific type of name, but this needs to be discussed:

  • Normal name: {"given":"Alice"}
  • Anonymous: { }
  • et al : { "etal": 1 }

Limiter for cs:name: suppress-min

Another user has asked for a way of truncating a name variable without applying et al. In his case, the first author should be listed at the front of the citation, but only for works that don't have lots of authors. The leading label does not affect the full list of authors, which appears later in the citation.

http://forums.zotero.org/discussion/9141?page=1#Item_6

This can be addressed fairly simply with an end-name attribute to limit the number of authors that are listed, and a max-name attribute, to quash rendering if the varaible contains over a certain number of authors. Both of these options should specially permit the name variable to be used again. Accordingly, they should be available only on the name element itself, and not on style, bibliography, or citation.

There is running code for this in citeproc-js. A schema patch is attached. The CSL used for testing the code validates against the patched schema.


Add coordinator role, for "Director of Publication" (LoC)

This keeps coming up in the following thread:

http://forums.zotero.org/discussion/8565/?Focus=45188#Comment_45188

As explored and explained in the thread, extending the list of creators with one additional role seems to be necessary. I would like to suggest "coordinator" as an appropriate name. Patch attached for illustration.


Item type for classical works

In publishing on well-known classical and ancient works, a simplified citation format can be used to refer to the work, rather than a published instance of it. One possible solution in CSL would be to provide an item type for which bibliography output is suppressed.

The following links are relevant to the issue:

Comment thread on the Zotero forums

http://forums.zotero.org/discussion/9293/classical-citations/

Sections of the CMS that contain examples, although not explicit descriptions, of such citations

http://www.chicagomanualofstyle.org/ch17/ch17_sec251.html

http://www.chicagomanualofstyle.org/ch17/ch17_sec260.html

The xbiblio-devel discussion thread that led to the filing of this ticket

http://sourceforge.net/mailarchive/forum.php?set=custom&viewmonth=200911&viewday=25&forum_name=xbiblio-devel&style=threaded&max_rows=25&submit=Change+View


Move publisher to cs:names

As has been noted before, the publisher variable can be used with both cs:names and cs:text:

http://sourceforge.net/mailarchive/message.php?msg_id=20080622122017.GB27924%40laptop.nowhere.net

If the processor accepts plain strings on cs:names (treating them as "literal" rather than personal names), this could be fixed in the migration to 1.0. Zotero and other applications could then shift to treating publisher as a names variable, which would allow more graceful handling of works published by a subunit of a larger institution.


"preceeding author style" as an altervative to "suppress author" option for author-date formats.

I'm sure you have thought about the issue before, so please excuse me if I'm stepping on toes, or reopening a closed issue.

I exclusively use "author-date" citation styles. There are two ways I (and many others, I know by experience) I make in text citations:

(Case 1) Smith et al. (2010) have recently shown... 

(Case 2) ... as shown by others. (Smith et al. 2010)

In Word, I do case 2 by manually typing "Smith et al." in the document, then inserting the Zotero reference while checking the "suppress author" checkbox.

Now consider what happens when you switch citation styles. Perhaps you go from a journal that requires "et al." for 3+ authors to a journal that requires "et al." for 4+ authors. You would have to manually go through the document, find any articles with exactly 4 authors, and switch the manually-typed author names.

There's other use cases, two, such as when you correct the spelling of an Author's name in your database. Or, when you're being lazy and just plain don't want to type the authors names...

There //should// be no need for this. We're programmers :)

I dream of a day where there is a checkbox (next "suppress author") that says something like "preceeding author style" This would simply switch the citation style from case 1 to case 2.

From a CSL Schema, you would need something like:

#!xml

  <citation>
    <option name="et-al-min" value="3"/>
    <layout prefix="(" suffix=")" delimiter="; ">
      <group delimiter="; ">
        <group delimiter=", ">
          <text macro="contributors-short"/>
          <text macro="date"/>
          <text macro="point-locators"/>
        </group>
      </group>
    </layout>
    <alternatelayout delimiter=", ">
      <group delimiter="; ">
        <text macro="contributors-short"/>
        <group prefix="(" suffix=")" >
          <group delimiter="; ">
            <text macro="date"/>
            <text macro="point-locators"/>
          </group>
        </group>
      </group>
    </alternatelayout>
  </citation>

There may be other ways to do the same thing, but I think this would be reasonable.

On the Zotero style, one would need to

  1. implement a checkbox to switch between <layout> and <alternatelayout>. I would think that the code that drives <layout> could be re-used with little work.
  2. and work out fallback behavior for styles without a . (e.g., disable the checkbox and fallback to <layout>)

Clearly define CSL input format

The CSL input format is described in the CSL specification (the CSL data model), in the citeproc-js documentation (the CSL/JSON variant) and in the RELAX NG file (the CSL/XML variant). All should be losslessly mappable to each other but there are some differences.

  1. The non-dropping-particle from citeproc-js is called prefix in csl-data.rnc - this is not a problem but may be confusing.

  2. In csl-data.rnc a reference is identified by an URI but in citeproc-js by a simple string of any form.

  3. I could not find the 'container-uri' property from csl-data.rnc in citeproc-js

  4. csl-data.rnc seems to allow multiple dates of the same type and dates with different type in start-date and end-date.

  5. In csl-data.rnc the value-space of a year is xsd:gYear but in citeproc-js it is a non-zero integer.

  6. In csl-data.rnc the value-space of month and day is 00..99 instead o 1..12 and 1..31.

  7. In csl-data.rnc a date may have a day but no month at the same time.

  8. In csl-data.rnc a season cannot be of any literal form like in citeproc-js

  9. In citeproc-js the season is a property of the whole date variable but in csl-data.rnc it applies to a start and/or an end-date

  10. In citeproc-js the circa flag is a property of a whole date variable but in csl-data.rnc the circa flag applies to a start-date and/or an end-date.

  11. It is not clear how open-ended date ranges are encoded in csl-data.rnc

  12. In citeproc.js the list of allowed markup tags in rich text variables is

    i, b, sup, sup, sc, span@nocase, span@nodecor, ", '

plus locale quotes plus the tags can be nested (?) but in csl-data.rnc the
tags can not be nested, there are no local quotes and the list of tags is:

i, b, sup, sub, abbr, cite, cite@part, span, span@protect

Citeproc-js almost complies to the specification but point 8 (and maybe 9). Point 10,11 and maybe 2 can be solved by better documentation. The other points require a refactoring of csl-data.rnc


first-reference-note-number data type and variable name

From issue 36:

Aside: we have first-reference-note-number as a simple variable (not a number). Two things:

  1. well, should it have been under number?
  2. we probably need to establish consistent naming of three things:
    1. the full citation as a whole
    2. the individual references within the full citation
    3. the item in the bibliography
      The main thing added by cs:number is the ability to render in alternative numeric formats (roman, ordinal, or the alphabetic counting system used by year-suffix). So long a footnote backreferences do not require one of these alternative numbering systems, there is no problem. but the variable could be reclassified without any impact on styles.

The name does not seem ambiguous, if "reference" is taken to mean the act of referring to, rather than a thing we would call a reference. In other contexts, I think we've referred to clusters of references in the text or in footnotes as "citations", and references in the bibliography as "references" or "items". Individual references in the text or in footnotes I've referred to as "cites". (I have heard that the pandoc group have used "citations" and "cites" with the opposite meaning in their own discussions.)

Is any action proposed?

Make timestamp in cs:updated optional

Assuming that styles are stored with an empty cs:updated element in the styles repository, we should make this element's content optional, i.e. switch from

info-updated = element cs:updated { xsd:dateTime }

to

info-updated = element cs:updated { xsd:dateTime? }

proposal: support gender-specific ordinals

Languages like Spanish and French use gender-specific ordinals (e.g. the French "premier" (masculine) and "première" (feminine)).

A proposal, which would only involve changes to the CSL locale files for these languages, is described here: http://sourceforge.net/mailarchive/message.php?msg_id=26629141

[edit: fixed link]


Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.