relaton-bib 2.1.7 → 2.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15d36c3ed1e4ae0042f96a06a6320dccbe089a87a691b77b8ad14e276217bd22
-  data.tar.gz: d6db31f185b72668da0c289bc462a62d1cfd1b9dda542f37b9dee7257d5282b4
+  metadata.gz: 395f67780defebb9f033822f67f28dec65f7a507b687631d718e7a143926bf95
+  data.tar.gz: 15b9c502271a17e795f21886d6721cff6533a3a9c9e67aaec8ef9b332ddb87de
 SHA512:
-  metadata.gz: 304fcb5b02e2c019d532164228acede4ed81c210eafededbbdd9446ac94fcd32d142be5be7689db09bc17b7aa3e6cfb333b892220ba36e64fcccc2bdda2df29c
-  data.tar.gz: 390cf8b808ab85b099d573b4bea833d265a2326d81c00936e5cebe6ae79c9243991843d44a46d3d24e403137f1ec27b433acc532c51f99a0d5e91d0ed66d6744
+  metadata.gz: 71e9495276f45dab74db3170a882d8db0a62aff68c29f5daa00e1c59abac9ad6d4069b887da6aee1293b6df1b3e2e57878c8abd9158014eac9d945f92a478f4b
+  data.tar.gz: 6045720a0265a3fb0c54ae76b7870a8b4288ef310832f9519bb488bf18b3f5cce94c00e08bb5b6ae42c832dcb3124a99de6a8e80599aa78ab90b779963990c42

data/CLAUDE.md

@@ -77,7 +77,17 @@ Each bibliographic attribute has its own class in `lib/relaton/bib/model/`:
 ### Rendering
 
 - **`Renderer::BibtexBuilder`** - Converts `ItemData` to BibTeX format
-- **`Converter::BibXml`** - Converts `ItemData` to RFC XML format via `Relaton::Bib::Converter::BibXml.to_xml`
+- **`Converter::BibXml`** - Converts `ItemData` to an `Rfcxml::V3` model object via
+  `Relaton::Bib::Converter::BibXml.from_item`; call `to_xml` on the result (this is what
+  `ItemData#to_rfcxml` does). Two output shapes share one class hierarchy:
+  - `ToRfcxml` / `ToRfcxmlReferencegroup` (default) emit **BibXML**, the shape the Relaton
+    data repositories publish. It keeps the RFC 7991-deprecated `<format>` element, so it
+    must stay byte-compatible — every relaton data fetcher's `"bibxml"` format is
+    `entry.to_rfcxml`. Do not change its output.
+  - `ToRfcxmlV3` / `ToRfcxmlReferencegroupV3` (`v3: true`) subclass those and emit strict
+    **RFC 7991**: no `<format>`, plus `<stream>`, `ascii*` attributes and `<refcontent>`.
+    New v3-only behaviour belongs in the subclass, so the default path stays untouched by
+    construction and `spec/relaton/bib/converter/bibxml_spec.rb` keeps passing unedited.
 - **lutaml-model native** - `to_xml`, `to_yaml`, `to_json` via the serialization classes
 
 ### Usage Pattern
@@ -98,11 +108,13 @@ item.to_xml                    # as <bibitem>
 item.to_xml(bibdata: true)     # as <bibdata>
 item.to_yaml
 item.to_bibtex
