📄 Citations, Groups and References

[rowanc1]

Introduces citation node types.

Some open questions on this:

• Reference node naming — Is Reference the best name, or should it be BibliographicEntry, CitationRecord, or something closer to schema.org's CreativeWork? Reference is concise and maps naturally to JATS <ref>, but could be confused with general cross-references in some contexts.
• xref as a initial convention
• CiTO vocabulary — Should we define a recommended subset of CiTO intents, or leave it open? A closed set improves interoperability; an open set accommodates domain-specific needs.
• ORCID and extended author metadata — CSL-JSON name objects do not natively include fields like orcid. Should ORCIDs and similar identifiers be stored in a separate mapping outside the csl object, or should they be added to the CSL name objects as extensions?

[github-actions]

Curvenote Preview

Directory	Preview	Checks	Updated (UTC)
content/RFC0005	🔍 Inspect	✅ 22 checks passed (2 optional)	Mar 25, 2026, 7:04 PM

[fwkoch]

Overall, the approach to citations defined in this RFC is great.

Regarding your open questions, I already addressed the Reference node naming.

For CiTO vocabulary, there are ~100 existing intents - this is so many but also narrowing to a subset feels a little arbitrary. I'm inclined to allow all CiTO intents; they are just descriptive strings that help readers understand and follow citations. I don't see big differences in behavior between different intents.

For ORCID, I agree inclusion is useful, and there isn't an exceptionally slick solution. My immediate thought is to allow oxa metadata on the Reference, alongside csl. This would be structured identically to article metadata, so we are not adding a new schema for OXA renderers. Ideally a citation would include full csl and full oxa representation, but it could also have only one or the other or partial versions of each... (I think this is close to your "separate mapping" suggestion.)

[fwkoch]

Suggested change

	locator?: string;
	locator?:[Inline];

locator is for human-readable display text. This feels equivalent to prefix/suffix (as opposed to fields like xref/intent/url which only work as strings).

[fwkoch]

Two concerns with display field.

First, the description of this field states default (i.e. no display) behavior falls back to default rendering, either author-date or number. I propose implicit behavior should have an explicit counterpart, i.e. leaving display off is the same as using display: 'author-date', as suggested above.

Suggested change

	display?: 'author' | 'date' | 'full';
	display?: 'author' | 'date' | 'full' | 'author-date';

[fwkoch]

Second, maybe less of a concern, but a point that should be emphasized:

We are relying on the renderer to understand and respect the intricacies of the OXA spec. Now, I would assume most "numeric" citation renderers to just see a cite node and replace it with the number. This doesn't work for author/date citation kinds.

e.g. for something like:

{type: Cite, kind: author} stated one fact in {type: Cite, kind: date}; {type: Cite, kind: undefined} disagreed.

authors would need to rely on their content getting rendered like so:

_Koch_ stated one fact in _2026_; [2] disagreed

rather than the lazier:

[1] stated one fact in [1]; [2] disagreed

Is this our expectation? Setting the bar higher for everyone involved?

(I think the alternative is to put the burden entirely on the authors to understand how their content will be rendered and adjust the wording and citation structure accordingly.)

[gabestein]

This is a good point. Along similar lines, in practice I've found there are plenty of edge cases where authors want to fully customize the text of their inline citations, or perhaps more urgently in the short term, where JATS imports use <mixed-citation> and so the xref contents can't be predictably rendered from the reference without trying to parse it as a string, with all of the attendant issues. I don't love building "custom" escape hatches into standards, as allowing it causes problems with downstream processing and rendering, but we may still want to consider the possibility. CSL partly discusses this limitation here, which offers an okay workaround for most use-cases, but not all. Note, too, the discussion of issues with legal citations, which are not a target for OXA, but I can imagine similar citation styles promulgating in science if we're successful in breaking down the article into more referencable components.

