relaton-w3c 1.20.1 → 2.0.0.pre.alpha.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: beb3bb1a8550059e754f001412336b78ab55771f25ebf33534dd92f59a724b9d
-  data.tar.gz: d32d55f604c16613c04d5d2ad5554e7c7ed8c6151ad0218411c47d58099b5a63
+  metadata.gz: 52af233974b9c9185360e9ada6422f123a72afcd6b5115e8de0607b5c47b1443
+  data.tar.gz: 84fba2eb714b7fbd72a8bcb7f9321e910631b0243dc79c72c61caf4299eb296e
 SHA512:
-  metadata.gz: b2927bebbb35dde93cb2659b44e0ef47608ffa164ae33d138041a46139ca17b1a62061eb1055959fe91771bf397bf5ecb11f9ff2ca19055d7d804a65962a8974
-  data.tar.gz: 240f1c9f84770eb129a372a015b582c7f3ff6870eaf83e2dd723ff9538bbc19da34d58190234441b3c6b9dde224810e09c5e287473afa1183f23c53deabcc849
+  metadata.gz: 77b68bb94eabb98522c008426be7896adf324418d1990e0a26d201eee58562557cc60e7cc50d0f6ca567db3a0222f9e82ea7230d78345b5d73324a2db7128401
+  data.tar.gz: a9d22b86422dfcf55e761a7c44bd9ceec3ba5ad5ce48c076bfa820133c040bf2ba04dfe27624ffc68e6e57b0c7ec916c9645ecb6c1843f8c8ef333f507e8617f

data/.gitignore

@@ -14,3 +14,4 @@ Gemfile.lock
 .rubocop-https---raw-githubusercontent-com-riboseinc-oss-guides-master-ci-rubocop-yml
 .vscode/
 tr.rdf
+.claude/

data/.rubocop.yml

@@ -7,6 +7,6 @@ require: rubocop-rails
 inherit_from:
   - https://raw.githubusercontent.com/riboseinc/oss-guides/master/ci/rubocop.yml
 AllCops:
-  TargetRubyVersion: 2.7
+  TargetRubyVersion: 3.2
 Rails:
   Enabled: false

data/CLAUDE.md