-item.to_rfcxml
+item.to_rfcxml                 # BibXML (what the data repos publish)
+item.to_rfcxml(v3: true)       # strict RFC 7991 / xml2rfc v3
+item.to_rfcxml(anchor: "ISO712", include_keywords: false)
 ```
 
 ## Code Style
 
 - Follows Ribose OSS Ruby style guide (inherited via `.rubocop.yml`)
-- Target Ruby version: 3.1+
+- Target Ruby version: 3.2+ (`required_ruby_version` in the gemspec, `TargetRubyVersion` in `.rubocop.yml`)
 - Uses YARD documentation comments

data/README.adoc

@@ -334,6 +334,70 @@ item.to_rfcxml
 </reference>
 ----
 
+=== Export bibliographic item to strict RFC XML v3
+
+`to_rfcxml` emits the BibXML shape published by the Relaton data repositories,
+which still carries the `<format>` element that RFC 7991 deprecates. Pass
+`v3: true` for output that follows the RFC 7991 (xml2rfc v3) vocabulary
+instead: no `<format>`, a `<stream>` element, `ascii*` attributes, and
+`<refcontent>` for identifiers that cannot be expressed as `<seriesInfo>`.
+
+[source,ruby]
+----
+item.to_rfcxml v3: true
+<reference anchor="ISO20483">
+  <front>
+    <title>Cereals and pulses</title>
+    <author initials="Ö." asciiInitials="O." surname="Nürk" asciiSurname="Nurk"/>
+    <author>
+      <organization abbrev="ISO" ascii="International Organization for Standardization">International Organization for Standardization</organization>
+    </author>
+    <date year="2013"/>
+  </front>
+  <refcontent>ISO 20483:2013-2014</refcontent>
+</reference>
+----
+
+Documents published by the IETF (identified by a contributing organization
+named `IETF`, `Internet Engineering Task Force` or `RFC Publisher`) express
+their identifiers as `<seriesInfo>` rather than `<refcontent>`:
+
+[source,ruby]
+----
+<reference anchor="RFC2119" target="https://www.rfc-editor.org/info/rfc2119">
+  <stream>IETF</stream>
+  <front>
+    <title>Key words for use in RFCs to Indicate Requirement Levels</title>
+    <seriesInfo name="BCP" value="14"/>
+    <seriesInfo name="RFC" value="2119"/>
+    ...
+  </front>
+</reference>
+----
+
+The v3 mode also applies the citation rules the IETF toolchain expects, which
+the BibXML mode leaves alone:
+
+* Contributors with role `author` or `editor` become `<author>`; the wider set
+  (`publisher`, `authorizer`, `translator`, …) is used only when the item names
+  no author or editor, so an RFC's publisher is not listed as its author.
+* `<title>` takes the composite `title[@type="main"]`, else joins
+  title-intro / title-main / title-part, so multipart standards keep their full
+  title. Inline markup is flattened, since v3 `<title>` is text-only.
+* Identifiers that restate the reference label, `URN` identifiers and the
+  `I-D.` anchor form are left out of `<refcontent>`; Internet-Draft
+  `<seriesInfo>` carries the full `draft-…` name, which is what xml2rfc
+  resolves against.
+* Where folding a name leaves no letters (a non-Latin script), the `ascii*`
+  attribute is omitted rather than emitted blank.
+
+Two further options are accepted by both modes:
+
+`anchor:`:: overrides the anchor otherwise derived from `docnumber`, for
+callers that carry their own identifier (for example a Metanorma Semantic XML
+`bibitem/@id`).
+`include_keywords:`:: set to `false` to suppress `<keyword>` elements.
+
 === Logging
 
 RelatonBib uses the relaton-logger gem for logging. By default, it logs to STDOUT. To change the log levels and add other loggers, read the https://github.com/relaton/relaton-logger#usage[relaton-logger] documentation.

data/lib/relaton/bib/converter/bibxml/from_rfcxml.rb

@@ -326,7 +326,18 @@ module Relaton
 
               t = Title.new(content: si.name, language: "en", script: "Latn")
               Series.new(title: [t], number: si.value, type: "main")
-            end.compact
+            end.compact + stream_series
+          end
+
+          # RFC XML v3 carries the publication stream in a <stream> element.
+          # ItemData has no dedicated slot for it, so it is kept the way
+          # relaton-ietf does: as a series marked `type="stream"`.
+          def stream_series
+            return [] unless @reference.stream
+
+            t = Title.new(content: @reference.stream, language: "en",
+                          script: "Latn")
+            [Series.new(title: [t], type: "stream")]
           end
 
           # --- Keyword ---

data/lib/relaton/bib/converter/bibxml/to_rfcxml.rb

@@ -5,14 +5,15 @@ module Relaton
     module Converter
       module BibXml
         class ToRfcxml
-          def initialize(item, include_keywords: true)
+          def initialize(item, include_keywords: true, anchor: nil)
             @item = item
             @include_keywords = include_keywords
+            @anchor = anchor
           end
 
           def transform
             model = ::Rfcxml::V3::Reference.new
-            model.anchor = @item.docnumber || derive_anchor
+            model.anchor = @anchor || @item.docnumber || derive_anchor
             model.target = create_target
             model.front = create_front
             model.format = create_format
@@ -26,14 +27,22 @@ module Relaton
             di&.content&.to_s&.gsub(" ", ".")
           end
 
+          # A <uri> may legitimately carry no type -- biblio.rng makes it
+          # optional, and hand-authored bibitems often omit it -- so never call
+          # String methods on it unguarded.
+          def target_types = %w[src doi]
+
           def create_target
-            target = @item.source.detect { |l| l.type.casecmp("src").zero? } ||
-              @item.source.detect { |l| l.type.casecmp("doi").zero? }
+            target = target_types.filter_map { |t| source_of_type(t) }.first
             return unless target
 
             target.content.to_s
           end
 
+          def source_of_type(type)
+            @item.source.detect { |l| l.type&.casecmp(type)&.zero? }
+          end
+
           def create_front # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
             front = ::Rfcxml::V3::Front.new
             front.title = Rfcxml::V3::Title.new(content: @item.title[0].content) if @item.title.any?
@@ -59,9 +68,16 @@ module Relaton
             end
           end
 
+          # A `type="stream"` series is the publication stream, not a series:
+          # it has no number, so it would yield a valueless <seriesInfo>.
+          def seriesinfo_series?(ser)
+            ser.type != "stream" &&
+              ser.title.reject { |t| t.content == "DOI" }.any?
+          end
+
           def series_to_seriesinfo # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity
             @item.series.select do |s|
-              s.title.reject { |t| t.content == "DOI" }.any?
+              seriesinfo_series?(s)
             end.uniq do |s|
               s.title.find { |t| t.content != "DOI" }.content
             end.each_with_object([]) do |s, si|
@@ -71,8 +87,13 @@ module Relaton
             end
           end
 
+          # Which contributors become <author>; overridden by the v3 emitter.
+          def contributors_for_authors
+            @item.contributor.reject { |c| committee_contributor?(c) }
+          end
+
           def create_authors # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
-            @item.contributor.reject { |c| committee_contributor?(c) }.map do |contrib|
+            contributors_for_authors.map do |contrib|
               role = "editor" if contrib.role.detect { |r| r.type == "editor" }
               Rfcxml::V3::Author.new(
                 role: role,
@@ -284,7 +305,10 @@ module Relaton
             return unless @item.abstract.any?
 
             content = @item.abstract[0].content
-            paragraphs = content.scan(%r{<p>(.*?)</p>}m).flatten
+            # Semantic XML paragraphs carry attributes (`<p id="_349ea…">`);
+            # match those too, or the whole abstract falls through to the
+            # fallback below and the markup is escaped into the <t>.
+            paragraphs = content.scan(%r{<p\b[^>]*>(.*?)</p>}m).flatten
             paragraphs = [content] if paragraphs.empty?
             ts = paragraphs.map { |p| Rfcxml::V3::Text.new(content: CGI.unescapeHTML(p)) }
             Rfcxml::V3::Abstract.new(t: ts)
@@ -294,7 +318,7 @@ module Relaton
 
           def create_format # rubocop:disable Metrics/AbcSize
             @item.source.each_with_object([]) do |l, a|
-              next unless FORMAT_TYPES.any? { |ft| l.type.casecmp(ft).zero? }
+              next unless FORMAT_TYPES.any? { |ft| l.type&.casecmp(ft)&.zero? }
 
               a << Rfcxml::V3::Format.new(
                 type: l.type, target: l.content,

data/lib/relaton/bib/converter/bibxml/to_rfcxml_referencegroup.rb

@@ -3,9 +3,10 @@ module Relaton
     module Converter
       module BibXml
         class ToRfcxmlReferencegroup
-          def initialize(item, include_keywords: true)
+          def initialize(item, include_keywords: true, anchor: nil)
             @item = item
             @include_keywords = include_keywords
+            @anchor = anchor
           end
 
           def transform
@@ -30,6 +31,8 @@ module Relaton
           end
 
           def create_anchor
+            return @anchor if @anchor
+
             docid = @item.docidentifier.detect(&:primary) ||
               @item.docidentifier[0]
             return unless docid
@@ -38,9 +41,13 @@ module Relaton
             id.sub(/^(RFC|BCP|FYI|STD) /, '\1').sub(/^\w+\./, "")
           end
 
+          # An untyped <uri> is legal, so guard before comparing.
+          def target_types = %w[src doi]
+
           def create_target
-            target = @item.source.detect { |l| l.type.casecmp("src").zero? } ||
-              @item.source.detect { |l| l.type.casecmp("doi").zero? }
+            target = target_types.filter_map do |type|
+              @item.source.detect { |l| l.type&.casecmp(type)&.zero? }
+            end.first
             return unless target
 
             target.content.to_s

data/lib/relaton/bib/converter/bibxml/to_rfcxml_referencegroup_v3.rb

@@ -0,0 +1,43 @@
+module Relaton
+  module Bib
+    module Converter
+      module BibXml
+        #
+        # Strict RFC 7991 flavour of {ToRfcxmlReferencegroup}: members are
+        # rendered by {ToRfcxmlV3}, and every one of them gets an anchor,
+        # which the v3 grammar makes mandatory on `<reference>`.
+        #
+        class ToRfcxmlReferencegroupV3 < ToRfcxmlReferencegroup
+          private
+
+          def target_types = %w[src HTML doi]
+
+          # <referencegroup> needs an anchor just as much as its members do,
+          # so fall back past the docidentifier the parent relies on.
+          def create_anchor
+            anchor = super || @item.docnumber || @item.id
+            anchor && anchor.to_s.strip.gsub(/\s+/, ".")
+          end
+
+          def build_references
+            included_items.each_with_index.map do |item, idx|
+              ref = ToRfcxmlV3.new(item, include_keywords: @include_keywords)
+                .transform
+              ref.anchor = member_anchor(idx) if ref.anchor.to_s.empty?
+              ref
+            end
+          end
+
+          def included_items
+            @item.relation.select { |rel| rel.type == "includes" }
+              .map(&:bibitem)
+          end
+
+          def member_anchor(idx)
+            "#{create_anchor || 'reference'}_#{idx + 1}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/relaton/bib/converter/bibxml/to_rfcxml_v3.rb

@@ -0,0 +1,416 @@
+module Relaton
+  module Bib
+    module Converter
+      module BibXml
+        #
+        # Strict RFC 7991 (xml2rfc v3) flavour of {ToRfcxml}.
+        #
+        # It differs from the BibXML output its parent produces in four ways:
+        #
+        # * the deprecated `<format>` element is never emitted;
+        # * identifiers of documents published outside the IETF go into
+        #   `<refcontent>` rather than being forced into `<seriesInfo>`
+        #   (RFC 7991 2.39), as do series that carry no number;
+        # * `<stream>` and the `ascii*` attributes are populated;
+        # * `<front>` is filled out enough to satisfy the v3 grammar, which
+        #   requires a title and at least one author.
+        #
+        class ToRfcxmlV3 < ToRfcxml
+          # Organizations whose documents are "home" standards: their
+          # identifiers are expressible as <seriesInfo>.
+          HOME_ORGS = [
+            "IETF", "Internet Engineering Task Force", "RFC Publisher"
+          ].freeze
+
+          # Identifier types that are already emitted as <seriesInfo> by the
+          # parent, or that never belong in one.
+          NON_AUTHORITATIVE_TYPES = %w[DOI URI].freeze
+
+          # Identifiers metanorma-ietf drops as internal bookkeeping.
+          IGNORED_ID_RE = /\A(rfc-anchor|Internet-Draft)/
+
+          # Series that name the document itself; handled as identifiers.
+          SUBSERIES = %w[BCP STD].freeze
+
+          HOME_ID_RE = /\A(?<name>RFC|BCP|STD|FYI)\s*(?<value>\d+)\z/i
+          # xml2rfc only resolves a draft reference when seriesInfo carries the
+          # full draft name, so keep `draft-…` intact. The `I-D.` anchor form
+          # is a citation label, not the identifier (metanorma-ietf#283).
+          DRAFT_ID_RE = /\A(?<value>draft-\S+)\z/i
+          DRAFT_ANCHOR_RE = /\AI-D[.\s]\s*\S+\z/i
+
+          # Identifier types that duplicate a human-readable identifier or are
+          # bookkeeping rather than citation content (metanorma-ietf#301).
+          EXCLUDED_ID_TYPES = %w[URN].freeze
+
+          # Title parts joined when relaton supplies no composite title.
+          TITLE_PARTS = %w[title-intro title-main title-part].freeze
+
+          # Roles that may stand in for an author when the item names none,
+          # mirroring the released renderer's `creatornames_roles_allowed`.
+          FALLBACK_ROLES = %w[performer adapter translator publisher
+                              distributor authorizer].freeze
+
+          # The values RFC XML v3 allows on <stream>; "editorial" was added by
+          # RFC 9280. Keyed by the spellings the RFC Editor and relaton-ietf
+          # use, so "Independent Submission" is not silently thrown away.
+          STREAMS = {
+            "ietf" => "IETF", "iab" => "IAB", "irtf" => "IRTF",
+            "independent" => "independent",
+            "independent submission" => "independent",
+            "independent submission stream" => "independent",
+            "editorial" => "editorial", "rfc editor" => "editorial",
+            "rfc-editor" => "editorial"
+          }.freeze
+
+          # Latin letters with no NFKD decomposition, which would otherwise be
+          # dropped outright ("Sørensen" -> "Srensen").
+          TRANSLITERATIONS = {
+            "æ" => "ae", "Æ" => "AE", "œ" => "oe", "Œ" => "OE",
+            "ø" => "o", "Ø" => "O", "ß" => "ss", "ẞ" => "SS",
+            "đ" => "d", "Đ" => "D", "ð" => "d", "Ð" => "D",
+            "þ" => "th", "Þ" => "Th", "ł" => "l", "Ł" => "L",
+            "ħ" => "h", "Ħ" => "H", "ŋ" => "ng", "Ŋ" => "NG",
+            "ŧ" => "t", "Ŧ" => "T", "ı" => "i", "ĸ" => "k"
+          }.freeze
+
+          def transform
+            model = ::Rfcxml::V3::Reference.new
+            model.anchor = create_anchor
+            model.target = create_target
+            model.stream = create_stream
+            model.front = create_front
+            model.refcontent = create_refcontent
+            model
+          end
+
+          private
+
+          # The released IETF renderer takes an HTML-typed uri as the reference
+          # target when there is no src (isodoc/ietf/references.rb), and the
+          # transformer does the same; match it here.
+          def target_types = %w[src HTML doi]
+
+          # anchor is mandatory in v3 and is an XML identifier, so fall back
+          # through every source the item has and never leave whitespace in it.
+          def create_anchor
+            sanitize_anchor(@anchor || @item.docnumber || derive_anchor ||
+                            @item.id)
+          end
+
+          def sanitize_anchor(anchor)
+            return nil if anchor.nil?
+
+            anchor.to_s.strip.gsub(/\s+/, ".")
+          end
+
+          # <front> needs a title and at least one author to be valid v3.
+          def create_front
+            front = super
+            front.title = compound_title || formattedref_title
+            front.author = [unknown_author] if Array(front.author).empty?
+            front
+          end
+
+          # The base emitter takes title[0], which on a multipart standard is
+          # the intro alone ("IT Security techniques"). A citation needs the
+          # whole compound, so prefer the composite title relaton builds, then
+          # the intro-main-part join, then whatever is first.
+          def compound_title
+            content = composite_title || joined_title ||
+              @item.title.first&.content
+            return nil if content.nil?
+
+            ::Rfcxml::V3::Title.new(content: plain_text(content))
+          end
+
+          def composite_title
+            @item.title.find { |t| t.type == "main" }&.content
+          end
+
+          def joined_title
+            parts = TITLE_PARTS.filter_map do |type|
+              @item.title.find { |t| t.type == type }&.content
+            end
+            parts.empty? ? nil : parts.join(" - ")
+          end
+
+          def formattedref_title
+            content = @item.formattedref&.content or return nil
+
+            ::Rfcxml::V3::Title.new(content: plain_text(content))
+          end
+
+          # v3 <title> is text-only, so inline markup a formattedref or title
+          # carries has to be flattened rather than escaped into the output.
+          def plain_text(content)
+            text = content.to_s
+            return text unless text.include?("<")
+
+            Nokogiri::XML.fragment(text).text.squeeze(" ").strip
+          end
+
+          def unknown_author
+            ::Rfcxml::V3::Author.new(surname: "Unknown")
+          end
+
+          # One <seriesInfo> per (name, value): the same identifier can arrive
+          # from a docidentifier and a series, or from two docidentifiers that
+          # spell it differently ("RFC 2119" and "RFC2119").
+          def create_seriesinfo
+            (docidentifier_to_seriesinfo + series_to_seriesinfo +
+              identifier_to_seriesinfo).uniq { |si| [si.name, si.value] }
+          end
+
+          # Only series that carry a number can become <seriesInfo>; the rest
+          # are rendered as <refcontent>.
+          def series_to_seriesinfo
+            numbered_series.map do |ser|
+              ::Rfcxml::V3::SeriesInfo.new(name: series_title(ser).content,
+                                           value: ser.number)
+            end
+          end
+
+          def numbered_series
+            renderable_series.select(&:number)
+          end
+
+          # Series that are neither the stream marker nor a restatement of
+          # something already rendered from the document's identifiers. Only
+          # names actually emitted elsewhere are dropped: a series such as
+          # Internet-Draft still carries its number when no docidentifier
+          # supplies one.
+          def renderable_series
+            @item.series.reject { |ser| skip_series?(ser) }
+              .uniq { |ser| series_title(ser).content }
+          end
+
+          def skip_series?(ser)
+            return true if ser.type == "stream"
+
+            title = series_title(ser)
+            title.nil? || title.content.to_s == "DOI" ||
+              identifier_series_names.include?(title.content.to_s)
+          end
+
+          # Series names already covered by <seriesInfo> or <refcontent> built
+          # from the item's identifiers.
+          def identifier_series_names
+            @identifier_series_names ||=
+              identifier_to_seriesinfo.map(&:name) +
+              subseries_identifiers.map { |id| id.split.first }
+          end
+
+          def series_title(ser)
+            ser.title.find { |title| title.content.to_s != "DOI" }
+          end
+
+          # --- Identifiers ---
+
+          def identifier_to_seriesinfo
+            return [] unless home_standard?
+
+            authoritative_identifiers.filter_map { |id| id_to_seriesinfo(id) }
+          end
+
+          def id_to_seriesinfo(id)
+            name, value = split_identifier(id)
+            return nil unless name
+
+            # No `stream` attribute here: in v3 the stream is carried by the
+            # <stream> element, and duplicating it only adds noise.
+            ::Rfcxml::V3::SeriesInfo.new(name: name, value: value,
+                                         status: seriesinfo_status)
+          end
+
+          def split_identifier(id)
+            if (match = DRAFT_ID_RE.match(id))
+              ["Internet-Draft", match[:value]]
+            elsif (match = HOME_ID_RE.match(id))
+              [match[:name].upcase, match[:value]]
+            end
+          end
+
+          # An untyped docidentifier that merely restates the reference's own
+          # label ("ZELLER", "Grail") is a citation label, not a citation: keep
+          # it only when the reference would otherwise show nothing at all.
+          def label_echo?(docid)
+            return false unless docid.type.nil?
+
+            docid.content.to_s.casecmp(label_candidates.to_s).zero? &&
+              reference_has_visible_text?
+          end
+
+          def label_candidates
+            @item.docnumber || @item.id
+          end
+
+          def reference_has_visible_text?
+            @item.title.any? || @item.formattedref ||
+              @item.contributor.any? || @item.date.any?
+          end
+
+          def seriesinfo_status
+            @item.status&.stage&.content
+          end
+
+          def authoritative_identifiers
+            ids = subseries_identifiers + docidentifier_identifiers
+            ids.reject { |id| id.empty? || IGNORED_ID_RE.match?(id) }.uniq
+          end
+
+          def docidentifier_identifiers
+            @item.docidentifier.reject { |di| non_authoritative?(di) }
+              .map { |di| di.content.to_s.strip }
+          end
+
+          def non_authoritative?(docid)
+            NON_AUTHORITATIVE_TYPES.include?(docid.type) ||
+              EXCLUDED_ID_TYPES.include?(docid.type) ||
+              docid.scope == "trademark" ||
+              DRAFT_ANCHOR_RE.match?(docid.content.to_s) ||
+              label_echo?(docid)
+          end
+
+          def subseries_identifiers
+            @item.series.filter_map do |ser|
+              title = ser.title.find { |t| SUBSERIES.include?(t.content.to_s) }
+              "#{title.content} #{ser.number}" if title && ser.number
+            end
+          end
+
+          def home_standard?
+            @item.contributor.any? do |contrib|
+              org = contrib.organization or next false
+
+              ([org.abbreviation&.content] + org.name.map(&:content))
+                .compact.any? { |name| HOME_ORGS.include?(name.to_s) }
+            end
+          end
+
+          # --- refcontent ---
+
+          def create_refcontent
+            (identifier_refcontent + series_refcontent)
+              .map { |text| ::Rfcxml::V3::Refcontent.new(content: text) }
+          end
+
+          # Identifiers that cannot be expressed as <seriesInfo> — either
+          # because the document is not an IETF one, or because the identifier
+          # does not split into a series name and number.
+          # Whatever <seriesInfo> already states must not be repeated here,
+          # whichever route put it there.
+          def identifier_refcontent
+            ids = authoritative_identifiers.reject { |id| in_seriesinfo?(id) }
+            ids.empty? ? [] : [ids.join(", ")]
+          end
+
+          def in_seriesinfo?(id)
+            name, value = split_identifier(id)
+            return false if name.nil?
+
+            create_seriesinfo.any? { |si| si.name == name && si.value == value }
+          end
+
+          def series_refcontent
+            (renderable_series - numbered_series).filter_map do |ser|
+              text = ser.formattedref&.content&.to_s || series_description(ser)
+              text unless text.strip.empty?
+            end
+          end
+
+          def series_description(ser)
+            [series_title(ser)&.content, ser.run, ser.organization,
+             ser.place&.city, series_dates(ser)]
+              .map(&:to_s).reject(&:empty?).join(", ")
+          end
+
+          def series_dates(ser)
+            [ser.from, ser.to].compact.map(&:to_s).reject(&:empty?).join("-")
+          end
+
+          # --- stream ---
+
+          # Values outside the grammar (relaton-ietf also has "Legacy") have no
+          # valid representation, so they are dropped with a warning rather
+          # than emitted as invalid XML.
+          def create_stream
+            value = ext_stream || series_stream
+            return nil if value.nil?
+
+            stream = STREAMS[value.to_s.strip.downcase]
+            unless stream
+              Util.warn "Dropping stream `#{value}`: not an RFC XML v3 stream"
+            end
+            stream
+          end
+
+          def ext_stream
+            @item.ext.respond_to?(:stream) ? @item.ext.stream : nil
+          end
+
+          def series_stream
+            ser = @item.series.find { |s| s.type == "stream" }
+            ser && ser.title.first&.content
+          end
+
+          # --- Contributors ---
+
+          # Every relaton-ietf RFC record carries publisher and authorizer
+          # contributors, and published RFC XML never lists those as authors.
+          # So: authors and editors if there are any, and only otherwise fall
+          # back to the wider set, which keeps a translator-only monograph its
+          # translator (metanorma-ietf#301).
+          def contributors_for_authors
+            contribs = super
+            primary = contribs.select { |c| role?(c, %w[author editor]) }
+            primary.any? ? primary : contribs.select { |c| fallback_author?(c) }
+          end
+
+          def role?(contrib, types)
+            contrib.role.any? { |r| types.include?(r.type) }
+          end
+
+          # A contributor with no role at all is an author by default; that is
+          # how most non-IETF bibitems are written.
+          def fallback_author?(contrib)
+            contrib.role.empty? || role?(contrib, FALLBACK_ROLES)
+          end
+
+          # --- ascii folding ---
+
+          def create_authors
+            super.each do |author|
+              author.ascii_fullname = ascii(author.fullname)
+              author.ascii_surname = ascii(author.surname)
+              author.ascii_initials = ascii(author.initials)
+            end
+          end
+
+          def create_organization(contrib)
+            org = super or return nil
+
+            org.ascii = ascii(Array(org.content).join)
+            org
+          end
+
+          # Transliterate to bare ASCII: expand the letters above, then strip
+          # the combining marks NFKD leaves behind. "Nürk" -> "Nurk",
+          # "Ö." -> "O.", "Sørensen" -> "Sorensen".
+          def ascii(str)
+            return nil if str.nil?
+
+            folded = str.to_s.gsub(/[#{TRANSLITERATIONS.keys.join}]/,
+                                   TRANSLITERATIONS)
+              .unicode_normalize(:nfkd)
+              .encode("ASCII", invalid: :replace, undef: :replace, replace: "")
+            # Folding a non-Latin script leaves only the punctuation and
+            # spacing behind ("Νίκος Παπαδόπουλος" -> " "), which is worse than
+            # no attribute at all. Real transliteration is the caller's policy.
+            folded.match?(/[[:alnum:]]/) ? folded : nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/relaton/bib/converter/bibxml.rb

@@ -1,5 +1,7 @@
 require_relative "bibxml/to_rfcxml"
 require_relative "bibxml/to_rfcxml_referencegroup"
+require_relative "bibxml/to_rfcxml_v3"
+require_relative "bibxml/to_rfcxml_referencegroup_v3"
 require_relative "bibxml/from_rfcxml"
 require_relative "bibxml/from_rfcxml_referencegroup"
 
@@ -16,17 +18,27 @@ module Relaton
         RFCPREFIXES = %w[RFC BCP FYI STD].freeze
 
         # Forward: ItemData -> Rfcxml model
-        def self.from_item(item, include_keywords: true) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
-          if bcp?(item)
-            ToRfcxmlReferencegroup.new(
-              item, include_keywords: include_keywords
-            ).transform
-          else
-            ToRfcxml.new(
-              item, include_keywords: include_keywords
-            ).transform
+        #
+        # @param v3 [Boolean] emit strict RFC 7991 (xml2rfc v3) instead of the
+        #   BibXML shape the relaton data fetchers publish
+        # @param anchor [String, nil] anchor to use instead of the one derived
+        #   from the item's docnumber/docidentifier
+        def self.from_item(item, include_keywords: true, v3: false, anchor: nil) # rubocop:disable Naming/MethodParameterName
+          klass = if v3 then v3_converter(item)
+                  elsif bcp?(item) then ToRfcxmlReferencegroup
+                  else ToRfcxml
+                  end
+          klass.new(item, include_keywords: include_keywords,
+                          anchor: anchor).transform
+        end
+
+        def self.v3_converter(item)
+          if item.relation.any? { |rel| rel.type == "includes" }
+            ToRfcxmlReferencegroupV3
+          else ToRfcxmlV3
           end
         end
+        private_class_method :v3_converter
 
         def self.bcp?(item) # rubocop:disable Metrics/CyclomaticComplexity
           item.docnumber&.match(/^BCP/) ||

data/lib/relaton/bib/item_data.rb

@@ -19,8 +19,18 @@ module Relaton
       COLLECTION_WRITE_ONLY_ATTRIBUTES = %i[title abstract source relation].freeze
 
       ATTRIBUTES.each { |attr| attr_accessor attr }
-      COLLECTION_ATTRBUTES.each { |attr| attr_accessor attr }
-      COLLECTION_WRITE_ONLY_ATTRIBUTES.each { |attr| attr_writer attr }
+      COLLECTION_ATTRBUTES.each { |attr| attr_reader attr }
+
+      # Collections are always arrays. lutaml-model assigns every mapped
+      # attribute after building the instance, so an element absent from the
+      # XML would otherwise overwrite the [] set in #initialize with nil --
+      # `Item.from_xml` items then blew up in any consumer that iterated them,
+      # while `from_yaml` ones did not.
+      (COLLECTION_ATTRBUTES + COLLECTION_WRITE_ONLY_ATTRIBUTES).each do |attr|
+        define_method("#{attr}=") do |value|
+          instance_variable_set("@#{attr}", array(value))
+        end
+      end
 
       attr_reader :id, :docidentifier
 
@@ -28,10 +38,10 @@ module Relaton
         ATTRIBUTES.each { |attr| instance_variable_set("@#{attr}", args[attr]) }
 
         (COLLECTION_ATTRBUTES + COLLECTION_WRITE_ONLY_ATTRIBUTES).each do |attr|
-          instance_variable_set("@#{attr}", args[attr] || [])
+          instance_variable_set("@#{attr}", array(args[attr]))
         end
 
-        @docidentifier = args[:docidentifier] || []
+        @docidentifier = array(args[:docidentifier])
         self.schema_version = schema
         @id = args[:id]
         create_id
@@ -42,7 +52,7 @@ module Relaton
       end
 
       def docidentifier=(value)
-        @docidentifier = value || []
+        @docidentifier = array(value)
         create_id
       end
 
@@ -156,8 +166,10 @@ module Relaton
         Converter::Asciibib.from_item(self)
       end
 
-      def to_rfcxml
-        Converter::BibXml.from_item(self).to_xml
+      # @param opts [Hash] passed to {Converter::BibXml.from_item}; notably
+      #   `v3: true` for strict RFC 7991 output instead of BibXML.
+      def to_rfcxml(**)
+        Converter::BibXml.from_item(self, **).to_xml
       end
 
       def deep_clone

data/lib/relaton/bib/model/series.rb

@@ -1,7 +1,9 @@
 module Relaton
   module Bib
     class Series < Lutaml::Model::Serializable
-      attribute :type, :string, values: %w[main alt]
+      # "stream" carries an RFC publication stream; relaton-ietf already builds
+      # such series, and biblio.rng's SeriesType admits any string.
+      attribute :type, :string, values: %w[main alt stream]
       attribute :formattedref, Formattedref
       attribute :title, Title, collection: (1..)
       attribute :place, Place

data/lib/relaton/bib/version.rb

@@ -1,5 +1,5 @@
 module Relaton
   module Bib
-    VERSION = "2.1.7".freeze
+    VERSION = "2.1.8".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: relaton-bib
 version: !ruby/object:Gem::Version
-  version: 2.1.7
+  version: 2.1.8
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-31 00:00:00.000000000 Z
+date: 2026-09-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bibtex-ruby
@@ -171,6 +171,8 @@ files:
 - lib/relaton/bib/converter/bibxml/from_rfcxml_referencegroup.rb
 - lib/relaton/bib/converter/bibxml/to_rfcxml.rb
 - lib/relaton/bib/converter/bibxml/to_rfcxml_referencegroup.rb
+- lib/relaton/bib/converter/bibxml/to_rfcxml_referencegroup_v3.rb
+- lib/relaton/bib/converter/bibxml/to_rfcxml_v3.rb
 - lib/relaton/bib/hash_parser_v1.rb
 - lib/relaton/bib/item_data.rb
 - lib/relaton/bib/model/abstract.rb