Citations references

docs/schema/block.md

@@ -6,4 +6,4 @@
 Union of all block content types.
 
 
-Union of: @oxa:code, @oxa:heading, @oxa:paragraph, @oxa:thematicbreak
+Union of: @oxa:code, @oxa:heading, @oxa:paragraph, @oxa:reference, @oxa:thematicbreak

docs/schema/cite.md

@@ -0,0 +1,91 @@
+(oxa:cite)=
+
+## Cite
+
+
+An inline citation to a bibliographic reference.
+
+
+__type__: _string_, ("Cite")
+
+: The type discriminator for Cite nodes.
+
+__id__: __string__
+
+: A unique identifier for the node.
+
+__classes__: __array__ ("string")
+
+: A list of class names for styling or semantics.
+
+__data__: __object__
+
+: Arbitrary key-value data attached to the node.
+
+__xref__: __string__
+
+: Reference to the id of a Reference node in the containing document.
+
+__children__: __array__ ("Inline")
+
+: Optional inline content that overrides generated citation display text.
+: See @oxa:inline
+
+__prefix__: __array__ ("Inline")
+
+: Inline content preceding the citation within its group.
+: See @oxa:inline
+
+__suffix__: __array__ ("Inline")
+
+: Inline content following the citation within its group.
+: See @oxa:inline
+
+__display__: _string_, ("author" | "date" | "full")
+
+: Controls which part of the referenced bibliographic record is rendered.
+
+__locator__: __string__
+
+: A human-readable locator within the referenced work.
+
+__url__: __string__
+
+: A deep link to a specific location in the referenced work.
+
+__intent__: __string__
+
+: The citation intent, typically using a CiTO vocabulary value.
+
+### Example
+
+`````{tab-set}
+````{tab-item} OXA
+:sync: oxa
+```json
+{"type":"Cite","xref":"jones2022","prefix":[{"type":"Text","value":"see "}],"locator":"fig. 3","intent":"extends"}
+```
+````
+
+````{tab-item} Markdown
+:sync: markdown
+```markdown
+[@jones2022]
+```
+````
+
+````{tab-item} HTML
+:sync: html
+```html
+<a href="#jones2022" role="doc-biblioref">see Jones, 2022, fig. 3</a>
+```
+````
+
+````{tab-item} JATS
+:sync: jats
+```xml
+<xref ref-type="bibr" rid="jones2022">see Jones, 2022, fig. 3</xref>
+```
+````
+
+`````

docs/schema/citegroup.md

@@ -0,0 +1,65 @@
+(oxa:citegroup)=
+
+## CiteGroup
+
+
+An inline container that groups citations with shared display semantics.
+
+
+__type__: _string_, ("CiteGroup")
+
+: The type discriminator for CiteGroup nodes.
+
+__id__: __string__
+
+: A unique identifier for the node.
+
+__classes__: __array__ ("string")
+
+: A list of class names for styling or semantics.
+
+__data__: __object__
+
+: Arbitrary key-value data attached to the node.
+
+__kind__: _string_, ("narrative" | "parenthetical")
+
+: The citation display style shared by the group.
+
+__children__: __array__ ("Cite")
+
+: The citations in the group.
+: See @oxa:cite
+
+### Example
+
+`````{tab-set}
+````{tab-item} OXA
+:sync: oxa
+```json
+{"type":"CiteGroup","kind":"parenthetical","children":[{"type":"Cite","xref":"jones2022"},{"type":"Cite","xref":"smith2021"}]}
+```
+````
+
+````{tab-item} Markdown
+:sync: markdown
+```markdown
+[@jones2022; @smith2021]
+```
+````
+
+````{tab-item} HTML
+:sync: html
+```html
+<span role="doc-biblioref">(Jones, 2022; Smith, 2021)</span>
+```
+````
+
+````{tab-item} JATS
+:sync: jats
+```xml
+<xref ref-type="bibr" rid="jones2022">Jones, 2022</xref>; <xref ref-type="bibr" rid="smith2021">Smith, 2021</xref>
+```
+````
+
+`````

docs/schema/inline.md

@@ -6,4 +6,4 @@
 Union of all inline content types.
 
 
-Union of: @oxa:text, @oxa:emphasis, @oxa:inlinecode, @oxa:strong, @oxa:subscript, @oxa:superscript
+Union of: @oxa:cite, @oxa:citegroup, @oxa:text, @oxa:emphasis, @oxa:inlinecode, @oxa:strong, @oxa:subscript, @oxa:superscript

docs/schema/reference.md