@@ -0,0 +1,97 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+relaton-w3c is a Ruby gem for retrieving and representing W3C Standards bibliographic data using the Relaton model. It is part of the larger Relaton ecosystem of gems. Uses a LutaML-based model architecture under the `Relaton::W3c` namespace.
+
+## Common Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rake spec
+
+# Run a specific test file
+bundle exec rspec spec/relaton/w3c/item_spec.rb
+
+# Run a specific test by line number
+bundle exec rspec spec/relaton/w3c/item_spec.rb:7
+
+# Lint
+bundle exec rubocop
+
+# Interactive console
+bin/console
+```
+
+## Architecture
+
+### Class Hierarchy
+
+All classes live under `lib/relaton/w3c/` in the `Relaton::W3c` namespace:
+
+**Model classes:**
+- **`Item`** (`item.rb`) — extends `Bib::Item`, adds W3C `ext` attribute. Base class for both Bibitem and Bibdata.
+- **`ItemData`** (`item_data.rb`) — LutaML data model for `Item`
+- **`Bibitem`** (`bibitem.rb`) — extends `Item`, includes `Bib::BibitemShared` (XML serialization without `<bibdata>` wrapper)
+- **`Bibdata`** (`bibdata.rb`) — extends `Item`, includes `Bib::BibdataShared` (XML serialization with `<bibdata>` wrapper)
+- **`Ext`** (`ext.rb`) — extends `Bib::Ext`, adds W3C-specific `doctype` attribute
+- **`Doctype`** (`doctype.rb`) — extends `Bib::Doctype`, restricts content to `groupNote` or `technicalReport`
+
+**Public API:**
+- **`Bibliography`** (`bibliography.rb`) — search and retrieve W3C standards from the Relaton index
+- **`Processor`** (`processor.rb`) — extends `Relaton::Core::Processor`, registers the W3C flavor (prefix `W3C`, dataset `w3c-api`)
+
+**Data fetching:**
+- **`DataFetcher`** (`data_fetcher.rb`) — extends `Core::DataFetcher`, fetches all W3C specs via the W3C API
+- **`DataParser`** (`data_parser.rb`) — converts W3C API spec objects into `Relaton::W3c::Item` instances
+- **`RateLimitHandler`** (`rate_limit_handler.rb`) — mixin for retry logic and caching of fetched API objects
+- **`PubId`** (`pubid.rb`) — parses and compares W3C document identifiers (stage, code, date parts)
+
+**Utilities:**
+- **`Util`** (`util.rb`) — extends `Relaton::Bib::Util`, sets `PROGNAME` for logging
+
+The entry module is defined in `lib/relaton/w3c.rb` and exposes `grammar_hash`.
+
+### Key Dependencies
+
+- **relaton-bib** (~> 2.0.0-alpha) — provides base `Bib::Item`, `Bib::Ext`, `Bib::Doctype` and serialization mixins (LutaML model layer)
+- **relaton-core** — provides base `Core::Processor` and `Core::DataFetcher`
+- **relaton-index** — index-based search for bibliographic references
+- **w3c_api** — W3C API client used by `DataFetcher` to retrieve specifications
+- **linkeddata/rdf/sparql** — legacy RDF dependencies (still in gemspec)
+
+### Schema Validation
+
+XML output is validated against RelaxNG grammars in `grammars/`:
+- `relaton-w3c-compile.rng` — top-level compiled grammar (includes all others)
+- `relaton-w3c.rng` — W3C-specific overrides (DocumentType restrictions)
+- `basicdoc.rng`, `biblio.rng`, `biblio-standoc.rng` — shared base schemas
+
+Tests use [Jing](https://github.com/jing-trang/jing-trang) for RelaxNG validation.
+
+### Test Structure
+
+Tests use RSpec with:
+- **Round-trip tests** — YAML/XML → object → YAML/XML, verifying lossless serialization
+- **Schema validation** — XML output validated against `grammars/relaton-w3c-compile.rng`
+- **VCR** — recorded HTTP cassettes in `spec/vcr_cassettes/` (7-day re-record interval)
+- **WebMock** — disables external HTTP in tests
+
+Test fixtures live in `spec/fixtures/` (YAML, XML, RDF files).
+
+## Style
+
+- Follows [Ribose OSS Ruby style guide](https://github.com/riboseinc/oss-guides) via RuboCop
+- Target Ruby version: 3.1
+- RuboCop config inherits from remote Ribose guide; Rails cops disabled
+
+## CI
+
+GitHub Actions workflows (auto-generated by Cimas) delegate to shared workflows in `relaton/support`:
+- `rake.yml` — runs tests on push to main and PRs
+- `release.yml` — gem versioning and publishing to RubyGems

data/README.adoc

@@ -1,8 +1,8 @@
-= RelatonW3c
+= Relaton::W3c
 
 RelatonW3c 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 W3C Standards from https://w3.org, and access such metadata through the `W3cBibliographicItem` object.
+You can use it to retrieve metadata of W3C Standards from https://w3.org, and access such metadata through the `Relaton::W3c::Item` object.
 
 == Installation
 
@@ -27,13 +27,13 @@ Or install it yourself as:
 
 [source,ruby]
 ----
-require 'relaton_w3c'
+require 'relaton/w3c'
 => true
 
-item = RelatonW3c::W3cBibliography.get "W3C REC-json-ld11-20200716"
-[relaton-w3c] (W3C REC-json-ld11-20200716) Fetching from Relaton repository ...
-[relaton-w3c] (W3C REC-json-ld11-20200716) Found: `REC-json-ld11-20200716`
-=> #<RelatonW3c::W3cBibliographicItem:0x00007fc4ea03c6c0
+item = Relaton::W3c::Bibliography.get "W3C REC-json-ld11-20200716"
+[relaton-w3c] INFO: (W3C REC-json-ld11-20200716) Fetching from Relaton repository ...
+[relaton-w3c] INFO: (W3C REC-json-ld11-20200716) Found: `W3C REC-json-ld11-20200716`
+=> #<Relaton::W3c::ItemData:0x0000000129b05b38
 ...
 ----
 
@@ -42,10 +42,12 @@ item = RelatonW3c::W3cBibliography.get "W3C REC-json-ld11-20200716"
 [source,ruby]
 ----
 item.to_xml
-=> "<bibitem id="W3CREC-json-ld11-20200716" type="standard" schema-version="v1.2.1">
-      <fetched>2022-12-05</fetched>
-      <title format="text/plain">JSON-LD 1.1</title>
+=> "<bibitem id="W3CRECjsonld1120200716" type="standard" schema-version="v1.4.1">
+      <fetched>2026-03-04</fetched>
+      <formattedref>W3C REC-json-ld11-20200716</formattedref>
+      <title language="en" script="Latn">JSON-LD 1.1</title>
       <uri type="src">https://www.w3.org/TR/2020/REC-json-ld11-20200716/</uri>
+      <docidentifier type="W3C" primary="true">W3C REC-json-ld11-20200716</docidentifier>
       ..
     </bibitem>"
 ----
@@ -55,74 +57,65 @@ With argument `bibdata: true` it outputs XML wrapped by `bibdata` element and ad
 [source,ruby]
 ----
 item.to_xml bibdata: true
-=> "<bibdata type="standard" schema-version="v1.2.1">
-      <fetched>2022-12-05</fetched>
-      <title format="text/plain">JSON-LD 1.1</title>
+=> "<bibdata type="standard" schema-version="v1.4.1">
+      <fetched>2026-03-04</fetched>
+      <formattedref>W3C REC-json-ld11-20200716</formattedref>
+      <title language="en" script="Latn">JSON-LD 1.1</title>
       <uri type="src">https://www.w3.org/TR/2020/REC-json-ld11-20200716/</uri>
+      <docidentifier type="W3C" primary="true">W3C REC-json-ld11-20200716</docidentifier>
       ...
       <ext schema-version="v1.0.0">
         <doctype>technicalReport</doctype>
-        <editorialgroup>
-          <technical-committee>JSON-LD Working Group</technical-committee>
-        </editorialgroup>
+        <flavor>w3c</flavor>
       </ext>
     </bibdata>"
 ----
 
-=== Typed links
+=== Typed source links
 
-Each W3C document has `src` type link.
+Each W3C document has `src` type source link.
 
 [source,ruby]
 ----
-item.link.first.type
+item.source.first.type
 => "src"
 
-item.link.first.content
-=> #<Addressable::URI:0x75634 URI:https://www.w3.org/TR/2020/REC-json-ld11-20200716/>
+item.source.first.content
+=> "https://www.w3.org/TR/2020/REC-json-ld11-20200716/"
 ----
 
 === Create bibliographic item from XML
 [source,ruby]
 ----
-RelatonW3c::XMLParser.from_xml File.read('spec/fixtures/cr_json_ld11.xml')
-=> #<RelatonW3c::W3cBibliographicItem:0x007f9381efce98
+Relaton::W3c::Bibdata.from_xml File.read('spec/fixtures/cr_json_ld11.xml')
+=> #<Relaton::Bib::ItemData:0x0000000100f50018
 ...
 ----
 
 === Create bibliographic item from YAML
 [source,ruby]
 ----
-hash = YAML.load_file 'spec/fixtures/cr_json_ld11.yml'
-=> {"schema-version"=>"v1.2.1",
-...
-
-bib_hash = RelatonW3c::HashConverter.hash_to_bib hash
-=> {:"schema-version"=>"v1.2.1",
-...
-
-RelatonW3c::W3cBibliographicItem.new **bib_hash
-=> #<RelatonW3c::W3cBibliographicItem:0x007f9381ec6a00
+Relaton::W3c::Item.from_yaml File.read('spec/fixtures/item.yaml')
+=> #<Relaton::W3c::ItemData:0x000000012b917450
 ...
 ----
 
 === Fetch data
 
-The method `RelatonW3c::DataFetcher.fetch(output: "data", format: "yaml")` converts all the documents from the dataset and saves them to the `./data` folder in YAML format.
+The method `Relaton::W3c::DataFetcher.fetch(output: "data", format: "yaml")` converts all the documents from the W3C API 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`).
 
-The method uses https://api.w3.org/doc API to fetch all the W3C documents.
+The available dataset is:
+- `w3c-api` - The dataset is fetched from the W3C API.
 
 [source,ruby]
 ----
-RelatonW3c::DataFetcher.fetch
-Started at: 2021-11-19 13:32:05 +0100
-Stopped at: 2021-11-19 13:34:40 +0100
-Done in: 155 sec.
-=> nil
+require 'relaton/w3c/data_fetcher'
+
+Relaton::W3c::DataFetcher.fetch
 ----
 
 === Logging

data/bin/console

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 
 require "bundler/setup"
-require "relaton_w3c"
+require "relaton/w3c"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.