relaton-bib 2.0.0.pre.alpha.2 → 2.0.0.pre.alpha.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3703439e0f575f526e99aa9076d7587bd9720061061877cb7c44565d8e510da
-  data.tar.gz: bd0a42331c2548e5ecfd8be6bc7d30e732cedccdeebbd96f9a6a33dfe80402b3
+  metadata.gz: 1c0a55f18c7de55d6551412157acc62414e31ad0f23f692b26aaab429f0958f1
+  data.tar.gz: cb1bc25d03c5419e8663532da102899f8720081e54ee3c7ab1c6bc800c74873f
 SHA512:
-  metadata.gz: 3c6cbf18b5fcd8885f86a7cfd24d9c18aea1e56b1a80f0fa81da943194742f859063f73aa76ceda2e96bcc75c9a621dbf7e9c192cb7278b0f1b0a6a3416d9822
-  data.tar.gz: 803e613dd74b00447c9aa04b643a3584b2b9132ef1af4e01dc311cf8627b8ddbd5ec591f8dd790e9c33c56aef24e69520455dfb7afbb0be5cd0638b7a6f31764
+  metadata.gz: 9c0b2431f5cbdecacd05074669d0eac38a2c9d783c0fea627d0dbc80f5fdc50a1223ea759715cc85548506039e01b70f88237386f4edb03305299fd47f61b630
+  data.tar.gz: d8080d53ebd5cac16d39e480c04c9e8de4e63be8c8d5fb20890f5fdd27dccedf2dce2b862117a8473a7c8f9e00be4865da54f799213363d95717dec23a1b8bda

data/.gitignore

@@ -11,5 +11,7 @@
 
 # rspec failure tracking
 .rspec_status
-.rubocop-https---raw-githubusercontent-com-riboseinc-oss-guides-master-ci-rubocop-yml
 Gemfile.lock
+.claude/
+.rubocop-remote-87c7cdd254a8d09d005ee06efac7acc0.yml
+rubocop-87c7cdd254a8d09d005ee06efac7acc0.yml

data/CLAUDE.md