@@ -0,0 +1,58 @@
+(oxa:reference)=
+
+## Reference
+
+
+A block-level bibliographic record.
+
+
+__type__: _string_, ("Reference")
+
+: The type discriminator for Reference nodes.
+
+__id__: __string__
+
+: A unique identifier for the node, used by Cite xref values.
+
+__classes__: __array__ ("string")
+
+: A list of class names for styling or semantics.
+
+__data__: __object__
+
+: Arbitrary key-value data attached to the node.
+
+__children__: __array__ ("Inline")
+
+: Optional inline content for the rendered display of this reference.
+: See @oxa:inline
+
+__csl__: __object__
+
+: A CSL-JSON item object for the bibliographic record.
+
+### Example
+
+`````{tab-set}
+````{tab-item} OXA
+:sync: oxa
+```json
+{"type":"Reference","id":"jones2022","children":[{"type":"Text","value":"Jones and Chen (2022)."}],"csl":{"id":"jones2022","citation-key":"jones2022","type":"article-journal","title":"A Framework for Open Science","author":[{"given":"Alice","family":"Jones"},{"given":"Bob","family":"Chen"}],"issued":{"date-parts":[[2022]]}}}
+```
+````
+
+````{tab-item} HTML
+:sync: html
+```html
+<div id="jones2022" role="doc-biblioentry">Jones and Chen (2022).</div>
+```
+````
+
+````{tab-item} JATS
+:sync: jats
+```xml
+<ref id="jones2022"><element-citation publication-type="journal"><article-title>A Framework for Open Science</article-title></element-citation></ref>
+```
+````
+
+`````

lexicon/blocks/defs.json

@@ -109,6 +109,41 @@
         }
       }
     },
+    "reference": {
+      "type": "object",
+      "description": "A block-level bibliographic record.",
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "classes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "data": {
+          "type": "unknown"
+        },
+        "text": {
+          "type": "string"
+        },
+        "facets": {
+          "type": "array",
+          "items": {
+            "type": "ref",
+            "ref": "pub.oxa.richtext.facet"
+          }
+        },
+        "csl": {
+          "type": "unknown"
+        }
+      },
+      "required": [
+        "id",
+        "csl"
+      ]
+    },
     "thematicBreak": {
       "type": "object",
       "description": "A thematic or structural division between sections of content.",
@@ -134,6 +169,7 @@
         "#code",
         "#heading",
         "#paragraph",
+        "#reference",
         "#thematicBreak"
       ]
     }

lexicon/richtext/facet.json

@@ -20,6 +20,8 @@
             "type": "union",
             "closed": false,
             "refs": [
+              "#cite",
+              "#citeGroup",
               "#emphasis",
               "#inlineCode",
               "#strong",
@@ -48,6 +50,51 @@
         }
       }
     },
+    "cite": {
+      "type": "object",
+      "description": "An inline citation to a bibliographic reference.",
+      "properties": {
+        "xref": {
+          "type": "string"
+        },
+        "display": {
+          "type": "string",
+          "knownValues": [
+            "author",
+            "date",
+            "full"
+          ]
+        },
+        "locator": {
+          "type": "string"
+        },
+        "url": {
+          "type": "string"
+        },
+        "intent": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "xref"
+      ]
+    },
+    "citeGroup": {
+      "type": "object",
+      "description": "An inline container that groups citations with shared display semantics.",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "knownValues": [
+            "narrative",
+            "parenthetical"
+          ]
+        }
+      },
+      "required": [
+        "kind"
+      ]
+    },
     "emphasis": {
       "type": "object",
       "description": "Emphasized content (typically italicized)."

packages/oxa-conformance/cases/block/reference-basic.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "../../schemas/test-case.schema.json",
+  "title": "Basic reference",
+  "description": "A bibliographic reference with CSL-JSON data",
+  "category": "block",
+  "formats": {
+    "oxa": {
+      "type": "Reference",
+      "id": "jones2022",
+      "children": [{ "type": "Text", "value": "Jones and Chen (2022)." }],
+      "csl": {
+        "id": "jones2022",
+        "citation-key": "jones2022",
+        "type": "article-journal",
+        "title": "A Framework for Open Science",
+        "author": [
+          { "given": "Alice", "family": "Jones" },
+          { "given": "Bob", "family": "Chen" }
+        ],
+        "issued": { "date-parts": [[2022]] }
+      }
+    },
+    "html": "<div id=\"jones2022\" role=\"doc-biblioentry\">Jones and Chen (2022).</div>",
+    "jats": "<ref id=\"jones2022\"><element-citation publication-type=\"journal\"><article-title>A Framework for Open Science</article-title></element-citation></ref>"
+  }
+}

packages/oxa-conformance/cases/inline/cite-basic.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "../../schemas/test-case.schema.json",
+  "title": "Basic citation",
+  "description": "A citation to a reference by id with prefix and locator metadata",
+  "category": "inline",
+  "formats": {
+    "oxa": {
+      "type": "Cite",
+      "xref": "jones2022",
+      "prefix": [{ "type": "Text", "value": "see " }],
+      "locator": "fig. 3",
+      "intent": "extends"
+    },
+    "markdown": "[@jones2022]",
+    "html": "<a href=\"#jones2022\" role=\"doc-biblioref\">see Jones, 2022, fig. 3</a>",
+    "jats": "<xref ref-type=\"bibr\" rid=\"jones2022\">see Jones, 2022, fig. 3</xref>"
+  },
+  "notes": {
+    "markdown": "Markdown citation syntax does not preserve all OXA citation metadata without extensions"
+  }
+}