relaton 3.0.0.pre.alpha.16 → 3.0.0.pre.alpha.18

data/lib/relaton/nist/hit_collection.rb

@@ -67,15 +67,32 @@ module Relaton
         # both sides of the equality, not only from the hits.
         parts << :stage if refid.stage
         compare_refid = refid.stage ? refid.exclude(:stage) : refid
-        arr = @array.select do |item|
-          pubid = ::Pubid::Nist::Identifier.parse(item.hit[:code])
-          pubid.exclude(*parts) == compare_refid
-        rescue StandardError
-          item.hit[:code] == ref
+        # A stage-typed row exists now (the CSRC supplement): when the
+        # reference names a stage and a hit carries it, the exact-stage
+        # match wins outright — the stage-excluded comparison below stays
+        # as the family fallback for stages the dataset still lacks.
+        exact = []
+        if refid.stage
+          exact = @array.select do |item|
+            ::Pubid::Nist::Identifier.parse(item.hit[:code]) == refid
+          rescue StandardError
+            false
+          end
+        end
+        arr = exact
+        if exact.empty?
+          arr = @array.select do |item|
+            pubid = ::Pubid::Nist::Identifier.parse(item.hit[:code])
+            pubid.exclude(*parts) == compare_refid
+          rescue StandardError
+            item.hit[:code] == ref
+          end
         end
       rescue StandardError
         arr = @array.select { |item| item.hit[:code] == ref }
       ensure
+        # The ensure is the one exit, so every branch sets arr: a `return`
+        # before it is overridden here (relaton#314).
         dup = self.dup
         dup.array = arr
         return dup
@@ -108,6 +125,76 @@ module Relaton
         parts
       end
 
