input: move noteIndex property

[bdarcus]

trafficstars

I'm confused by this, and think it's a mistake.

A fragment of what I think we want:

"citationID": 123,
"citationItems": [],
"noteIndex": 1

Correct, @fbennett @bwiernik @cormacrelf?

Because what the schema now says is this, which if nothing else is confusing just from a maintenance perspective (given the json schema keyword of "properties"), as well as I would think for developers implementing

"citationID": 123,
"citationItems": [],
"properties": {
   "noteIndex": 1
 }

I do see that in the citeproc-js docs, so it's obviously not strictly a mistake. But I'd still like to change it for 1.1, if there are no objections (see linked PR).

[bwiernik]

One benefit of the current structure (aside from maintaining existing structures if there isn't a compelling reason to change them) is that if we wanted to support the compound citations used in Chemistry, an object might provide a good place for the necessary values to be stored.

E.g.,

1. a) First citation; b) section citation; c) third citation
2. a) First citation; b) section citation; c) third citation

[bdarcus]

... an object might provide a good place for ...

Perhaps, but surely not this object?

I don't really understand that use case, but it seems from your example there's just a prefix on each cite within a single citation, so that prefix number or letter seems better placed within the citationItems data, parallel to the id?.

[bwiernik]

The structure of citations in chemistry is that multiple cites in a single citation are individually enumerated by letters within a single numeric citation. This is used to refer to a whole batch of thematically-similar items as a set. If they are referenced subsequently, they are generally referred to again all at once (citing just the group number), but they might also be referenced individually, citing both the group number and item letter.

That's currently difficult to grok against the noteIndex counter structure.

What exactly is the problem the current structure is causing?

[fbennett]

I also don't see why the current structure needs to be shifted. It's a fundamental value for processing that all implementations will be referencing at the current location. Implementations wanting to process both 1.0.1 and 1.1 styles would be faced with either applying conditionals across the code base wherever the id value is referenced, or subverting the schema change by transforming the input object back to the 1.0.1 form on receipt, to avoid the need for further changes internally. If it were me, I would choose the latter.

[bdarcus]

If they are referenced subsequently, they are generally referred to again all at once (citing just the group number), but they might also be referenced individually, citing both the group number and item letter.

Wow; what a headache.

What exactly is the problem the current structure is causing?

It's a fundamental value for processing that all implementations will be referencing at the current location.

"It's" meaning noteIndex; right? No doubt, and no objection.

But properties?

Again: the purpose of the input schema changes are to clearly express the model to developers going forward.

Implementations wanting to process both 1.0.1 and 1.1 styles would be faced with either applying conditionals across the code base wherever the id value is referenced, or subverting the schema change by transforming the input object back to the 1.0.1 form on receipt, to avoid the need for further changes internally. If it were me, I would choose the latter.

In the grand schema of 1.1 input changes, this would be the most minor. There are others (in citation, locators) that are much more significant.

So not sure why not do this one in particular.

But it's admittedly not a big issue either way. So I'll close the PR if people prefer.

However, if we do close (or just use the PR to add annotations), I think we must at least add an annotation that explains why that property (properties) is there, as a piece of the effort to annotate the schema asked for in #190.

For example, this from the citeproc-js docs is circular, and only explains the noteIndex sub-property:

In the properties portion of a citation, the noteIndex value indicates the footnote number in which the citation is located within the document. Citations within the main text of the document have a noteIndex of zero.

[bdarcus]

I suppose this is worthy of a larger conversation, somewhere, about compatibility.

I've been assuming different schema versions for citation and data, and processors would thus be able to handle them.

But the other option is to keep the citation schema model as is, but only add elements for new stuff.

So keep locator from 1.0, but add locators for 1.1, keep properties, etc.

But that's not a problem-free alternative.

Maybe this should happen on Discourse. Problem is, not all developers are engaged these days.