newsmlg2 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 556c768538613353dfff0fcadf54e6b11a810d7aa6fce89b1182204d6135f471
+  data.tar.gz: f8a212eb59e47d8e0118e54472d03589fb6f471df17750d686a258576f1b86e1
+SHA512:
+  metadata.gz: 2df4c64419fce1237b3a91228b9bf04f8b8cc612fcee7c3d97a445370ce9287eb00b59f069df15a7eca02940b2bc9b60ff1afaae0038b5b3f258daab8329232a
+  data.tar.gz: d02c09c2b4c808bb5bc62769f7a9471da7ef2316a0544f3ed392b2babbd65007453dbefab2934c7eeb132b00eb47350e055696450892ea159e620e3591edcee6

data/.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+    - 'docs/**'
+  pull_request:
+    paths:
+    - 'docs/**'
+  repository_dispatch:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+          cache-version: 0
+          working-directory: docs
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Build with Jekyll
+        run: bundle exec jekyll build --verbose --trace --baseurl "${{ steps.pages.outputs.base_path }}"
+        working-directory: docs
+        env:
+          JEKYLL_ENV: production
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/_site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    if: ${{ github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

data/.github/workflows/links.yml

@@ -0,0 +1,99 @@
+name: links
+
+on:
+  push:
+    branches:
+    - main
+    paths:
+    - 'docs/**'
+  pull_request:
+    paths:
+    - 'docs/**'
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  link_checker:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.4'
+        bundler-cache: true
+        working-directory: docs
+
+    - name: Build site
+      env:
+        JEKYLL_ENV: production
+      run: bundle exec jekyll build --trace
+      working-directory: docs
+
+    - name: Restore lychee cache
+      uses: actions/cache@v4
+      with:
+        path: .lycheecache
+        key: cache-lychee-${{ github.sha }}
+        restore-keys: cache-lychee-
+
+    - name: Check if site was built
+      run: |
+        if [ ! -d "_site" ]; then
+          echo "Error: _site directory not created"
+          exit 1
+        fi
+        echo "Site built successfully"
+        ls -la _site/
+      working-directory: docs
+
+    - name: Link Checker (Built Site)
+      uses: lycheeverse/lychee-action@v2
+      with:
+        # Check the built HTML site for rendered links
+        # Only check https and http schemes, exclude file:// due to path resolution issues
+        args: >-
+          --verbose
+          --no-progress
+          --config lychee.toml
+          --root-dir "$(pwd)/_site"
+          --scheme https,http
+          '_site/**/*.html'
+        fail: true
+        output: link-check-results.md
+        format: markdown
+        workingDirectory: docs
+
+    - name: Upload link check results
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: link-check-results
+        path: |
+          docs/link-check-results.md
+        retention-days: 30
+
+    - name: Comment PR with results
+      if: failure() && github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const fs = require('fs');
+          let comment = '## 🔗 Link Check Failed\n\n';
+
+          if (fs.existsSync('docs/link-check-results.md')) {
+            const results = fs.readFileSync('docs/link-check-results.md', 'utf8');
+            comment += '### Built Site Results\n\n' + results + '\n\n';
+          }
+
+          comment += '\n---\n\n*Please fix the broken links and push a new commit.*';
+
+          github.rest.issues.createComment({
+            issue_number: context.issue.number,
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            body: comment
+          });

data/.github/workflows/performance.yml

@@ -0,0 +1,25 @@
+name: performance
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  performance:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: 3.4
+          bundler-cache: true
+
+      - name: Run performance benchmarks
+        run: bundle exec rake performance:compare

data/.github/workflows/rake.yml

@@ -0,0 +1,19 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
+name: rake
+
+permissions:
+  contents: write
+  packages: write
+
+on:
+  push:
+    branches: [ master, main ]
+    tags: [ v* ]
+  pull_request:
+
+jobs:
+  rake:
+    uses: metanorma/ci/.github/workflows/generic-rake.yml@main
+    secrets:
+      pat_token: ${{ secrets.LUTAML_CI_PAT_TOKEN }}

data/.github/workflows/release.yml

@@ -0,0 +1,34 @@
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
+name: release
+
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+
+on:
+  workflow_dispatch:
+    inputs:
+      next_version:
+        description: |
+          Next release version. Possible values: x.y.z, major, minor, patch (or pre|rc|etc).
+          Also, you can pass 'skip' to skip 'git tag' and do 'gem push' for the current version
+        required: true
+        default: 'skip'
+      acknowledge_breaking_in_patch:
+        description: 'Override the patch-release breaking-change guard when the trip is a known false-positive'
+        required: false
+        type: boolean
+        default: false
+  repository_dispatch:
+    types: [ do-release ]
+
+jobs:
+  release:
+    uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
+    with:
+      next_version: ${{ github.event.inputs.next_version }}
+      acknowledge_breaking_in_patch: ${{ inputs.acknowledge_breaking_in_patch }}
+    secrets:
+      rubygems-api-key: ${{ secrets.LUTAML_CI_RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,17 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/tmp/
+.rspec_status
+/docs/_site/
+/docs/.jekyll-cache/
+/docs/.jekyll-metadata
+/docs/Gemfile.lock
+/docs/vendor/
+/TODO.impl/

data/.rubocop.yml

@@ -0,0 +1,51 @@
+require:
+  - rubocop
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.3
+  Exclude:
+    - "pkg/**/*"
+    - "vendor/**/*"
+    - "coverage/**/*"
+    - "reference-docs/**/*"
+    - "spec/fixtures/**/*"
+    - "data/**/*"
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+    - "lib/newsmlg2/base/**/*"
+    - "lib/tasks/*.rake"
+
+Metrics/MethodLength:
+  Exclude:
+    - "lib/newsmlg2/base/**/*"
+    - "lib/newsmlg2/builder/**/*"
+
+Metrics/AbcSize:
+  Exclude:
+    - "lib/newsmlg2/base/**/*"
+    - "lib/newsmlg2/builder/**/*"
+
+Metrics/ModuleLength:
+  Exclude:
+    - "lib/newsmlg2/base/**/*"
+    - "lib/newsmlg2.rb"
+    - "lib/newsmlg2/types.rb"
+    - "lib/newsmlg2/base.rb"
+    - "spec/support/**/*"
+
+Layout/LineLength:
+  Exclude:
+    - "lib/newsmlg2/base/**/*"
+    - "spec/**/*"
+
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - "spec/**/*"
+    - "lib/tasks/*.rake"
+
+Style/Documentation:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.1] - 2026-08-30
+
+### Fixed
+
+- `Newsmlg2.parse` now works on a fresh install with no XML adapter
+  configured: when the configured adapter cannot be resolved, the
+  stdlib REXML adapter is used instead of raising.
+- Renamed `InlineData#encoding` to `#content_encoding` (wire name
+  unchanged) to silence a lutaml-model override warning at load time.
+
+## [0.1.0] - 2026-08-30
+
+### Added
+
+- Initial release: a lutaml-model-based Ruby object model for IPTC
+  NewsML-G2 (NAR) targeting specification version 2.35 (power conformance).
+- Typed parsing and serialization of all seven item types plus
+  `newsMessage`, with per-document catalog stores and bundled IPTC
+  catalogs (v32–v41) for offline qcode ⇄ URI resolution.
+- Reflection-driven builder DSL (`Newsmlg2.build_news_item`, …) generated
+  from the model metadata.
+- Full port of the python-newsmlg2 test suite.
+- Compliance fixtures: the 35 official IPTC example documents and the
+  official IPTC XSD validation unit-test suite (161 files across schema
+  versions 2.9–2.35).

data/CLAUDE.md

@@ -0,0 +1,77 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+`newsmlg2` — a lutaml-model-based Ruby object model for IPTC **NewsML-G2** (News Architecture, NAR): parse, manipulate, build (DSL), and serialize NewsML-G2 XML with round-trip fidelity. Targets spec version **2.35**, **power** conformance. Namespace: `Newsmlg2`.
+
+Implementation was driven by the ordered plan files in **`TODO.impl/`** (`01-…` through `14-…`; kept locally only — the directory is gitignored). Their completion records document every port deviation and design decision.
+
+## Reference codebases — READ, do not guess
+
+Four local checkouts are the authority for this port. Consult them before designing anything:
+
+| Path | Role |
+|---|---|
+| `/Users/mulgogi/src/external/python-newsmlg2/` | Reference implementation (Python, lxml). ~317 model classes in `NewsMLG2/*.py`; its `tests/` (11 files, 35 tests, 13 fixtures in `tests/test_files/`) must be **ported fully and pass**. |
+| `/Users/mulgogi/src/external/newsml-g2/` | **Official IPTC spec repo** (git@github.com:iptc/newsml-g2). XSDs in `specification/` and `tests/schema_versions/`; 31 example listings in `examples/`; official unit-test suite: 161 XML files in `tests/unit_test_files/{version}/should_pass|should_fail/` run by `tests/runtests.py`. All are compliance fixtures for our specs. |
+| `/Users/mulgogi/src/lutaml/chemicalml/` | Sibling gem whose **gemspec, GitHub workflows, and architecture we fully adopt** (gemspec, `.github/workflows/rake.yml`+`release.yml`, `Base::*` mixin pattern, canon-based round-trip specs). |
+| `/Users/mulgogi/src/plurimath/mml/` | **Registry-pattern reference**: how models register into a lutaml GlobalContext (`register_model(Klass, id:)`), resolve via `GlobalContext.resolve_type`, and model heterogeneous children with per-element attributes + symbol types (CommonElements). |
+| `/Users/mulgogi/src/mn/metanorma-document/` | lutaml-model usage reference. NOTE: it has **no builder DSL** — the NewsML builder DSL is generated generically from model metadata. |
+| `/Users/mulgogi/src/lutaml/lutaml-model/docs/` | lutaml-model's own documentation (guides/references/tutorials) — the authority on the framework's public API. |
+
+Ground truth on NewsML-G2 semantics (item types, itemMeta/contentMeta/partMeta, catalog/scheme/qcode system, conformance levels): the 2.35 XSDs in the official repo (`specification/individual/NewsML-G2_2.35-spec-Framework-Power.xsd` is the core, 5.3k lines).
+
+## Commands
+
+```sh
+bundle install                      # deps: lutaml-model ~> 0.8, dev: rspec, rubocop, nokogiri, canon, simplecov
+bundle exec rake                    # default task = rspec
+bundle exec rspec                   # full suite
+bundle exec rspec spec/newsmlg2/catalog_spec.rb          # one file
+bundle exec rspec spec/newsmlg2/catalog_spec.rb:42       # one example by line
+bundle exec rspec -e "round trips"                        # by description
+bundle exec rubocop                 # lint (TargetRubyVersion 3.3, NewCops: enable)
+bundle exec rubocop -a              # safe autocorrect
+```
+
+RSpec config lives in `spec/spec_helper.rb` (no `.rspec` file): nokogiri XML adapter, canon semantic-XML comparison (`be_xml_equivalent_to`, wrap compared docs in `<r>…</r>`), random order, focus filtering.
+
+Never modify vendored fixture files under `spec/fixtures/` (copied from the reference repos); regenerate/copy anew if needed.
+
+## Architecture
+
+### Model layer (chemicalml pattern)
+
+One Ruby class per NewsML-G2 complex type, `snake_case` file per class under `lib/newsmlg2/`, all wired with `autoload` from `lib/newsmlg2.rb` (never `require_relative`).
+
+- **`Base::*` modules** (`lib/newsmlg2/base/`) — one per XSD *attribute group* (`CommonPowerAttributes`, `I18NAttributes`, `FlexAttributes`, …) and per shared *element group* (`ItemManagementGroup`, `DescriptiveMetadataGroup`, `ConceptRelationshipsGroup`, …). Each declares its `attribute`s and appends mappings via a `self.included(klass)` hook — this is how python-newsmlg2's multiple-inheritance MRO merging translates to Ruby mixins.
+- **Wire classes** — thin: `class NewsItem < Lutaml::Model::Serializable; include Base::…; include …; end` with their `xml do … end` mapping (`root`, `map_element`, `map_attribute`, `map_content`).
+- **Namespaces** — `Newsmlg2::NarNamespace` (`http://iptc.org/std/nar/2006-10-01/`, default/unprefixed) and `Newsmlg2::NitfNamespace`; `xml:lang`/`xml:base` attributes come from `Lutaml::Xml::W3c::XmlNamespace`. Set via `namespace` in the `xml` block.
+- **xs:any / unknown children** — captured with `map_all` (raw round-trip), replacing python-newsmlg2's `ExtensionElement`/`_xs_any_content`.
+- All serialization goes through lutaml-model mappings. **Never** hand-roll `to_h`/`from_h`/`to_xml` on model classes.
+
+### Subsystems
+
+- **`Newsmlg2::Configuration`** — the registry: every root model is registered by element id (`register_model(NewsItem, id: :"newsItem")` … in the `lib/newsmlg2.rb` module body) into a lutaml GlobalContext. It is the **single source of truth** for element-name → class resolution.
+- **`Newsmlg2::Document`** — thin entry point: `Newsmlg2.parse(xml)` / `parse_file(path)` resolves the root class **through the registry** and delegates to `klass.from_xml`; `#item`/`#item=`; `#to_xml` with declaration; writes required defaults (`standard="NewsML-G2" standardversion="2.35" conformance="power" version="1"`). `NarModel.lutaml_default_register` binds symbol-typed attributes to the `:newsmlg2` context (chemicalml `Context` pattern).
+- **`ItemSet`** — typed the mml CommonElements way: one collection attribute + `map_element` per carried item type, types as registry symbols (`:"newsItem"`).
+- **Catalog system** — `CatalogStore` (per-document), `Catalog`/`CatalogRef`/`Scheme`, bundled IPTC catalogs (`lib/newsmlg2/catalogs/*.xml`, v32–v41), `Newsmlg2.qcode_to_uri` / `uri_to_qcode`, errors `AliasNotFoundInCatalogs` / `URINotFoundInCatalogs`.
+- **Builder DSL** — `Newsmlg2.build_news_item(guid: …, lang: "en-GB") { |item| … }` (one `build_*` per item type). Node proxies are **generated from the model's lutaml attribute metadata** (snake_case methods, value coercion String→content-model, nested blocks, repeatable calls for collections). No per-class hand-written builder code.
+
+### Test tiers (all must stay green)
+
+1. **Ported python suite** — `spec/newsmlg2/**` mirroring `python-newsmlg2/tests/test_*.py` one-to-one (semantics preserved, Ruby idioms).
+2. **IPTC examples** — `spec/compliance/examples_spec.rb` over vendored `spec/fixtures/iptc/examples/` (31 LISTING files + extras): parse → typed assertions → semantic round-trip via canon.
+3. **IPTC official validation suite** — `spec/compliance/xsd_validation_spec.rb` over `spec/fixtures/iptc/unit_test_files/` (151 should-pass / 10 should-fail) × per-version XSDs from `tests/schema_versions/`, using `Lutaml::Xml::XsdValidator`; the file→schema matrix mirrors `tests/runtests.py` exactly.
+
+## Conventions
+
+- Specs use **real model instances — never doubles**; assert behavior and output, not interactions.
+- **NEVER reference nokogiri (or any specific XML parser) in `lib/`** — specs only. All raw XML handling goes through lutaml-model's configured adapter (`Lutaml::Model::Config.adapter_for(:xml)`) or, better, `from_xml`/`to_xml` on models.
+- **NEVER hand-roll element-name dispatch** (no name→class hashes, no `node.name` comparisons in code). Element names live only in the `xml do` DSL and the `Configuration` registration block; dispatch goes through the registry / framework mappings.
+- **NEVER reimplement framework mechanics** (parsing, polymorphic dispatch, serialization) — read `~/src/lutaml/lutaml-model/docs/` and follow `~/src/plurimath/mml/`.
+- Gemspec/workflows follow chemicalml verbatim (adapted names): `required_ruby_version >= 3.3.0`, single runtime dep `lutaml-model ~> 0.8.0`, `BSD-2-Clause`, Ribose Inc.
+- Versions, tags, and releases are **the user's decision** — the release workflow is manually dispatched; never pick a version number.
+- All changes go through PRs; never commit/push to main or push tags.

data/Gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake', '~> 13.2'
+
+group :development do
+  gem 'canon', '0.2.12'
+  gem 'nokogiri'
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.66', require: false
+  gem 'simplecov', '~> 0.22', require: false
+end

data/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2026, Ribose Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,135 @@
+= newsmlg2
+
+NewsML-G2 for Ruby, built on link:https://github.com/lutaml/lutaml-model[lutaml-model].
+
+Parse, manipulate, build and serialize IPTC
+link:https://iptc.org/standards/newsml-g2/[NewsML-G2] (News Architecture) XML
+with round-trip fidelity. Targets specification version 2.35, power
+conformance. The model layer is a port of
+link:https://github.com/iptc/python-newsmlg2[python-newsmlg2], its full test
+suite is ported, and the official IPTC specification examples and unit-test
+suite are adopted as compliance fixtures.
+
+== Installation
+
+.....
+gem "newsmlg2"
+.....
+
+== Parsing
+
+.....
+require "newsmlg2"
+
+doc = Newsmlg2.parse_file("newsitem.xml")     # or Newsmlg2.parse(xml_string)
+doc.item                                     # => Newsmlg2::NewsItem (typed)
+doc.item.item_meta.item_class.qcode          # => "ninat:text"
+doc.item.content_meta.headlines.first.to_s   # => "Fed to halt QE ..."
+.....
+
+Every root element dispatches to its typed model: +NewsItem+, +PackageItem+,
++ConceptItem+, +KnowledgeItem+, +CatalogItem+, +PlanningItem+ or
++NewsMessage+.
+
+== QCodes and catalogs
+
+A document carries its own catalog store: inline +<catalog>+ elements plus
++<catalogRef>+ hrefs (the IPTC standard catalogs are bundled, so no network
+access is needed).
+
+.....
+doc.catalog_store.get_scheme_for_alias("ninat").uri
+# => "http://cv.iptc.org/newscodes/ninature/"
+
+Newsmlg2.qcode_to_uri("ninat:text", doc)
+# => "http://cv.iptc.org/newscodes/ninature/text"
+Newsmlg2.uri_to_qcode("http://cv.iptc.org/newscodes/ninature/text", doc)
+# => "ninat:text"
+.....
+
+== Building with the DSL
+
+.....
+doc = Newsmlg2.build_news_item(guid: "urn:newsml:acme.com:20260830:00001",
+                                lang: "en-GB") do |item|
+  item.item_meta do |meta|
+    meta.item_class qcode: "ninat:text"
+    meta.provider qcode: "nprov:acme" do |p|
+      p.name "Acme News Agency"
+    end
+    meta.version_created "2026-08-30T12:00:00+00:00"
+  end
+  item.content_meta do |cm|
+    cm.urgency 2
+    cm.headline "Eruption of Icelandic volcano"
+    cm.subject qcode: "medtop:20000962" do |s|
+      s.name "Volcano"
+      s.name "Vulkan", xml_lang: "de"
+    end
+  end
+end
+
+doc.to_xml   # => "<?xml version=\"1.0\" ... ?>"
+.....
+
+Builder methods are generated from the model metadata: one per attribute
+(collections accept repeated calls and singular aliases — +subject+ appends
+to +subjects+), keyword arguments become child attributes, plain strings
+wrap into content-bearing types, and blocks nest.
+
+== Serialization
+
+.....
+doc.to_xml                 # declaration + canonical 2-space-pretty XML
+doc.item.item_meta.to_xml  # any subtree
+.....
+
+Serializing an item without a +guid+ raises +Newsmlg2::MissingGuidError+.
+The spec's default attributes (+standard+, +standardversion+,
++conformance+, +version+) are filled in like python-newsmlg2 does.
+
+== Architecture
+
+* +lib/newsmlg2/nar_model.rb+ — the base model: binds the NAR namespace
+  once and provides the declaration DSL (+xml_attributes+, +xml_element+,
+  +xml_content+).
+* +lib/newsmlg2/base/+ — XSD attribute groups and element groups as mixins
+  (one file per group, ported from python-newsmlg2's attributegroups.py and
+  the +*Group+ element lists).
+* +lib/newsmlg2/types/+ — one class per XSD complex type; element names are
+  declared once, at their usage site in the owning model.
+* +lib/newsmlg2/items/+ — the seven item types, +newsMessage+, and their
+  structural children (+ItemMeta+, +ContentMeta+, +PartMeta+, +GroupSet+ …).
+* +lib/newsmlg2/catalog_store.rb+ — per-document catalog store and qcode
+  resolution; IPTC catalogs v32–v41 are bundled under
+  +lib/newsmlg2/catalogs/+.
+* +lib/newsmlg2/document.rb+ — the parse/serialize entry point.
+* +lib/newsmlg2/builder.rb+ — the reflection-driven build DSL.
+
+== Compliance
+
+Three test tiers, all green in CI:
+
+1. **python-newsmlg2 test suite port** — +spec/newsmlg2/*_spec.rb+.
+2. **IPTC official examples** — all 35 example documents
+   (+spec/compliance/examples_spec.rb+).
+3. **IPTC official validation suite** — 161 should-pass/should-fail files
+   across all schema versions, ~2100 assertions
+   (+spec/compliance/xsd_validation_spec.rb+).
+
+IPTC material (examples, schemas, unit-test files) is vendored under
++spec/fixtures/iptc/+ under the IPTC's CC-BY 4.0 / MIT terms; see
++spec/fixtures/iptc/README.md+.
+
+== Development
+
+.....
+bundle install
+bundle exec rake            # full suite
+bundle exec rubocop
+.....
+
+== License
+
+BSD-2-Clause. NewsML-G2 is a trademark of the IPTC; this library is not
+affiliated with the IPTC.

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+
+Dir[File.expand_path('lib/tasks/*.rake', __dir__)].each { |task| import task }
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+  task default: :spec
+rescue LoadError
+  task :default do
+    warn 'rspec not available — skipping specs'
+  end
+end

data/docs/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'jekyll', '~> 4.3'
+gem 'jekyll-theme-minimal'

data/docs/_config.yml

@@ -0,0 +1,4 @@
+title: newsmlg2
+description: NewsML-G2 for Ruby, built on lutaml-model
+theme: jekyll-theme-minimal
+markdown: kramdown

data/docs/index.md

@@ -0,0 +1,15 @@
+---
+title: newsmlg2 — NewsML-G2 for Ruby
+layout: default
+---
+
+# newsmlg2
+
+NewsML-G2 for Ruby, built on [lutaml-model](https://github.com/lutaml/lutaml-model).
+
+See the [README](https://github.com/lutaml/newsmlg2-ruby) for usage:
+parsing, qcode/catalog resolution, the builder DSL and serialization.
+
+## Pages
+
+- [Usage](usage.md)

data/docs/lychee.toml

@@ -0,0 +1,4 @@
+# Link checker configuration for the built docs site.
+timeout = 20
+max_retries = 3
+retry_wait_time = 5