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

data/lib/relaton/omg/README.adoc

@@ -0,0 +1,101 @@
+= Relaton::Omg
+
+RelatonOmg is a Ruby gem that searches and fetches standards from https://www.omg.org[The Object Management Group (OMG)].
+
+The standards are scraped from https://www.omg.org/spec
+
+== Usage
+
+=== Search document
+
+Reference format is `OMG + {ACRONYM} + {VERSION}`
+
+- `ACRONYM` is an acronym from the list of specs https://www.omg.org/spec/#all
+- `VERSION` (optional) if omitted then the latest version is fetched
+
+[source,ruby]
+----
+require 'relaton/omg'
+=> true
+
+item = Relaton::Omg::Bibliography.get 'OMG AMI4CCM 1.0'
+[relaton-omg] INFO: (OMG AMI4CCM 1.0) Fetching from www.omg.org ...
+[relaton-omg] INFO: (OMG AMI4CCM 1.0) Found: `OMG AMI4CCM 1.0`
+=> #<Relaton::Bib::ItemData:0x0000000128bf7650
+...
+
+# Return nil if the document doesn't exist.
+Relaton::Omg::Bibliography.get 'OMG 1111'
+[relaton-omg] INFO: (OMG 1111) Fetching from www.omg.org ...
+[relaton-omg] INFO: (OMG 1111) Not found.
+=> nil
+----
+
+=== Serialization
+
+[source,ruby]
+----
+item.to_xml
+=> "<bibitem id="OMGAMI4CCM10" schema-version="v1.4.1">
+      <fetched>2026-02-27</fetched>
+      <title language="en" script="Latn" type="main">Asynchronous Method Invocation for CCM</title>
+      <uri type="src">https://www.omg.org/spec/AMI4CCM/1.0/About-AMI4CCM</uri>
+      <uri type="pdf">https://www.omg.org/spec/AMI4CCM/1.0/PDF</uri>
+      <docidentifier type="OMG" primary="true">OMG AMI4CCM 1.0</docidentifier>
+      ...
+    </bibitem>"
+
+item.to_xml bibdata: true
+=>  "<bibdata schema-version="v1.4.1">
+      <fetched>2026-02-27</fetched>
+      <title language="en" script="Latn" type="main">Asynchronous Method Invocation for CCM</title>
+      <uri type="src">https://www.omg.org/spec/AMI4CCM/1.0/About-AMI4CCM</uri>
+      <uri type="pdf">https://www.omg.org/spec/AMI4CCM/1.0/PDF</uri>
+      <docidentifier type="OMG" primary="true">OMG AMI4CCM 1.0</docidentifier>
+      ...
+    </bibdata>"
+----
+
+=== Typed links
+
+OMG documents may have `src` and `pdf` link source types.
+
+[source,ruby]
+----
+item.source[0].type
+=> "src"
+
+item.source[0].content
+=> "https://www.omg.org/spec/AMI4CCM/1.0/About-AMI4CCM"
+----
+
+=== Create bibliographic item from XML
+
+[source,ruby]
+----
+xml = File.read 'spec/fixtures/omg_ami4ccm_1_0.xml', encoding: 'UTF-8'
+item = Relaton::Omg::Bibitem.from_xml xml
+=> #<Relaton::Bib::ItemData:0x00000001248f8c00
+...
+----
+
+=== Create bibliographic item from YAML
+[source,ruby]
+----
+yaml = File.read 'spec/fixtures/omg_ami4ccm_1_0.yaml', encoding: 'UTF-8'
+item = Relaton::Omg::Item.from_yaml yaml
+=> #<Relaton::Bib::ItemData:0x000000012813b180
+...
+----
+
+=== Logging
+
+RelatonOmg 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.
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/relaton/relaton-omg.
+
+== License
+
+The gem is available as open source under the terms of the https://opensource.org/licenses/MIT[MIT License].

data/lib/relaton/plateau/CLAUDE.md