+      # The id of a pubs-export row: from its DOI (or its docidentifier),
+      # with the stage and the update its uri carries. A class method, so the
+      # scraper derives a related row's id the same way.
+      #
+      # @param json [Hash] pubs-export row
+      # @return [String]
+      def self.pubs_export_id(json) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
+        if json && json["doi"]
+          json["doi"].sub(/^10.6028\//, "")
+        else
+          json["docidentifier"]
+        end => id
+
+        # Not sub!: the row belongs to the shared PubsExport data.
+        id = id.sub(/(?:-draft\d*|\.\wpd)$/, "")
+        id = id.gsub(".", " ").sub(/-Add(\d*)$/, ' Add.\1') if id.match?(/-Add\d*$/)
+        # Normalize to space-separated form so pubid 2.x parses as
+        # parsed_format=:short and renders without dots; also force the
+        # "NIST " prefix so publisher_was_parsed is set.
+        parse_input = id.gsub(/\bNIST\./, "NIST ")
+        parse_input = "NIST #{parse_input}" unless parse_input.start_with?("NIST ")
+        pid = ::Pubid::Nist::Identifier.parse(parse_input)
+
+        # Canonicalize edition spelling: DOI-derived codes are already short
+        # ("…r2"), but no-DOI drafts come from the verbose docidentifier
+        # ("… Rev. 2") and pubid preserves that spelling via original_prefix.
+        # Drop it so every code renders the canonical short form.
+        pid.edition.original_prefix = nil if pid.respond_to?(:edition) && pid.edition
+
+        # Stage: URI is authoritative, fall back to iteration. "final" => no stage.
+        uri_stage = json["uri"] && json["uri"][%r{/(final|ipd|fpd|\dpd)(?:-\(\d+\))?(?:/|$)}, 1]
+        stage_src = uri_stage || json["iteration"]
+        case stage_src
+        when nil, "final"
+          # no stage — "final" means published
+        when "fpd"
+          pid.stage = ::Pubid::Nist::Components::Stage.new id: "f", type: "pd"
+        when /\A(\w)pd\z/
+          pid.stage = ::Pubid::Nist::Components::Stage.new id: Regexp.last_match(1), type: "pd"
+        end
+
+        /\/upd(?<upd>\d+)\// =~ json["uri"]
+        # In pubid 2.x render paths the Update is read from
+        # update_component (Components::Update), not the legacy :update
+        # slot — assigning to :update would render as "-upd/Upd2" via the
+        # elsif fallback path in Base#to_short_style.
+        pid.update_component = ::Pubid::Nist::Components::Update.new(number: upd) if upd
+        pid.to_s
+      rescue StandardError
+        id += " #{json["iteration"]}" if json["iteration"] && json["iteration"] != "final"
+        id
+      end
+
+      #
+      # Build hit data from a CSRC pubs-export row. Shared with
+      # DataFetcher#fetch_csrc, so a crawled row and a runtime hit carry the
+      # same code.
+      #
+      # @param json [Hash] pubs-export row
+      #
+      # @return [Hash] hit data
+      #
+      def hit_data(json) # rubocop:disable Metrics/AbcSize
+        /(?<series>(?<=-)\w+$)/ =~ json["series"]
+        title = [json["title-main"], json["title-sub"]].compact.join " - "
+        release_date = parse_date(json["published-date"], str: false)
+        { code: pubs_export_id(json), series: series.upcase, title: title, url: json["uri"],
+          status: json["status"], release_date: release_date, json: json }
+      end
+
       private
 
       def code_parts(code) # rubocop:disable Metrics/MethodLength
@@ -196,22 +283,45 @@ module Relaton
       # @return [self] sorted hits collection
       #
       def sort_hits!
+        ref_stage = begin
+          st = ::Pubid::Nist::Identifier.parse(@reference)&.stage
+          st && st.id.to_s + st.type.to_s # the feed iteration form ("ipd")
+        rescue StandardError
+          nil
+        end
         @array.sort! do |a, b|
+          # A stage-carrying reference prefers the hit whose stage matches
+          # (the ipd draft sorts before the final it drafts for); a
+          # stage-less reference keeps the stage-less hits first (relaton#146).
+          cmp = hit_stage_rank(a, ref_stage) <=> hit_stage_rank(b, ref_stage)
+          next cmp unless cmp.zero?
+
           base_a, upd_a = base_and_update(a.hit[:code])
           base_b, upd_b = base_and_update(b.hit[:code])
 
-          cmp = base_a <=> base_b
+          cmp = base_a.to_s <=> base_b.to_s
           next cmp unless cmp.zero?
 
           # Same base code: prefer higher /UpdN (latest update wins).
           cmp = upd_b <=> upd_a
           next cmp unless cmp.zero?
 
-          b.hit[:release_date] <=> a.hit[:release_date]
+          cmp = b.hit[:release_date] <=> a.hit[:release_date]
+          next cmp unless cmp
+          cmp
         end
         self
       end
 
+      # The hit's stage id ("i" of an ipd, "f" of an fpd), or nil for a
+      # stage-less code. A parse failure reads as stage-less.
+      def hit_stage_rank(hit, ref_stage)
+        # The stage the hit carries: the CSRC feed's iteration field ("ipd",
+        # "fpd", "2pd") — the code itself strips stage suffixes.
+        hit_stage = hit.hit[:json].is_a?(Hash) ? hit.hit[:json]["iteration"] : nil
+        hit_stage == ref_stage ? 0 : 1 # rank 0 = the stage the reference names
+      end
+
       # Split a code like "NIST FIPS 140-2/Upd2" into ["NIST FIPS 140-2", 2].
       # Codes without an update suffix return update 0.
       def base_and_update(code)
@@ -285,61 +395,13 @@ module Relaton
       #
       # @return [Array<Relaton::Nist::Hit>] hits
       #
-      def from_json # rubocop:disable Metrics/AbcSize
+      def from_json
         Util.info "Fetching from csrc.nist.gov ...", key: @reference
-        select_data.map do |h|
-          /(?<series>(?<=-)\w+$)/ =~ h["series"]
-          title = [h["title-main"], h["title-sub"]].compact.join " - "
-          release_date = parse_date(h["published-date"], str: false)
-          Hit.new({ code: pubs_export_id(h), series: series.upcase, title: title, url: h["uri"],
-                    status: h["status"], release_date: release_date, json: h }, self)
-        end
+        select_data.map { |h| Hit.new(hit_data(h), self) }
       end
 
-      def pubs_export_id(json) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/MethodLength
-        if json && json["doi"]
-          json["doi"].sub(/^10.6028\//, "")
-        else
-          json["docidentifier"]
-        end => id
-
-        id.sub!(/(?:-draft\d*|\.\wpd)$/, "")
-        id = id.gsub(".", " ").sub(/-Add(\d*)$/, ' Add.\1') if id.match?(/-Add\d*$/)
-        # Normalize to space-separated form so pubid 2.x parses as
-        # parsed_format=:short and renders without dots; also force the
-        # "NIST " prefix so publisher_was_parsed is set.
-        parse_input = id.gsub(/\bNIST\./, "NIST ")
-        parse_input = "NIST #{parse_input}" unless parse_input.start_with?("NIST ")
-        pid = ::Pubid::Nist::Identifier.parse(parse_input)
-
-        # Canonicalize edition spelling: DOI-derived codes are already short
-        # ("…r2"), but no-DOI drafts come from the verbose docidentifier
-        # ("… Rev. 2") and pubid preserves that spelling via original_prefix.
-        # Drop it so every code renders the canonical short form.
-        pid.edition.original_prefix = nil if pid.respond_to?(:edition) && pid.edition
-
-        # Stage: URI is authoritative, fall back to iteration. "final" => no stage.
-        uri_stage = json["uri"] && json["uri"][%r{/(final|ipd|fpd|\dpd)(?:-\(\d+\))?(?:/|$)}, 1]
-        stage_src = uri_stage || json["iteration"]
-        case stage_src
-        when nil, "final"
-          # no stage — "final" means published
-        when "fpd"
-          pid.stage = ::Pubid::Nist::Components::Stage.new id: "f", type: "pd"
-        when /\A(\w)pd\z/
-          pid.stage = ::Pubid::Nist::Components::Stage.new id: Regexp.last_match(1), type: "pd"
-        end
-
-        /\/upd(?<upd>\d+)\// =~ json["uri"]
-        # In pubid 2.x render paths the Update is read from
-        # update_component (Components::Update), not the legacy :update
-        # slot — assigning to :update would render as "-upd/Upd2" via the
-        # elsif fallback path in Base#to_short_style.
-        pid.update_component = ::Pubid::Nist::Components::Update.new(number: upd) if upd
-        pid.to_s
-      rescue StandardError
-        id += " #{json["iteration"]}" if json["iteration"] && json["iteration"] != "final"
-        id
+      def pubs_export_id(json)
+        self.class.pubs_export_id json
       end
 
       #

data/lib/relaton/nist/scraper.rb

@@ -105,16 +105,16 @@ module Relaton
         # Fetch dates
         # @param doc [Hash]
         # @param release_date [Date]
-        # @return [Array<Bib::Date>]
+        # @return [Array<Date>]
         def fetch_dates(doc, release_date) # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
-          dates = [Bib::Date.new(type: "published", at: release_date.to_s)]
+          dates = [Date.new(type: "published", at: release_date.to_s)]
 
           issued = safe_parse_date doc["issued-date"]
           updated = safe_parse_date doc["updated-date"]
-          dates << Bib::Date.new(type: "updated", at: updated.to_s) if updated
+          dates << Date.new(type: "updated", at: updated.to_s) if updated
           obsoleted = safe_parse_date doc["obsoleted-date"]
-          dates << Bib::Date.new(type: "obsoleted", at: obsoleted.to_s) if obsoleted
-          dates << Bib::Date.new(type: "issued", at: issued.to_s) if issued
+          dates << Date.new(type: "obsoleted", at: obsoleted.to_s) if obsoleted
+          dates << Date.new(type: "issued", at: issued.to_s) if issued
           dates
         end
 
@@ -247,14 +247,28 @@ module Relaton
         def fetch_relations_json(hit) # rubocop:disable Metrics/AbcSize
           doc = hit[:json]
           relations = doc["supersedes"].map do |r|
-            doc_relation "supersedes", hit[:code], r["uri"]
+            doc_relation "supersedes", related_id(r, hit), r["uri"]
           end
 
           relations + doc["superseded-by"].map do |r|
-            doc_relation "updates", hit[:code], r["uri"]
+            doc_relation "updates", related_id(r, hit), r["uri"]
           end
         end
 
+        # The related document's own id. The hit's code is the record's own
+        # id, and a relation that names it points the record at itself. The
+        # entry's docidentifier drops the update and the part ("SP 800-162"
+        # for each of 800-162, /Upd1 and /Upd2), so derive the id the way the
+        # record's own is derived: from the related feed row (its DOI), or
+        # from the entry's uri when the feed lacks that row.
+        def related_id(rel, hit)
+          row = PubsExport.instance.data.find { |d| d["uri"] == rel["uri"] }
+          return HitCollection.pubs_export_id(row) if row
+          return hit[:code] if rel["docidentifier"].to_s.strip.empty?
+
+          HitCollection.pubs_export_id(rel)
+        end
+
         # @param type [String]
         # @param ref [String]
         # @param uri [String]

data/lib/relaton/oasis/CLAUDE.md

@@ -0,0 +1,251 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+relaton-oasis is a Ruby gem for retrieving and serializing OASIS Standards bibliographic metadata. It is part of the Relaton family of gems and implements the IsoBibliographicItem model for OASIS standards. Uses the lutaml-model pattern on the `lutaml-integration` branch.
+
+## Commands
+
+```bash
+bundle exec rake spec       # Run all tests (default rake task)
+bundle exec rake rubocop    # Run linter
+bundle exec rspec           # Run tests directly
+bundle exec rspec spec/relaton/oasis/bibitem_spec.rb  # Run a single test file
+bin/console                 # Interactive IRB with gem loaded
+```
+
+## Architecture
+
+### Class Hierarchy (under `Relaton::Oasis`)
+
+All model classes use the lutaml-model pattern from `relaton-bib`:
+
+- **ItemData** (`lib/relaton/oasis/item_data.rb`) — Data model class extending `Bib::ItemData`
+- **Item** (`lib/relaton/oasis/item.rb`) — Base class extending `Bib::Item`, uses `ItemData` model, adds `ext` attribute of type `Ext`
+- **Bibitem** (`lib/relaton/oasis/bibitem.rb`) — Extends `Item`, includes `Bib::BibitemShared` for individual bibliography entries
+- **Bibdata** (`lib/relaton/oasis/bibdata.rb`) — Extends `Item`, includes `Bib::BibdataShared` for complete bibliography records
+- **Ext** (`lib/relaton/oasis/ext.rb`) — Extends `Bib::Ext`, OASIS-specific metadata: `doctype`, `technology_area`, `schema_version`
+- **Doctype** (`lib/relaton/oasis/doctype.rb`) — Extends `Bib::Doctype`, valid values: `specification`, `memorandum`, `resolution`, `standard`
+- **Docidentifier** (`lib/relaton/oasis/docidentifier.rb`) — Extends
+  `Bib::Docidentifier`, parses its `content` into a `Pubid::Oasis::Identifier`
+  exposed as `#pubid`; see **Identifiers and the index**
+
+### Bibliography (under `Relaton::Oasis`)
+
+- **Bibliography** (`lib/relaton/oasis/bibliography.rb`) — Module with `search`/`get` class methods for fetching OASIS standards from the relaton-data-oasis GitHub repository. Delegates to private methods: `find_index_entry`, `fetch_yaml`, `parse_item`
+
+### Data Fetching (under `Relaton::Oasis`)
+
+These classes scrape https://www.oasis-open.org/standards/ to produce YAML/XML data files. Loaded separately via `require "relaton/oasis/data_fetcher"`.
+
+- **DataFetcher** (`lib/relaton/oasis/data_fetcher.rb`) — Extends `Core::DataFetcher`, orchestrates fetching all OASIS standards
+- **DataParser** (`lib/relaton/oasis/data_parser.rb`) — Parses individual OASIS document nodes into `ItemData`
+- **DataPartParser** (`lib/relaton/oasis/data_part_parser.rb`) — Parses multi-part OASIS document nodes into `ItemData`
+- **DataParserUtils** (`lib/relaton/oasis/data_parser_utils.rb`) — Shared module included by both parsers; provides contributor parsing, docid construction, retry logic, and doctype detection
+
+### Identifiers and the index
+
+#### Pubid-backed docidentifier
+
+`Relaton::Oasis::Docidentifier` parses its `content` into a
+`Pubid::Oasis::Identifier` kept in `@pubid`, while the lutaml `content`
+attribute stays a plain **string** for serialization. Parsing is **soft**:
+`content=` lazily requires pubid and rescues `LoadError`/`StandardError`, so a
+missing gem or non-OASIS content leaves `@pubid` nil rather than raising. The
+stored content carries the `OASIS ` publisher token, which is
+`Pubid::Oasis::Identifier#to_s`'s default rendering, so a bare slug
+(`"amqp-core"`) is *not* an OASIS printed id and leaves `@pubid` nil.
+
+The scrapers still compose the slug by hand (`DataParserUtils#parse_docid`,
+`#parse_spec`, `#parse_part`, `#parse_errata`, `DataParser#title_to_docid`) —
+pubid parses the result, it does not replace those heuristics.
+
+**`remove_part!` / `remove_date!` / `to_all_parts!` stay the inherited no-ops,
+deliberately.** `Pubid::Oasis::Renderer` echoes the verbatim slug held in
+`original`, so clearing `part`, `version` or `stage` cannot change the printed
+id — the mutation would be invisible — and rewriting `original` would invent a
+reference form OASIS does not publish. OASIS slugs are free-form with an
+inconsistent internal structure, and no OASIS citation drops a part or a
+version; there is no "all parts" or "most recent" spelling to render. Since
+`dfbd26c72` those defaults are no-ops rather than `NotImplementedError` raises,
+so `Bib::ItemData#to_all_parts` and `#to_most_recent_reference` return the item
+unchanged instead of blowing up. Do not "finish" this class by adding them.
+(Contrast `Relaton::Ogc::Docidentifier`, whose components really do render.)
+
+#### `index-v2`, written and read
+
+`INDEXFILE = "index-v2"` is the only index this flavor touches: pubid-keyed
+rows (`_type: pubid:oasis:standard`), published by `relaton-data-oasis` on its
+`v2` branch — the same branch `Bibliography::ENDPOINT` reads.
+
+The producer and the consumer pass `pubid_class: ::Pubid::Oasis::Identifier`:
+
+| Call site | Why it needs `pubid_class:` |
+|---|---|
+| `DataFetcher#index` | `FileIO#save` calls `to_hash` only for instances of it — without it the crawl writes v1-shaped rows under a v2 name, silently |
+| `Bibliography#index` | without it the rows stay raw hashes, `FileIO#sorted` is false, and every lookup scans all 605 rows |
+
+`Processor#remove_index_file` passes `url: true` and `file:`, and no
+`pubid_class:`: the delete never reads the index (see
+`lib/relaton/index/CLAUDE.md`). It used to omit `url: true`, so `Db#clear` on an
+empty pool deleted `./index-v2.yaml` in the working directory and kept the
+cache.
+
+`Bibliography#index` also passes `file:`, which the pre-migration code omitted.
+`file:` names the cache file (`Type` falls back to `index.yaml` without it), so
+the consumer and `remove_index_file` must pass the same one, or `Db#clear`
+leaves the consumer's cache in place.
+
+**This gem never writes `index-v1`.** `relaton-data-oasis`'s crawler derives it
+from the v2 rows, for relaton v2 consumers only.
+
+#### Resolving a reference
+
+`Bibliography#find_index_entry` is the pubid `best_match` shape:
+
+- **`#parse_ref` supplies the publisher token.** An OASIS printed id starts
+  with `OASIS `, and pubid's grammar requires it, but callers write bare slugs
+  (`mqtt-v5.0`) and `Db#fetch` passes the reference through verbatim. Adding
+  the token is normalization, not identification, so it happens in the flavor —
+  the same place W3C normalizes a URL or a leading `TR-`.
+- **The parsed pubid is passed to `Type#search`, never the string.** Search
+  narrows only for a non-`String` argument, so passing text would disable the
+  binary search however the index was built. `pubid_class:` alone fixes
+  nothing; both had to change together.
+- **Selection is pubid's asymmetric subset match** (`Pubid::SubsetMatch`):
+  `pubid === row[:id]`, the reference on the left. A component the reference
+  omits (`version`, `stage`, `part`, `label`) matches any value; a component it
+  states must be equal. `number` is always stated: it is the specification name,
+  the whole identity of an OASIS record and the key the index bsearches on.
+  `#ignored` survives only for `#ranking_key`, which counts the components the
+  caller did not ask for. Measured over the whole fixture index (605 rows,
+  6,795 comparisons): the subset match and the old
+  `matches?(…, ignore: #ignored)` agree on every pair.
+- **There is no substring fallback.** After normalization the only unparseable
+  inputs are a blank string and one over pubid's 1000-character cap, and a
+  substring scan for `""` matches every row — worse than a miss. An
+  unparseable reference raises `Pubid::Errors::ParseError`
+  (`spec/oasis/relaton/oasis/bibliography_spec.rb` pins it), so a malformed
+  identifier stays distinct from an absent document.
+
+##### Ordering: `#ranking_key`
+
+Ignoring a component means "don't care", so a loose reference also matches the
+more specific rows. The key, in order: an **exact printed id**; then the
+**newest version**, segments compared as integers; then the **least specific**
+row; then the **later stage revision** (digits only — OASIS stage letters have
+no ranking this code may invent); then the printed id, so the result never
+depends on index order.
+
+The exact-match rule is not decoration. Five records are a bare specification
+name that also has versioned siblings — `OASIS EDXL`, `OData`, `OSLC`, `SAML`,
+`WSS` — and without it three of them answered with their newest sibling instead
+of themselves. Published ids are unique (0 duplicates in 605 rows), so at most
+one row can score there.
+
+Verified over the whole published index: **all 605 ids resolve to their own
+record**, with and without the publisher token.
+
+##### One behaviour is deliberately lost
+
+v1 matched by substring, so `OASIS amqp` resolved to some `amqp-core` record.
+v2 matches identifiers, so a partial specification name no longer resolves.
+That is the same semantic change IANA recorded, and
+`spec/oasis/relaton/oasis/bibliography_spec.rb` asserts it so it stays a
+decision rather than a surprise.
+
+#### Unparseable ids are reported, in two places on purpose
+
+`DataFetcher#add_to_index` indexes `docid.pubid` and, when it is nil, records
+the reason in `@errors` and skips the row rather than indexing it unparsed:
+`Relaton::Index` rejects the WHOLE index if a single row fails to deserialize,
+and its sort calls `.root.number` on every id. The data file is still written,
+so a document is unindexed, never lost.
+
+`DataParserUtils#record_unparseable_id` records the **same** thing at the moment
+the id is built. That is not redundant: the part ids that only ever become a
+relation's `formattedref` (`DataParser#parse_relation`,
+`DataPartParser#parse_relation`) never reach `save_doc`, so an index-time hook
+alone cannot see them. Both entries are keyed on the **id string**, so a
+document that is saved reports one line — the fetcher's, which also names the
+output file. Keep the two keys identical.
+
+Both routes rely on `Core::DataFetcher#report_errors` treating a **String**
+value in `@errors` as the message, logged verbatim at `:error`, which is the
+level the `GhIssue` channel subscribes to. So each entry becomes one line of the
+crawl's "Error fetching documents" GitHub issue, and the key serves only to
+de-duplicate. W3C and 3GPP use exactly this `@errors` route; ISO, ITU and NIST
+reach the same issue through a side list plus a `report_errors` override.
+OASIS is the only flavor that also records from its parser, for the
+`formattedref` reason above.
+
+#### The index key
+
+`Index::Type#candidates_by_number` bsearches on `id.root.number.to_s`, and
+`FileIO` sorts by that same key. `Pubid::Oasis::Identifier#number` holds the
+**specification name** — "OSLC-CoreShapes", "STIX", "amqp-core" — so every
+version, stage and part of one specification shares a bucket, the same shape as
+an IETF draft slug or an IANA registry slug.
+
+This needed a pubid change: the attribute was called `spec` and `number` was
+never set, so every row keyed on `""` — one bucket, bsearch degraded to a
+linear scan, silently, exactly the IANA and W3C trap. pubid `cfe8ee84` renames
+it, with **no alias**, and it ships in the released `2.0.0.alpha.10` that
+`relaton.gemspec` pins — so this flavor needs nothing from the `Gemfile`'s
+temporary pubid `main` pin, unlike the nine listed there.
+`spec/oasis/relaton/oasis/pubid_contract_spec.rb` is the standing guard: it
+fails against any pubid that does not set `number`.
+
+The flavor is indifferent to pubid's parse-failure class, which moved twice
+during this work — `RuntimeError`, then `Parslet::ParseFailed`, and in
+alpha.10 `Pubid::Errors::ParseError` (a `Parslet::ParseFailed`) with
+`Pubid::Errors::InvalidInputError` (an `ArgumentError`) for a non-String or an
+over-long input. `Docidentifier#content=` and `Bibliography#parse_ref` both
+rescue `StandardError`, which every one of those descends from.
+
+Measured over all 605 published rows, written through
+`Relaton::Oasis::Docidentifier` into a `pubid_class:`-configured index and read
+back: 605 rows round-trip byte-identically, 0 unparseable, 0 keying on `""`,
+309 buckets with the largest 25, and a `STIX` lookup narrows to 25 of 605.
+
+### Serialization
+
+Supports XML (with RELAX NG schema validation via `grammars/`) and YAML round-trip serialization. Classes use `from_xml`/`to_xml` and `from_yaml`/`to_yaml` class methods inherited from the lutaml-model base.
+
+### Test Conventions
+
+Tests are round-trip based: parse a fixture file, serialize back, and compare output to input. XML tests also validate against the RELAX NG schema (`../../grammar/relaton-oasis-compile.rng`) using the `ruby-jing` gem — so the suite needs a Java runtime on `PATH`. Fixtures live in `spec/oasis/fixtures/`. VCR cassettes record HTTP interactions in `spec/oasis/vcr_cassettes/`. Private methods are tested via `send(:method_name, ...)`.
+
+## Style
+
+RuboCop config inherits from the Ribose OSS style guide. Target Ruby version: 3.4. Rails cops are required but disabled.
+
+## Testing
+
+Run the suite with `bundle exec rake spec:oasis` from the repo root; specs live
+in `spec/oasis/` and run self-contained (see the root `CLAUDE.md`).
+
+- **Index fixture:** `spec/oasis/fixtures/index-v2.zip` — the whole published
+  index (605 rows, verbatim), seeded into the `Relaton::Index` pool by
+  `spec/oasis/support/webmock.rb` in `before(:each)`, not only
+  `before(:suite)`: `Index::Pool#type` replaces the pooled entry whenever
+  `actual?` says no, and `DataFetcher#index` asks for the same `:oasis` type
+  with a `file:` and no `url:`. One producer example would otherwise evict the
+  fixture and send every later consumer example to a real download. The pool
+  key is `type.upcase.to_sym`, so `:oasis` is pooled as `:OASIS`.
+- It is built **with `pubid_class:`**, and `type.index` runs once offline to
+  force the deserialize and sort. Without that the suite would pass while
+  exercising something the runtime never does.
+- Refresh it with `bundle exec rake spec:update_index_oasis`
+  (`tasks/index_fixture_oasis.rb`), which copies the published rows verbatim
+  and refuses a v1 source rather than writing a fixture `Relaton::Index` would
+  reject wholesale.
+- **The fixture must be written with `File.binwrite`.** The zip entry comes
+  back `ASCII-8BIT`, and one published row carries a non-breaking space —
+  `OpenC2-MQTT-v1.0]<NBSP>-CS01`, a malformed upstream "cite as" that pubid
+  keeps verbatim in `original`. `File.write(..., encoding: "UTF-8")`
+  transcodes and raises `Encoding::UndefinedConversionError` on it. Same
+  invariant as `Index::FileStorage#write`; OGC's copy of this fixture code gets
+  away with the transcode only because its rows are pure ASCII.

data/lib/relaton/oasis/README.adoc

@@ -0,0 +1,132 @@
+= Relaton::Oasis: retrieve OASIS Standards for bibliographic use using the BibliographicItem model
+
+RelatonOasis is a Ruby gem that implements the https://github.com/metanorma/metanorma-model-iso#iso-bibliographic-item[IsoBibliographicItem model].
+
+You can use it to retrieve metadata of OASIS Standards from https://www.oasis-open.org/standards/ and access such metadata through the `Relaton::Oasis::ItemData` object.
+
+== Usage
+
+=== Get standard using reference.
+
+All the OASIS documents are parsed from https://www.oasis-open.org/standards/ and stored in a GitHub repository https://github.com/relaton/relaton-data-oasis. You can find all possible references on the index page https://relaton.github.io/relaton-data-oasis/.
+
+[source,ruby]
+----
+require 'relaton/oasis'
+=> true
+
+item = Relaton::Oasis::Bibliography.get "OASIS amqp-core"
+[relaton-oasis] INFO: (OASIS amqp-core) Fetching from Relaton repository ...
+[relaton-oasis] INFO: (OASIS amqp-core) Found: `OASIS amqp-core`
+=> #<Relaton::Oasis::ItemData:0x0000000120db0fa8
+...
+----
+
+=== XML serialization
+
+[source,ruby]
+----
+item.to_xml
+=> "<bibitem id="OASISamqpcore" type="standard" schema-version="v1.4.1">
+      <fetched>2026-02-27</fetched>
+      <title language="en" script="Latn" type="main">Advanced Message Queueing Protocol (AMQP) v1.0</title>
+      <docidentifier type="OASIS" primary="true">OASIS amqp-core</docidentifier>
+      ...
+    </bibitem>"
+----
+
+With argument `bibdata: true` it outputs XML wrapped by `bibdata` element and adds flavour `ext` element.
+
+[source,ruby]
+----
+item.to_xml bibdata: true
+=> "<bibdata type="standard" schema-version="v1.4.1">
+      <fetched>2026-02-27</fetched>
+      <title language="en" script="Latn" type="main">Advanced Message Queueing Protocol (AMQP) v1.0</title>
+      <docidentifier type="OASIS" primary="true">OASIS amqp-core</docidentifier>
+      ...
+      <ext schema-version="v1.0.1">
+        <doctype>standard</doctype>
+        <flavor>oasis</flavor>
+        <technology-area>Messaging</technology-area>
+      </ext>
+    </bibdata>"
+----
+
+=== Typed links
+
+Some OASIS documents have `src` type source link.
+
+[source,ruby]
+----
+item = Relaton::Oasis::Bibliography.get "OASIS amqp-core-types-v1.0-Pt1"
+[relaton-oasis] INFO: (OASIS amqp-core-types-v1.0-Pt1) Fetching from Relaton repository ...
+[relaton-oasis] INFO: (OASIS amqp-core-types-v1.0-Pt1) Found: `OASIS amqp-core-types-v1.0-Pt1`
+=> #<Relaton::Oasis::ItemData:0x0000000123ff12d8
+...
+
+item.source[0].type
+=> "src"
+
+item.source[0].content
+=> "http://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-types-v1.0-os.html"
+----
+
+=== Create bibliographic item from XML
+
+[source,ruby]
+----
+Relaton::Oasis::Item.from_xml File.read("spec/fixtures/oasis_bibdata.xml")
+=> #<Relaton::Oasis::ItemData:0x0000000123ffeb18
+...
+----
+
+=== Create bibliographic item from YAML
+[source,ruby]
+----
+Relaton::Oasis::Item.from_yaml File.read("spec/fixtures/item.yaml")
+=> #<Relaton::Oasis::ItemData:0x000000012119a290
+...
+----
+
+=== Fetch data
+
+The OASIS documents can be fetched from https://www.oasis-open.org/standards/ and converted into RelatonXML/BibXML/BibYAML formats:
+
+The method `Relaton::Oasis::DataFetcher.fetch(output: "data", format: "yaml")` fetches and converts all the documents from the https://www.oasis-open.org/standards/ and saves them to the `./data` folder in YAML format.
+
+Arguments:
+
+- `output` - folder to save documents (default './data').
+- `format` - the format in which the documents are saved. Possible formats are: `yaml`, `xml`, `bibxml` (default `yaml`).
+
+[source,ruby]
+----
+require "relaton/oasis/data_fetcher"
+
+Relaton::Oasis::DataFetcher.fetch
+Started at: 2022-03-18 18:34:06 +0100
+Stopped at: 2022-03-18 18:34:12 +0100
+Done in: 5 sec.
+=> nil
+----
+
+=== Logging
+
+RelatonOasis 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.
+
+== Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+The index test fixture used by the tests is `spec/oasis/fixtures/index-v2.zip`, a verbatim copy of the published `index-v2.zip` from the https://github.com/relaton/relaton-data-oasis[relaton-data-oasis] repository. Refresh it with `rake spec:update_index_oasis`.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/relaton/relaton-oasis.
+
+== License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).