I don't know that there's a particularly good solution here — I've often thought if you want to do weird things with citations, you should build on top of generic links the way epub does, rather than having specific citations. But that's another discussion.

Ah, I see this is covered in children, below!

[fwkoch]

A standalone Cite node is completely equivalent to a narrative CiteGroup with a single Cite child. It feels a little bad to have two different ways to do the same thing, but I think the only way to avoid that is to require Cite nodes to only exist inside CiteGroups. This gives us consistency but extra boilerplate for the simplest case.

My personal preference is consistency, i.e. always require a CiteGroup. This also makes narrative vs. parenthetical always explicit (since those are only defined on CiteGroup).

[fwkoch]

Regarding note - it's probably worth a small peek ahead to how OXA may handle footnotes.

In JATS, citations use xref -> ref structures, where xref has a specific @xref-type and ref is differentiated by the content it holds (e.g. mixed-citation). There is also note which is an element for non-citation content in a bibliographic ref (JATS best practice is to avoid using this element - https://jats.nlm.nih.gov/archiving/tag-library/1.4/element/note.html). Finally, there are fn footnotes. These use the same xref node in the text, but have a different @xref-type and point to fn nodes in a fn-group.

I like the proposal that Cite will extend a more-generic, not-yet-defined CrossReference node. I think Footnote will be defined similarly, as another extension of CrossReference? Then, there will also be the node type these xref fields point to (FootnoteDefinition or something).

[fwkoch]

Naming for this node is challenging. In isolation, "Reference" makes sense - these are the article's references.

However, in the context of other nodes, it gets muddy: CrossReferences "reference" other nodes, but CiteGroup "references" a "Reference" ...

When things get hairy like this, I'm always inclined to introduce patterns that make node types more verbose but make relationships clearer. For example, if we extend the thinking to generic xrefs, citations, and footnotes, we could have:

In-line reference -> block-level target
---------------------------------------
CrossReference    -> <any node>
CiteReference     -> CiteDefinition
FootnoteReference -> FootnoteDefinition

Or maybe just Cite and Footnote for the in-line nodes.

---

All that said, I'm also perfectly fine declaring that "Reference" (capitalized noun) is this specific node type, regardless of how much we use the verb "reference" elsewhere. However - if we do leave this as Reference, we need to consider the footnote case... is it just FootnoteDefinition and we don't worry about similar naming conventions for these similar nodes?

[gabestein]

Right on. These conventions confuse me to this day, and I agree that it's worth paying some attention to them and deciding if we want to break convention to make it easier for, in particular, developers from outside of academia, to onboard onto these standards and work with folks with academic backgrounds.

My understanding is in vernacular language used by most researchers, the inline node for a citation (e.g. [1] or (Koch, 2026)) is referred to as a "citation." The block node it points to (e.g. Koch, F.W. "Naming for this node is challenging." OXA RFC 5. March 26, 2026. https://github.com/oxa-dev/rfc/pull/5/.) is referred to as a "reference." At the same time, "citation" is also used to describe the effect of having referenced another work, independent of how many times it appears as an inline node in a document. Meanwhile, the inline node for a footnote, almost always rendered as superscript, does not seem to have a formal name! And, of course, the block node it references is simply called a "footnote."

Given the vernacular use of "reference," I don't know that CiteReference or FootnoteReference is appropriate, which is why most tools I'm aware of use simply Cite and Footnote as the node names, as you suggest. But I agree this is also confusing, because "footnote" is the vernacular word for the referenced block element, not the inline element!

I don't have a good proposal for solving this, and agree we could just go with convention. Another stray thought is to use abbreviations to completely disambiguate from the vernacular (although CrossRef breaks this bc ugggggh, but ignore that for now), so, e.g.:

In-line reference -> block-level target
---------------------------------------
CrossRef    -> <any node>
CiteRef     -> CiteDef
FootnoteRef -> FootnoteDef

¯_(ツ)_/¯

[fwkoch]

I'm a little confused by children: There's the rendered representation of the entire Reference (i.e. text in the reference list) and there's the short representation when it is referenced by Cite.

Here, "inline content" implies we are talking about the latter case? However, don't Cite nodes themselves define inline rendering? Is Reference.children just another fallback if Cite.display and Cite.children are both undefined and the renderer is unopinionated? I feel like the Reference should not concern itself with inline rendering.

However, maybe my understanding is wrong and children refers to the representation of the full reference. In that case, I understand and agree; we just need to change the wording here.

[gabestein]

Agreed — a little confused if the intent here is, like Cite children, to replace rendered representations, or to add to them to add e.g. notes to the reference.

[fwkoch]

👍 Leveraging CSL-JSON is great.

[fwkoch]

👍 I agree we need not prescribe a collection where References are listed. They are simply block-level content that can be handled at render time, in whatever manner is appropriate for the context.

[fwkoch]

I wonder if there's any benefit to prefix/suffix at the CiteGroup level... The prefix in this example "see" refers to both citations in the group. I think this is probably overcomplexity, and prefix/suffix on Cite only is fine.

[gabestein]

Similarly, do we need the ability to specify the separator for a CiteGroup, or is a semicolon always sufficient?

[gabestein]

This may be out of scope for OXA, but requiring the identifier to be in the containing document may preclude supporting endnotes in the way they're often used in books and other multi-document works. E.g., in epub3 you can use the <a> tag to cite an element in another document, such as citing a work in chapter-1.html for which the reference only appears in a global references.html. Granted, this is not a full citation/reference specification, it's just extending the HTML a tag. But it is quite useful in practice. The proposed locator property seems to point to this possibility, but this rule would preclude actually allowing it.

https://help.apple.com/itc/booksassetguide/en.lproj/itccf8ecf5c8.html

This also allows an author to cite a work multiple times throughout a multi-document work while only needing to reference it once in a bibliography or endnote.

This also brings to mind the inverse case, somewhat more common in humanities, where a work is only cited in the reference list as a general reference (often with additional commentary), but is not specifically cited in the text. Do we think OXA should support that case?

[gabestein]

This is probably right, and yet I think it's worth at least asking whether we should consider instead extending a generic reference tag with a role or type attribute, similar to epub3's epub:type="noteref".

The philosophical thought here is that in a world where we want to be considering allowing researchers to cite and annotate content far more granularly than traditional citations, do we want to continue to privilege citations with their own tag? And for that matter, do we want to differentiate between internal and external references given our desire to build OXA for remixing of content and, in some sense, break the distinction between "internal" and "external" in the first place?

Again, I think this is probably the right approach for all the reasons mentioned below, as well as making implementations easier by avoiding polymorphism, improving human readability, and, well, the fact that HTML has never been able to develop a standardized approach to citations/references/footnotes despite or perhaps due to the flexibility of the a tag.

But I think it's worth at least examining this assumption while we have the opportunity to.

[gabestein]

This is a really solid approach! As noted in inline comments, I think it's worth taking a little time to make sure we want to follow some existing conventions given the behavioral changes we're looking to make, but the justifications for doing so do make sense.

On open questions:

• Reference node names: I added some thoughts about reference nodes as an extension of @fwkoch's comment in https://github.com/oxa-dev/rfc/pull/5/changes#r2993194496
• CiTO vocabulary: keeping it open makes the most sense to me. My guess is conventions will arise fairly naturally in specific communities that will (mostly) resolve interop concerns.
• ORCID and extended author metadata: I like the idea of extending csl-json rather than adding additional complexity. Per the docs, arbitrary fields simply won't be passed to the processor, so we'll have no issues with validation for folks using CSL toolkits downstream, but oxa renderers can choose to parse those fields. One thought: we could do as citation.js does and prepend non-conforming fields with an underscore to signal that they're extensions. (e.g. _orcid: https://orcid.org/1234-1234-1234-1234X).