@@ -0,0 +1,126 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+relaton-plateau is a Ruby gem for retrieving and managing bibliographic metadata for Project PLATEAU (Japanese 3D city model standards published by MLIT). It is part of the Relaton ecosystem of bibliographic gems.
+
+## Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rake spec
+
+# Run a single test file
+bundle exec rspec spec/relaton/plateau/bibitem_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/relaton/plateau/bibitem_spec.rb:15
+
+# Lint
+bundle exec rake rubocop
+
+# Default rake task (runs specs)
+bundle exec rake
+```
+
+## Architecture
+
+All code lives in `lib/relaton/plateau/`. The gem uses LutaML::Model::Serializable for data modeling with automatic XML/YAML serialization.
+
+### Models
+- **Item** (`item.rb`) — base Plateau item extending `Bib::Item`, declares `model ItemData` and adds `ext` attribute
+- **ItemData** (`item_data.rb`) — data class extending `Bib::ItemData`, returned by `Item.from_xml`, `Item.from_yaml`, and `Bibliography.get`
+- **Bibitem** (`bibitem.rb`) — bibliographic item variant (includes `Bib::BibitemShared`)
+- **Bibdata** (`bibdata.rb`) — bibliographic data variant (includes `Bib::BibdataShared`)
+- **Ext** (`ext.rb`) — extension element: doctype, subdoctype, flavor, editorialgroup, stagename, filesize, etc.
+- **Doctype** (`doctype.rb`) — extends `Bib::Doctype`, valid values: `handbook`, `technical-report`, `annex`
+
+### Retrieval & Data Fetching
+- **Bibliography** (`bibliography.rb`) — module with `get(code)` for index-based document retrieval, returns `ItemData`
+- **HitCollection** / **Hit** — search the relaton-data-plateau index and fetch YAML documents
+- **DataFetcher** (`data_fetcher.rb`) — extends `Core::DataFetcher`, scrapes MLIT JSON APIs for handbooks and technical reports
+- **Parser** / **HandbookParser** / **TechnicalReportParser** — parse JSON into `ItemData` objects
+- **Processor** (`processor.rb`) — standard Relaton processor plugin (`get`, `from_xml`, `from_yaml`, `fetch_data`, `grammar_hash`)
+
+### Serialization Methods
+- `bib.to_xml` — XML (bibitem format)
+- `Item.to_yaml(bib)` — YAML (class method)
+- `bib.to_rfcxml` — BibXML/RFC XML
+- `Item.from_xml(xml)` — parse XML into `ItemData`
+- `Item.from_yaml(yaml)` — parse YAML into `ItemData`
+
+### Data Sources
+- Handbooks: `https://www.mlit.go.jp/plateau/_next/data/1.3.0/libraries/handbooks.json`
+- Technical Reports: `https://www.mlit.go.jp/plateau/_next/data/1.3.0/libraries/technical-reports.json`
+- Pre-fetched index: `https://raw.githubusercontent.com/relaton/relaton-data-plateau/v2/` (`HitCollection::ENDPOINT`)
+
+### Pubid-backed index (index-v2)
+
+The index is **pubid-structured** (`_type: pubid:plateau:*` rows), mirroring
+NIST/CIE. The producer and the consumer `Relaton::Index.find_or_create` call
+sites (`data_fetcher.rb`, `hit_collection.rb`) pass
+`pubid_class: ::Pubid::Plateau::Identifier`, and `INDEXFILE = "index-v2"`.
+`processor.rb#remove_index_file` passes `url: true` and `file:` only: the delete
+never reads the index (see `lib/relaton/index/CLAUDE.md`).
+
+**Ids are pubid-canonical.** The parsers emit the form `Pubid::Plateau.parse`
+accepts, which also matches the MLIT source:
+- Handbook: `PLATEAU Handbook #NN 第X.Y版` (Japanese edition label — the parser
+  keeps the source `第X.Y版`; the Latinized `#edition` is retained only for the
+  structured `Bib::Edition`/`ext` fields).
+- Technical Report: `PLATEAU Technical Report #NN` (**no edition** — pubid TRs
+  carry none; the document still has a `1.0` `Bib::Edition`).
+- Sub-numbers use a hyphen (`#46-1`), not the source underscore (`#46_1`).
+
+`DataFetcher#save_document` parses the canonical id via `#pubid` (a round-trip
+guard: `from_hash(to_hash) == to_hash`) and stores the `Pubid::Plateau::Identifier`
+object; unparseable ids are warned and skipped (defensive — the parser already
+emits canonical, so nothing is expected to skip).
+
+**Search accepts both forms.** `HitCollection#find` parses the query via `#ref`
+(`Pubid::Plateau.parse`, memoized; an unparseable query **raises**
+`Pubid::Errors::ParseError`; `Bibliography.get` rescues transport errors only,
+as `Relaton::RequestError`, and `Hit#item` raises that same error on a
+non-200) and matches on **pubid objects**, mirroring the
+other pubid flavors: an exact edition uses `index.search(ref, exact: true)`
+(pubid `==` compares type + number + annex + edition); a family query
+(`ref.edition.nil?` — an edition-less handbook, or any Technical Report) uses
+the default subset match `ref === row`, where the omitted edition matches any
+value. pubid declares `annex` strict for PLATEAU (pubid#408), so
+`PLATEAU Handbook #03` does not reach the annex `#03-1`;
+`hit_collection_spec.rb` pins that against the index fixture. This keeps the
+family-vs-exact decision and the match on the *same* parsed identifier (no raw
+`@ref` regex). Canonical (`第1.0版`), edition-less (`#00`), and **legacy Latin**
+(`#00 1.0`) references all resolve — `Pubid::Plateau` normalizes Latin input to
+the canonical id (metanorma/pubid #269; needs the pubid `main` pin). No
+relaton-side Latin shim exists by design.
+
+`EDITION_SUFFIX` is **not** used for matching; it lives only in `#to_all_editions`,
+which strips the edition off the fetched document's `Bib::Docidentifier`/docnumber
+**strings** (relaton-bib content, not pubid) to build the family record — it
+matches both Japanese and Latin suffixes so it works against the current (Latin)
+VCR-cassette documents and future canonical ones.
+
+### Schema Validation
+RNG grammar files in `grammars/` define the XML schema. Tests validate fixtures against `relaton-plateau-compile.rng` using the `ruby-jing` gem.
+
+## Testing
+
+- **Index fixture:** `spec/fixtures/index-v2.zip` (pubid-backed, `_type: pubid:plateau:*` rows) is pre-loaded into the `Relaton::Index` pool in `before(:suite)` via a `Relaton::Index::Type` built with `::Pubid::Plateau::Identifier` (configured in `spec/support/webmock.rb`, mirroring NIST/CIE). Run `rake spec:update_index` to refresh from relaton-data-plateau.
+- RSpec with `expect` syntax (no monkey-patching)
+- VCR cassettes record HTTP interactions (in `spec/fixtures/vcr_cassettes/`)
+- `equivalent-xml` for XML comparison assertions
+- `jing` matcher for RNG schema validation
+- SimpleCov for code coverage
+
+## Key Conventions
+
+- Document identifiers are pubid-canonical: `PLATEAU Handbook #XX 第Y.Z版` (Japanese edition) or `PLATEAU Technical Report #XX` (no edition); sub-numbers use a hyphen (`#XX-N`). See "Pubid-backed index" above.
+- The gem supports multi-format serialization: XML, YAML, BibXML (RFC XML)
+- RuboCop follows Ribose OSS style guide; target Ruby version is 3.0
+- The `ext` element in XML/YAML carries PLATEAU-specific metadata (doctype, flavor, editorialgroup, etc.)

data/lib/relaton/plateau/README.adoc

@@ -0,0 +1,139 @@
+= Relaton::Plateau: retrieve Project PLATEAU Standards for bibliographic use using the ItemData model
+
+RelatonPlateau is a Ruby gem that implements the https://github.com/relaton/relaton-model-plateau[ItemData model].
+
+You can use it to retrieve metadata of Plateau Standards from the GitHub repository, and access such metadata through the `Relaton::Plateau::ItemData` object.
+
+== Usage
+
+=== Fetching
+
+==== Fetching Technical Reports
+
+[source,ruby]
+----
+require "relaton/plateau"
+
+Relaton::Plateau::Bibliography.get("PLATEAU Technical Report #00")
+[relaton-plateau] INFO: (PLATEAU Technical Report #00) Fetching ...
+[relaton-plateau] INFO: (PLATEAU Technical Report #00) Found `PLATEAU Technical Report #00 1.0`
+=> #<Relaton::Plateau::ItemData:0x00000001236204e8
+...
+----
+
+==== Fetching Handbooks unversioned
+
+[source,ruby]
+----
+Relaton::Plateau::Bibliography.get("PLATEAU Handbook #00")
+[relaton-plateau] INFO: (PLATEAU Handbook #00) Fetching ...
+[relaton-plateau] INFO: (PLATEAU Handbook #00) Found `PLATEAU Handbook #00`
+=> #<Relaton::Plateau::ItemData:0x00000001242bd200
+...
+----
+
+==== Fetching Handbooks versioned
+
+[source,ruby]
+----
+bib = Relaton::Plateau::Bibliography.get("PLATEAU Handbook #00 1.0")
+[relaton-plateau] INFO: (PLATEAU Handbook #00 1.0) Fetching ...
+[relaton-plateau] INFO: (PLATEAU Handbook #00 1.0) Found `PLATEAU Handbook #00 1.0`
+=> #<Relaton::Plateau::ItemData:0x0000000124157320
+...
+----
+
+=== Serializing
+
+==== XML
+
+[source,ruby]
+----
+puts bib.to_xml
+=> "<bibitem id="PLATEAUHandbook0010" type="standard" schema-version="v1.4.1">
+      <title language="en" script="Latn" type="main">PLATEAU Guidebook</title>
+      <uri type="pdf">https://www.mlit.go.jp/plateau/file/libraries/doc/plateau_doc_0000_ver01.pdf</uri>
+      <docidentifier type="PLATEAU" primary="true">PLATEAU Handbook #00 1.0</docidentifier>
+      ...
+    </bibitem>"
+
+puts bib.to_xml bibdata: true
+=> "<bibdata type="standard" schema-version="v1.4.1">
+      <title language="en" script="Latn" type="main">PLATEAU Guidebook</title>
+      <uri type="pdf">https://www.mlit.go.jp/plateau/file/libraries/doc/plateau_doc_0000_ver01.pdf</uri>
+      <docidentifier type="PLATEAU" primary="true">PLATEAU Handbook #00 1.0</docidentifier>
+      ...
+      <ext schema-version="v0.0.2">
+        <doctype>handbook</doctype>
+        <flavor>plateau</flavor>
+        <structuredidentifier type="Handbook">
+          <agency>PLATEAU</agency>
+          <docnumber>00</docnumber>
+          <edition>1.0</edition>
+        </structuredidentifier>
+        <filesize>18381880</filesize>
+      </ext>
+    </bibdata>"
+----
+
+==== YAML
+
+[source,ruby]
+----
+bib.to_yaml
+=> "---
+    id: PLATEAUHandbook0010
+    type: standard
+    schema_version: v1.4.1
+    ..."
+----
+
+=== Create from XML
+
+[source,ruby]
+----
+Relaton::Plateau::Item.from_xml File.read("spec/fixtures/handbook.xml")
+=> #<Relaton::Plateau::ItemData:0x0000000123b99118
+...
+----
+
+=== Create from YAML
+
+[source,ruby]
+----
+Relaton::Plateau::Item.from_yaml File.read("spec/fixtures/item.yaml")
+=> #<Relaton::Plateau::ItemData:0x00000001209fd208
+...
+----
+
+=== Fetching data
+
+Two datasets are available for fetching: `plateau-handbooks` and `plateau-technical-reports`. The format can be `xml`, `yaml`, or `bibxml`.
+
+[source,ruby]
+----
+require "relaton/plateau/data_fetcher"
+
+Relaton::Plateau::DataFetcher.fetch("plateau-handbooks", output: "dir", format: "xml")
+Started at: 2026-03-02 15:36:03 -0500
+Stopped at: 2026-03-02 15:36:04 -0500
+Done in: 1 sec.
+----
+
+== Logging
+
+RelatonPlateau uses https://github.com/relaton/relaton-logger[relaton-logger] for logging. By default, it logs to STDERR. To change the log level and output, use `Relaton.logger_pool` and `Relaton.logger`.
+
+== Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To update the index test fixture (used by tests), run `rake spec:update_index`. This downloads the latest `index-v2.zip` from the https://github.com/relaton/relaton-data-plateau[relaton-data-plateau] repository.
+
+== Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/relaton/relaton-plateau
+
+== License
+
+The gem is available as open source under the terms of the https://opensource.org/licenses/MIT[MIT license].

data/lib/relaton/sdo/CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+Dev notes for `Relaton::Sdo` — the SDO organization & logo store.
+
+## What this is
+
+A **non-flavor** component that answers metanorma#346 (central logo store) and
+its sister relaton-db#132 (map abbreviation → organisation name/translation).
+It is **not** a bibliographic flavor: it has **no processor**, **no
+`Db::Registry` entry**, and is not reachable from `Db#fetch`. It is a standalone
+top-level store, exposed through `Relaton.organization`.
+
+This deliberately honors the scope decision in `lib/relaton/db/CLAUDE.md`
+("org metadata … kept out of the processors"): nothing here touches a processor.
+The user's choice was to still surface it from the `relaton` gem itself (one
+`require`, one entry point) as a **lazily-autoloaded** component — referencing
+`Relaton::Sdo` or calling `Relaton.organization` is what loads it.
+
+## Public API
+
+```ruby
+org = Relaton.organization("ISO")   # case-insensitive; nil if unknown
+org.name                            # default (untranslated) name
+org.name("fr")                      # translation, or nil
+org.name(language: "fr")            # same, via the language: keyword
+org.logo_query(format:, size:, style:)  # all args optional → matching Logo list
+org.logo(format:, size:, style:)        # one Logo: nil if 0, the match if 1,
+                                        # raises Sdo::Error if the filter is ambiguous
+logo.content    # raw binary (lazy HTTP GET of logo.url, memoized)
+logo.data_uri   # "data:<mime>;base64,…"
+logo.save               # write to a filename derived from the URL; returns path
+logo.save("/path.eps")  # write to a custom path
+```
+
+## Data model & retrieval flow
+
+`Store` (singleton) lazily builds an index from a single **`index.yaml`**
+manifest served by the `relaton-data-sdo` data repo, and memoizes it (`reset!`
+drops the memo — used by specs). Shape:
+
+```yaml
+organizations:
+  ISO:
+    name:
+      - content: International Organization for Standardization   # default
+      - { language: fr, content: Organisation internationale de normalisation }
+    logo:
+      - { style: default, format: eps, size: 700x300, url: "https://…/iso.eps" }
+      - { style: red, format: svg, url: "https://…/red.svg",
+          applicability: "stage>=60" }   # opaque text; the store never interprets it
+```
+
+- **`style`** is the primary discriminator for multiple logos per org (e.g.
+  `default`, `red`, `grey`, `iso_1972`, `white_paper_2022`, BIPM `si_aspect_full`).
+- **`applicability`** (year/stage/doctype/cover-color rules) is carried through
+  verbatim and exposed; **selection is the consumer's job** (metanorma), not the
+  store's.
+
+`Config` (`Relaton::Sdo.configuration`) holds the index `url`, the cache
+`storage_dir` (default `~/.relaton/sdo`), the `storage` backend (defaults to
+`Relaton::Index::FileStorage`; swappable, e.g. S3), and the `ttl` (24 h).
+`Fetcher.fetch_index` serves a fresh on-disk copy within the TTL, re-downloads
+otherwise, and falls back to a stale cache if the network fails. A URL with no
+scheme (or `file://`) is read straight off disk — handy for fixtures/specs. Logo
+binaries are fetched on demand and memoized on the `Logo` (no disk cache yet).
+
+## Tests
+
+`spec/sdo/` is a self-contained suite (auto-discovered by `rake spec`). It uses
+WebMock to stub the index and logo URLs, points `storage_dir` at a fresh
+`Dir.mktmpdir` per example, and resets the store between examples. It
+`require "relaton"` because the public entry point (`Relaton.organization`)
+lives in the root entry file, which the shared spec_helper does not load.
+
+## Scope / not yet done
+
+- The real `relaton-data-sdo` data repo (assets + build GHA) — see
+  `HANDOFFS/relaton__relaton-data-sdo.md`. Until it publishes, `Config#url`
+  points at its (future) raw `index.yaml`.
+- No structured interpretation of `applicability`; no on-disk cache of logo
+  binaries; no writeback/authoring.

data/lib/relaton/un/CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+relaton-un is a Ruby gem that provides bibliographic data models for UN documents, part of the Relaton family of gems. It extends `relaton-bib` with UN-specific metadata using the LutaML-Model serialization framework. Currently on the `lutaml-integration` branch undergoing a major migration from the old `RelatonUn` namespace to `Relaton::Un`.
+
+## Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests (also the default rake task)
+bundle exec rake spec
+
+# Run a specific test file
+bundle exec rspec spec/relaton/un/bibitem_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/relaton/un/bibitem_spec.rb:7
+
+# Lint
+bundle exec rubocop
+
+# Interactive console with gem loaded
+bin/console
+```
+
+## Architecture
+
+### Flavor Model Pattern
+
+The gem follows the Relaton flavor pattern: base classes from `relaton-bib` (`Bib::Item`) are extended with a flavor-specific `Ext` class containing UN-specific metadata.
+
+```
+Bib::ItemData (from relaton-bib)
+  └── Relaton::Un::ItemData    # UN flavor identity, enables NamespaceHelper#namespace → Relaton::Un
+
+Bib::Item (from relaton-bib)
+  └── Relaton::Un::Item        # model ItemData; adds Ext attribute
+        ├── Relaton::Un::Bibitem   # includes Bib::BibitemShared (for <bibitem> XML)
+        └── Relaton::Un::Bibdata   # includes Bib::BibdataShared (for <bibdata> XML)
+```
+
+### Lookup
+
+`Bibliography.get` takes a String (`UN TRADE/CEFACT/2004/32`, the `UN ` token
+optional) or a parsed `Pubid::Un::Identifier`, which renders the document
+symbol without the token (`TRADE/CEFACT/2004/32`) — the form the UN data
+itself writes. Either becomes the symbol the search matches (`document_symbol`).
+`Relaton::Db` routes UN by the `UN ` prefix (`Registry#route` falls back to
+`class_by_ref`): `Pubid::Un` renders the symbol without the token, so a
+`UN …` reference is not an exact parse. A symbol without the token
+(`TRADE/CEFACT/2004/32`) is not routed at all — no flavor claims it — and
+raises `Relaton::UnknownReferenceError`. `Pubid::Un` also parses a bare DOI
+exactly (`10.6028/NIST.IR.8245`), but UN does not claim it (`10.` is a DOI
+prefix), so it does not route to UN either.
+
+### Key Classes (all in `lib/relaton/un/`)
+
+- **ItemData** — extends `Bib::ItemData`; the UN-specific data container used by `Item` via `model ItemData`
+- **Item** — extends `Bib::Item`, adds `ext` attribute of type `Ext`
+- **Bibitem / Bibdata** — extend Item with shared mixins for two XML serialization formats
+- **Ext** — UN-specific metadata: `doctype`, `distribution`, `session`, `submissionlanguage`, `job_number`; extends `Bib::Ext`
+- **Session** — session metadata (number, date, item numbers/names, collaborator, agenda_id)
+- **Doctype** — restricts document types to: recommendation, plenary, addendum, communication, corrigendum, reissue, agenda, budgetary, sec-gen-notes, expert-report, resolution
+
+### LutaML-Model Serialization
+
+All model classes use `Lutaml::Model::Serializable`. XML mappings are defined in `xml do` blocks:
+- `map_attribute` for XML attributes (e.g., `schema-version` → `schema_version`)
+- `map_element` for XML elements (e.g., `session-date` → `session_date`)
+- `collection: true` for array attributes
+- `values: [...]` for restricted string values
+
+### Schema Validation
+
+RelaxNG grammars in `grammars/` validate XML output. The compiled schema is `grammars/relaton-un-compile.rng`. Tests use `ruby-jing` for validation.
+
+### Testing Approach
+
+Tests are round-trip serialization tests: load a fixture, serialize to XML/YAML, compare against the original fixture. Bibitem and Bibdata specs also validate XML against the RelaxNG schema. Fixtures live in `spec/fixtures/`.
+
+## Dependencies
+
+- **relaton-bib** (~> 2.0.0-alpha.1) — base bibliographic model with LutaML-Model integration
+- **faraday** — HTTP client
+- **ruby-jing** (dev) — RelaxNG schema validation in tests
+- **equivalent-xml** (dev) — XML comparison in tests

data/lib/relaton/un/README.adoc

@@ -0,0 +1,125 @@
+= Relaton for UN documents
+
+RelatonUn 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 UN documents from https://documents.un.org, and access such metadata through the `Relaton::Un::Item` object.
+
+== Usage
+
+=== Search for a standard using keywords
+
+[source,ruby]
+----
+require 'relaton/un'
+=> true
+
+hits = Relaton::Un::Bibliography.search("TRADE/CEFACT/2004/32")
+=> <Relaton::Un::HitCollection:0x00000000001660 @ref=TRADE/CEFACT/2004/32 @fetched=false>
+
+item = hits[0].item
+=> #<Relaton::Un::Item:0x000000012385aa60
+...
+----
+
+=== XML serialization
+
+[source,ruby]
+----
+item.to_xml
+=> "<bibitem id="TRADECEFACT200432" type="standard" schema-version="v1.4.1">
+      <fetched>2026-03-03</fetched>
+      <title language="en" script="Latn" type="title-main"/>
+      <title language="en" script="Latn" type="main"/>
+      <uri type="pdf">https://documents.un.org/api/symbol/access?j=G0430683&amp;t=pdf</uri>
+      <docidentifier type="UN" primary="true">TRADE/CEFACT/2004/32</docidentifier>
+      <docnumber>TRADE/CEFACT/2004/32</docnumber>
+      <date type="published">
+        <on>2004-03-18</on>
+      </date>
+      <language>en</language>
+      <script>Latn</script>
+    </bibitem>"
+----
+With argument `bibdata: true` it outputs XML wrapped by `bibdata` element and adds flavor `ext` element.
+[source,ruby]
+----
+item.to_xml bibdata: true
+=> "<bibdata type="standard" schema-version="v1.4.1">
+      <fetched>2026-03-03</fetched>
+      <title language="en" script="Latn" type="title-main"/>
+      <title language="en" script="Latn" type="main"/>
+      <uri type="pdf">https://documents.un.org/api/symbol/access?j=G0430683&amp;t=pdf</uri>
+      <docidentifier type="UN" primary="true">TRADE/CEFACT/2004/32</docidentifier>
+      <docnumber>TRADE/CEFACT/2004/32</docnumber>
+      <date type="published">
+        <on>2004-03-18</on>
+      </date>
+      <language>en</language>
+      <script>Latn</script>
+      <ext schema-version="v1.0.0">
+        <distribution>general</distribution>
+        <session>
+          <number>10</number>
+          <agenda-id>12</agenda-id>
+        </session>
+        <job_number>G0430683</job_number>
+      </ext>
+    </bibdata>"
+----
+
+=== Get code, and year
+[source,ruby]
+----
+Relaton::Un::Bibliography.get "UN TRADE/CEFACT/2004/32"
+[relaton-un] INFO: (UN TRADE/CEFACT/2004/32) Fetching from documents.un.org ...
+[relaton-un] INFO: (UN TRADE/CEFACT/2004/32) Found: `TRADE/CEFACT/2004/32`
+=> #<Relaton::Un::ItemData:0x0000000127d9c448
+...
+----
+
+=== Typed links
+
+UN documens may have `pdf` and `word` source link types.
+
+[source,ruby]
+----
+item.source[0].type
+=> "pdf"
+
+item.source[0].content
+=> "https://documents.un.org/api/symbol/access?j=G0430683&t=pdf"
+----
+
+=== Create bibliographic item from XML
+[source,ruby]
+----
+Relaton::Un::Bibdata.from_xml File.read('spec/fixtures/bibdata.xml')
+=> #<Relaton::Bib::ItemData:0x000000012772a448
+...
+----
+
+=== Create bibliographic item from YAML
+[source,ruby]
+----
+Relaton::Un::Item.from_yaml File.read('spec/fixtures/item.yaml')
+=> #<Relaton::Un::ItemData:0x0000000127d7a140
+...
+----
+
+=== Logging
+
+RelatonUn 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.
+
+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 tags, 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/calconnect/relaton_un.
+
+== License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/relaton/version.rb

@@ -1,3 +1,3 @@
 module Relaton
-  VERSION = "3.0.0.pre.alpha.16".freeze
+  VERSION = "3.0.0.pre.alpha.18".freeze
 end