@@ -0,0 +1,96 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+RelatonBib is a Ruby gem that implements the [BibliographicItem model](https://github.com/metanorma/relaton-models#bibliography-uml-models) for bibliographic reference management. It's part of the Relaton ecosystem and serves as the base library for other Relaton gems.
+
+## Common Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rake spec
+
+# Run a single test file
+bundle exec rspec spec/relaton_bib/bibliographic_item_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/relaton_bib/bibliographic_item_spec.rb:42
+
+# Run linting
+bundle exec rubocop
+
+# Auto-fix linting issues
+bundle exec rubocop -a
+
+# Interactive console
+bin/console
+```
+
+## Architecture
+
+### Serialization Layer (lutaml-model)
+
+The codebase uses [lutaml-model](https://github.com/lutaml/lutaml-model) for serialization. Each model class in `lib/relaton/bib/model/` inherits from `Lutaml::Model::Serializable` and declares attributes with XML/YAML/JSON mappings.
+
+### Core Classes
+
+**`Relaton::Bib::Item`** ([lib/relaton/bib/model/item.rb](lib/relaton/bib/model/item.rb)) - The main serialization class defining all bibliographic attributes and their XML mappings. Uses `ItemData` as its underlying model.
+
+**`Relaton::Bib::ItemData`** ([lib/relaton/bib/item_data.rb](lib/relaton/bib/item_data.rb)) - The data container class that holds bibliographic data and provides conversion methods (`to_xml`, `to_yaml`, `to_bibtex`, `to_rfcxml`). This separation allows the same data to be serialized differently (bibitem vs bibdata).
+
+**`Relaton::Bib::Bibitem`** and **`Relaton::Bib::Bibdata`** - Variants of `Item` with different XML root elements and attributes (bibitem excludes `ext`, bibdata excludes `id`).
+
+### Component Models
+
+Each bibliographic attribute has its own class in `lib/relaton/bib/model/`:
+
+- `Title`, `LocalizedString`, `LocalizedMarkedUpString` - text with language/script
+- `Contributor`, `Person`, `Organization` - contributors and affiliations
+- `Docidentifier` - document IDs (DOI, ISBN, etc.)
+- `Date` - publication dates with custom `StringDate` type
+- `Relation` - related documents (circular reference with Item)
+- `Ext` - extension data (doctype, ICS codes, structured identifiers)
+
+### Parsing
+
+- **`HashParserV1`** ([lib/relaton/bib/hash_parser_v1.rb](lib/relaton/bib/hash_parser_v1.rb)) - Converts legacy Hash/YAML format to `ItemData`
+- **`Converter::BibXml`** ([lib/relaton/bib/converter/bibxml.rb](lib/relaton/bib/converter/bibxml.rb)) - Parses RFC BibXML format via `Relaton::Bib::Converter::BibXml.to_item`
+- **lutaml-model native** - `Item.from_xml`, `Item.from_yaml`, `Item.from_json` handle current format
+
+### Rendering
+
+- **`Renderer::BibtexBuilder`** - Converts `ItemData` to BibTeX format
+- **`Converter::BibXml`** - Converts `ItemData` to RFC XML format via `Relaton::Bib::Converter::BibXml.to_xml`
+- **lutaml-model native** - `to_xml`, `to_yaml`, `to_json` via the serialization classes
+
+### Usage Pattern
+
+```ruby
+# Parse from YAML
+item = Relaton::Bib::Item.from_yaml(yaml_string)
+
+# Parse from XML
+item = Relaton::Bib::Bibitem.from_xml(xml_string)
+item = Relaton::Bib::Bibdata.from_xml(xml_string)
+
+# Parse from RFC XML
+item = Relaton::Bib::Converter::BibXml.to_item(xml_string)
+
+# Convert to different formats (returns string)
+item.to_xml                    # as <bibitem>
+item.to_xml(bibdata: true)     # as <bibdata>
+item.to_yaml
+item.to_bibtex
+item.to_rfcxml
+```
+
+## Code Style
+
+- Follows Ribose OSS Ruby style guide (inherited via `.rubocop.yml`)
+- Target Ruby version: 3.1+
+- Uses YARD documentation comments

data/Gemfile

@@ -5,6 +5,7 @@ gemspec
 
 gem "byebug"
 gem "equivalent-xml", "~> 0.6"
+gem "openssl", "~> 3.3.2" # 3.3.0 raises error when rubocop fetches https resources
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"
 gem "rubocop"

data/README.adoc

@@ -180,7 +180,7 @@ Relaton::Bib::Item.from_yaml yaml
 xml = File.read 'spec/fixtures/rfc.xml'
  => "<reference anchor=\"RFC1\" target=\"10.17487/RFC0001\">\n  <front>\n    <title>Title RFC1</title>\n    <seriesInf..."
 
-Relaton::Bib::Parser::RfcReference.from_xml xml
+Relaton::Bib::Converter::BibXml.to_item xml
  => #<Relaton::Bib::ItemData:0x000000011dc9fc98 ...
 ----
 
@@ -202,7 +202,7 @@ item = Relaton::Bib::Bibdata.from_xml xml
 
 [source,ruby]
 ----
-Relaton::Bib::BibtexParser.from_bibtex File.read('spec/examples/techreport.bib')
+Relaton::Bib::BibtexParser.from_bibtex File.read('spec/fixtures/techreport.bib')
 => {"ISOTC211"=>
   #<Relaton::Bib::Item:0x007fedee0a2ab0
   ...

data/grammars/basicdoc.rng

@@ -198,14 +198,14 @@ Applicable to modify and delete</a:documentation>
         </zeroOrMore>
       </element>
     </optional>
-    <optional>
+    <zeroOrMore>
       <element name="description">
-        <a:documentation>Description of the change described in this block</a:documentation>
-        <zeroOrMore>
+        <a:documentation>Description(s) of the change described in this block</a:documentation>
+        <oneOrMore>
           <ref name="BasicBlock"/>
-        </zeroOrMore>
+        </oneOrMore>
       </element>
-    </optional>
+    </zeroOrMore>
     <optional>
       <element name="newcontent">
         <a:documentation>New content to be added to the document; applicable to add and modify</a:documentation>
@@ -267,6 +267,10 @@ in a document (e.g. sourcecode annotations)</a:documentation>
       <value>justified</value>
     </choice>
   </define>
+  <define name="IdRefType">
+    <a:documentation>Type of cross-references to elements. In BasicDoc, these always point to id { xsd:ID } </a:documentation>
+    <data type="IDREF"/>
+  </define>
   <define name="RequiredId">
     <a:documentation>Mandatory anchor of element, to be used for cross-references within the document</a:documentation>
     <attribute name="id">
@@ -382,33 +386,7 @@ in a document (e.g. sourcecode annotations)</a:documentation>
     <a:documentation>Block intended to capture reviewer comments about some text in the document</a:documentation>
     <element name="review">
       <ref name="RequiredId"/>
-      <attribute name="reviewer">
-        <a:documentation>The party who has offered the comment</a:documentation>
-      </attribute>
-      <optional>
-        <attribute name="type">
-          <a:documentation>The type of reviewer comment</a:documentation>
-        </attribute>
-      </optional>
-      <optional>
-        <attribute name="date">
-          <a:documentation>The date when the comment was made</a:documentation>
-          <data type="dateTime"/>
-        </attribute>
-      </optional>
-      <optional>
-        <attribute name="from">
-          <a:documentation>Identifier for the start of the text or point in the text to which the comment applies.
-If not provided, the comment applies in the vicinity of the place it has been inserted into the text</a:documentation>
-          <data type="IDREF"/>
-        </attribute>
-      </optional>
-      <optional>
-        <attribute name="to">
-          <a:documentation>Identifier for the end of the text to which the comment applies</a:documentation>
-          <data type="IDREF"/>
-        </attribute>
-      </optional>
+      <ref name="ReviewAttributes"/>
       <oneOrMore>
         <ref name="paragraph">
           <a:documentation>Reviewer comments content</a:documentation>
@@ -416,6 +394,35 @@ If not provided, the comment applies in the vicinity of the place it has been in
       </oneOrMore>
     </element>
   </define>
+  <define name="ReviewAttributes">
+    <attribute name="reviewer">
+      <a:documentation>The party who has offered the comment</a:documentation>
+    </attribute>
+    <optional>
+      <attribute name="type">
+        <a:documentation>The type of reviewer comment</a:documentation>
+      </attribute>
+    </optional>
+    <optional>
+      <attribute name="date">
+        <a:documentation>The date when the comment was made</a:documentation>
+        <data type="dateTime"/>
+      </attribute>
+    </optional>
+    <optional>
+      <attribute name="from">
+        <a:documentation>Identifier for the start of the text or point in the text to which the comment applies.
+If not provided, the comment applies in the vicinity of the place it has been inserted into the text</a:documentation>
+        <ref name="IdRefType"/>
+      </attribute>
+    </optional>
+    <optional>
+      <attribute name="to">
+        <a:documentation>Identifier for the end of the text to which the comment applies</a:documentation>
+        <ref name="IdRefType"/>
+      </attribute>
+    </optional>
+  </define>
   <define name="NumberingAttributes">
     <optional>
       <attribute name="unnumbered">
@@ -857,6 +864,7 @@ in case the table cannot be rendered accessibly (HTML 5)</a:documentation>
   <define name="tr">
     <a:documentation>Sequence of cells to be displayed as a row in a table</a:documentation>
     <element name="tr">
+      <ref name="TrAttributes"/>
       <oneOrMore>
         <choice>
           <ref name="td">
@@ -869,6 +877,9 @@ in case the table cannot be rendered accessibly (HTML 5)</a:documentation>
       </oneOrMore>
     </element>
   </define>
+  <define name="TrAttributes">
+    <empty/>
+  </define>
   <define name="tr-no-id">
     <a:documentation>Sequence of cells to be displayed as a row in a table: optional ID attributes recursively (for use in Relaton, metadata)</a:documentation>
     <element name="tr">
@@ -1280,13 +1291,13 @@ Restricted recursively to contain only other such inline elements with no identi
       <ref name="pure_strike"/>
       <ref name="pure_smallcap"/>
       <ref name="br"/>
+      <ref name="stem"/>
     </choice>
   </define>
   <define name="NestedTextElement">
     <a:documentation>Contents of TextElement tags: leaves out tags that should occur only at top level of block: bookmark image hr pagebreak</a:documentation>
     <choice>
       <ref name="PureTextElement"/>
-      <ref name="stem"/>
       <ref name="eref"/>
       <ref name="xref"/>
       <ref name="hyperlink"/>
@@ -1497,7 +1508,7 @@ Restricted recursively to contain only other such inline elements with no identi
         <attribute name="to">
           <a:documentation>A reference to an anchor element (typically a bookmark), 
 to indicate that the index range covers a range of locations between the current index element and the `to` anchor</a:documentation>
-          <data type="IDREF"/>
+          <ref name="IdRefType"/>
         </attribute>
       </optional>
       <ref name="index-primary">
@@ -1655,7 +1666,7 @@ which can be bookmarks as well as block or section references</a:documentation>
   <define name="XrefAttributes">
     <attribute name="target">
       <a:documentation>The identifier of a section, block or inlined element being referenced</a:documentation>
-      <data type="IDREF"/>
+      <ref name="IdRefType"/>
     </attribute>
     <optional>
       <attribute name="type">
@@ -1694,23 +1705,29 @@ which can be bookmarks as well as block or section references</a:documentation>
     <a:documentation>Inline reference to a paragraph or paragraphs, appearing as a footnote.
 The target of a footnote is the location it is embedded in within the text</a:documentation>
     <element name="fn">
-      <attribute name="reference">
-        <a:documentation>The number of the footnote, used to identify it visually</a:documentation>
-      </attribute>
-      <oneOrMore>
-        <ref name="paragraph">
-          <a:documentation>The content of the footnote</a:documentation>
-        </ref>
-      </oneOrMore>
+      <ref name="FnAttributes"/>
+      <ref name="FnBody"/>
     </element>
   </define>
+  <define name="FnBody">
+    <oneOrMore>
+      <ref name="paragraph">
+        <a:documentation>The content of the footnote</a:documentation>
+      </ref>
+    </oneOrMore>
+  </define>
+  <define name="FnAttributes">
+    <attribute name="reference">
+      <a:documentation>The number of the footnote, used to identify it visually</a:documentation>
+    </attribute>
+  </define>
   <define name="callout">
     <a:documentation>Inline reference to a paragraph or paragraphs, appearing as annotation of source code</a:documentation>
     <element name="callout">
       <attribute name="target">
         <a:documentation>The target of the callout is understood to be the location of the callout within the source code; 
 the extent of the target is not expressed overtly</a:documentation>
-        <data type="IDREF"/>
+        <ref name="IdRefType"/>
       </attribute>
       <text>
         <a:documentation>The label of the callout, used to identify its target within the source code</a:documentation>

data/grammars/biblio-standoc.rng

@@ -1,13 +1,14 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <grammar xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0" xmlns="http://relaxng.org/ns/structure/1.0">
-  <!--
-    Add-ons to biblio.rnc for standoc model: defines the extension point BibDataExtensionType
-    of relaton
-    
-    Specialisations as for biblio.rnc. Extension point can be redefined completely for a flavour of standoc
-    (SDO); but other elements in Bibdata can only be extended (more specialised vocabularies for Bibdata)
-  -->
   <include href="biblio.rng">
+    <!-- ALERT: we cannot have comments on root element, as they intervene with https://github.com/metanorma/metanorma/issues/437 fix -->
+    <!--
+      Add-ons to biblio.rnc for standoc model: defines the extension point BibDataExtensionType
+      of relaton
+      
+      Specialisations as for biblio.rnc. Extension point can be redefined completely for a flavour of standoc
+      (SDO); but other elements in Bibdata can only be extended (more specialised vocabularies for Bibdata)
+    -->
     <define name="BibData">
       <a:documentation>The bibliographic description of a standardisation document</a:documentation>
       <ref name="StandardBibliographicItem"/>
@@ -75,12 +76,6 @@ from other documents in the same doctype</a:documentation>
     <ref name="flavor">
       <a:documentation>Flavour of Metanorma used to process this document</a:documentation>
     </ref>
-    <optional>
-      <ref name="editorialgroup">
-        <a:documentation>Groups associated with the production of the standards document, typically within
-a standards definition organization</a:documentation>
-      </ref>
-    </optional>
     <zeroOrMore>
       <ref name="ics">
         <a:documentation>Classification of the document contents taken from the International Classification of Standards</a:documentation>
@@ -91,6 +86,9 @@ a standards definition organization</a:documentation>
         <a:documentation>Representation of the identifier for the standardisation document, giving its individual semantic components</a:documentation>
       </ref>
     </zeroOrMore>
+    <ref name="DocumentImages">
+      <a:documentation>Coverpage and other images to be rendered with document</a:documentation>
+    </ref>
   </define>
   <define name="doctype">
     <a:documentation>Classification of the standardisation document</a:documentation>
@@ -126,49 +124,6 @@ a standards definition organization</a:documentation>
 However we prefer not to hardcode it, given ongoing extension.</a:documentation>
     <text/>
   </define>
-  <define name="editorialgroup">
-    <a:documentation>A group associated with the production of the standards document, typically within
-a standards definition organization</a:documentation>
-    <element name="editorialgroup">
-      <oneOrMore>
-        <ref name="technical-committee">
-          <a:documentation>A technical committee associated with the production of the standards document</a:documentation>
-        </ref>
-      </oneOrMore>
-    </element>
-  </define>
-  <define name="technical-committee">
-    <a:documentation>Technical committee associated with the production of a standards document</a:documentation>
-    <element name="technical-committee">
-      <ref name="IsoWorkgroup"/>
-    </element>
-  </define>
-  <define name="IsoWorkgroup">
-    <optional>
-      <attribute name="number">
-        <a:documentation>Numeric identifier of the technical committee</a:documentation>
-      </attribute>
-    </optional>
-    <optional>
-      <attribute name="type">
-        <a:documentation>Type of the technical committee, used in identifying the technical committee</a:documentation>
-      </attribute>
-    </optional>
-    <optional>
-      <attribute name="identifier">
-        <a:documentation>Non-numeric, complete identifier of the technical committee</a:documentation>
-      </attribute>
-    </optional>
-    <optional>
-      <attribute name="prefix">
-        <a:documentation>Disambiguating prefix added to number to form the identifier of the technical committee,
-typically indicating its type</a:documentation>
-      </attribute>
-    </optional>
-    <text>
-      <a:documentation>Name of the technical committee</a:documentation>
-    </text>
-  </define>
   <define name="ics">
     <a:documentation>Classification taken from the International Classification of Standards. 
 ICS is defined by ISO here -- https://www.iso.org/publication/PUB100033.html</a:documentation>
@@ -268,6 +223,32 @@ and not those document components</a:documentation>
       </optional>
     </element>
   </define>
+  <define name="DocumentImages">
+    <zeroOrMore>
+      <element name="coverpage-image">
+        <a:documentation>Images to be displayed on the coverpage of the document</a:documentation>
+        <ref name="image-no-id"/>
+      </element>
+    </zeroOrMore>
+    <zeroOrMore>
+      <element name="innercoverpage-image">
+        <a:documentation>Images to be displayed on the inner coverpage of the document</a:documentation>
+        <ref name="image-no-id"/>
+      </element>
+    </zeroOrMore>
+    <zeroOrMore>
+      <element name="tocside-image">
+        <a:documentation>Images to be displayed on the Table of Contents page of the document</a:documentation>
+        <ref name="image-no-id"/>
+      </element>
+    </zeroOrMore>
+    <zeroOrMore>
+      <element name="backpage-image">
+        <a:documentation>Images to be displayed on the backpage of the document</a:documentation>
+        <ref name="image-no-id"/>
+      </element>
+    </zeroOrMore>
+  </define>
   <define name="StandardBibliographicItem">
     <ref name="BibliographicItem"/>
     <zeroOrMore>

data/grammars/biblio.rng

@@ -1,23 +1,25 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<!--
-  instantiations of this grammar may replace leaf strings
-  with more elaborated types; e.g. title (text) replaced with
-  title-main, title-intro, title-part; type replaced with
-  enum.
-  
-  some renaming at leaf nodes is permissible
-  
-  obligations can change both from optional to mandatory,
-  and from mandatory to optional; optional elements may
-  be omitted; freely positioned alternatives may be replaced
-  with strict ordering
-  
-  DO NOT introduce a namespace here. We do not want a distinct namespace
-  for these elements, and a distinct namespace for any grammar inheriting
-  these elements; we just want one namespace for any child grammars
-  of this.
--->
 <grammar xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0" xmlns="http://relaxng.org/ns/structure/1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
+  <!--
+    ALERT: we cannot have comments on root element, as they intervene with https://github.com/metanorma/metanorma/issues/437 fix
+    
+    Instantiations of this grammar may replace leaf strings
+    with more elaborated types; e.g. title (text) replaced with
+    title-main, title-intro, title-part; type replaced with
+    enum.
+    
+    Some renaming at leaf nodes is permissible
+    
+    Obligations can change both from optional to mandatory,
+    and from mandatory to optional; optional elements may
+    be omitted; freely positioned alternatives may be replaced
+    with strict ordering
+    
+    DO NOT introduce a namespace here. We do not want a distinct namespace
+    for these elements, and a distinct namespace for any grammar inheriting
+    these elements; we just want one namespace for any child grammars
+    of this.
+  -->
   <!--
     https://www.myintervals.com/blog/2009/05/20/iso-8601-date-validation-that-doesnt-suck/
     iso8601date = xsd:string { pattern = "([\+-]?\d{4}(?!\d{2}\b))((-?)((0[1-9]|1[0-2])(\3([12]\d|0[1-9]|3[01]))?|W([0-4]\d|5[0-2])(-?[1-7])?|(00[1-9]|0[1-9]\d|[12]\d{2}|3([0-5]\d|6[1-6])))([T\s]((([01]\d|2[0-3])((:?)[0-5]\d)?|24\:?00)([\.,]\d+(?!:))?)?(\17[0-5]\d([\.,]\d+)?)?([zZ]|([\+-])([01]\d|2[0-3]):?([0-5]\d)?)?)?)?" }
@@ -240,6 +242,8 @@ Detailed in https://www.relaton.org/model/creator/</a:documentation>
     </choice>
   </define>
   <define name="roledescription">
+    <a:documentation>A more detailed description of the role of the contributor
+Some descriptions are reserved words; in particular, the editorial committee of a standard has the role description "committee"</a:documentation>
     <element name="description">
       <ref name="LocalizedMarkedUpString"/>
     </element>
@@ -441,7 +445,10 @@ real names (if the person is named with a pseudonym or user name); previous lega
     </oneOrMore>
     <zeroOrMore>
       <ref name="subdivision">
-        <a:documentation>The subdivision of the organization directly involved with the production of the bibliographic item</a:documentation>
+        <a:documentation>The subdivision of the organization directly involved with the production of the bibliographic item.
+Multiple subdivisions can be specified for an organization, with no implication of hierarchical
+relation between them
+Editorial and advisory groups are represented as consecutive subdivisions of the SDO</a:documentation>
       </ref>
     </zeroOrMore>
     <optional>
@@ -483,6 +490,11 @@ real names (if the person is named with a pseudonym or user name); previous lega
           <a:documentation>The type of subdivision</a:documentation>
         </attribute>
       </optional>
+      <optional>
+        <attribute name="subtype">
+          <a:documentation>The subtype of subdivision; e.g. different types of technical committee</a:documentation>
+        </attribute>
+      </optional>
       <ref name="OrganizationType">
         <a:documentation>The subdivision, modelled recursively as an organization</a:documentation>
       </ref>
@@ -857,7 +869,7 @@ depending on whether the items exist as independent documents, or are parts of a
       </zeroOrMore>
     </element>
   </define>
-  <define name="BibItemType" combine="choice">
+  <define name="BibItemType">
     <a:documentation>Type of bibliographic item.
 The value list complies with the types provided in ISO 690:2021.
 NOTE: These values represent a strict superset to BibTeX
@@ -1241,6 +1253,11 @@ Refer to `BibliographicItem` for definitions</a:documentation>
   </define>
   <define name="formattedref">
     <element name="formattedref">
+      <optional>
+        <attribute name="format">
+          <a:documentation>format of formatted reference; Metanorma assumes references are formatted as Metanorma XML</a:documentation>
+        </attribute>
+      </optional>
       <oneOrMore>
         <ref name="TextElement"/>
       </oneOrMore>
@@ -1812,6 +1829,11 @@ May be used to differentiate rendering of notes in bibliographies</a:documentati
     <a:documentation>Abstract of bibliographic item</a:documentation>
     <element name="abstract">
       <ref name="LocalizedStringAttributes"/>
+      <optional>
+        <attribute name="format">
+          <a:documentation>What format the formatted abstract is in. In Metanorma, assumed to be Metanorma XML</a:documentation>
+        </attribute>
+      </optional>
       <choice>
         <oneOrMore>
           <ref name="BasicBlockNoId">