"issue", "number" and bibtex

I received a bug report because APA uses the variable “issue” for volume
numbers, whereas bibtex would use “number”. And so, when mapping bibtex
to CSL, the APA style is not working properly.

See the relevant discussion here:

Any suggestion on how to treat issues like this?


Per off-list message I just sent to you and Chris, two things:

  1. bibtex “number” is definitely supposed to map to CSL “issue”, but …

  2. bibutils deals with this issue inconsistently, so I tend to think
    the problem should be solved there

If he doesn’t solve it there, then you should map
mods:part/mods:detail[type=‘number’]/mods:number to CSL ‘issue’.

CSL ‘number’ is for document numbers.


I just came across the same issue. Both biblatex and csl have “number” and “issue” fields, but their meanings seem to be quite different. Do I understand correctly that biblatex’s “number” (string) should always be mapped to CSL’s “issue” (number) and biblatex’s “issue” (string) should also be converted to CSL’s “issue” whereas there is no biblatex equivalent of CSL’s “number” (number)?

Can CSL deal with the issue being a string like “Summer” or should one always make sure it is converted to a number?

The biblatex manual says this about the difference between the two fields in biblatex:

2.3.11 Journal Numbers and Issues
The words ‘number’ and ‘issue’ are often used synonymously by journals to refer
to the subdvision of a volume. The fact that biblatex’s data model has fields
of both names can sometimes lead to confusion about which field should be used.
First and foremost the word that the journal uses for the subdivsion of a volume
should be of minor importance, what matters is the role in the data model. As a rule
of thumb number is the right field in most circumstances. In the standard styles
number modifies volume, whereas issue modifies the date (year) of the entry.
Numeric identifiers and short designators that are not necessarily (entirely) numeric
such as ‘A’, ‘S1’, ‘C2’, ‘Suppl. 3’, ‘4es’ would go into the number field, because
they usually modify the volume. The output of—especially longer—non-numeric
input for number should be checked since it could potentially look odd with some
styles. The field issue can be used for designations such as ‘Spring’, ‘Winter’ or
‘Michaelmas term’ if that is commonly used to refer to the journal.


For entries that are not journal articles the biblatex number field should rather be mapped to CSL variables collection-number or number (for patents).

The number of a journal or the volume/number of a book in a series. See also
issue as well as §§ 2.3.7, 2.3.10, 2.3.11. With @patent entries, this is the number or
record token of a patent or patent request. Normally this field will be an integer or an
integer range, but it may also be a short designator that is not entirely numeric such
as “S1”, “Suppl. 2”, “3es”. In these cases the output should be scrutinised carefully.

Since number is—maybe counterintuitively given its name—a literal field, sorting
templates will not treat its contents as integers, but as literal strings, which means
that “11” may sort between “1” and “2”. If integer sorting is desired, the field can be
declared an integer field in a custom data model (see § 4.5.4). But then the sorting of
non-integer values is not well defined.

See page 23 of the same manual.

Also, biblatex has ISWC, ISRN, ISAN and ISMN fields which could also map to CSL’s number, I think.


And then there is the question of field type.

As far as what I can tell both fields are numeric in CSL, right? [1] And they are both strings in biblatex. So when converting, if I get a string in biblatex (such as “Summer” or “1st” or “3”), should I try to convert that to an integer, or should I just leave it as a string and assume that CSL will be able to handle that in some way even though it expects a number?

[1] https://aurimasv.github.io/z2csl/typeMap.xml#cslVar-issue

Sorry, I missed that on the first go. I don’t really know what to do about that, although citeproc-js seems to treat it okay. It probably conflicts with a number of style guides though.

1 Like

(Except “Summer”, which should probably end up as a season on the issued date (using month > 13) so that it can be localised. But this also depends on style guides which might want that formatted as a number, but the numeric form of month for seasons is undefined behaviour. Which brings us to hemispheres, as well. Currently there isn’t hemisphere support anywhere, which is one good motivation for EDTF Level 2.)

1 Like

Yeah, I see how that could make sense if it’s really just a reference to the season. I was trying to find examples of “issue” referencing something related to the publication year as the biblatex spec seems to request. “Summer” could be interpreted. But how about “July/August edition”, “early Summer”, “Spring/Autumn edition”. “Autumn Colour issue” (not sure what that would be), “Indian Summer edition” (meaning: September/October), “Forever Winter issue” (April/May issue of a journal published during a year with a particularly long winter)? I can see how the issue string almost becomes part of the title in a sense and in that case it probably shouldn’t be translated.

Yep. EDTF can actually represent some of those, but if they’re titles, then they’re titles.

1 Like

I would represent all of those examples as CSL issue. issue can be a numeric value, but a string is acceptable if that is how the issue is labeled. The cs:number function exists to being able to format numbers (e.g., as ordinal), but it can also render fields literally if presented with a string.

Another related question: what shall we do when we have biblatex number and issue, which could be absolutely possible. Going from 2 fields > 1 field isn’t ideal.