glossarist 2.10.3 → 2.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fb1aa6f911f51d2a58777a0b48615d94bdf84f46cf434f7850ffbd022b8ad0ff
-  data.tar.gz: 9129cf0ef1e397c530795c33d702de64836f6728aa3825e5e255e3c64fb6dfa0
+  metadata.gz: b70c846aebbbbd0af25b5ba83b94ea880631518cf60b7a8ce39911275ab44ee4
+  data.tar.gz: bada2553c608f3816aa6532313cededc476680e52f5efdf6bf0285061340ade9
 SHA512:
-  metadata.gz: c9c6fccba7097d7572c7715f499e8be577557fd936fd3f7bc6573427a1e498eb859533a1506a3c19e28196d3ba85381509fde73d9d0fb67a9d89f65bd24acb6e
-  data.tar.gz: 7f42bfe0f602950647f08521a2e084480497d57e0d94e9b62cbfb07bd65a4fc7e9eda51a4f0640b5d37360d6f71db0d360160a0558cf3bf469092aceed4e1689
+  metadata.gz: 40bd8e71cbb34e419bb1ed4d82f1474666c82d29467afbc9b6e5537f7e706a61f8d53fb6682a25a65040b1e89d7b59ecacec2f9af77e9305ec2ce5f561c6f769
+  data.tar.gz: e39ba317e19833514190bcd693538b44f75241f07ba03ca25e261ac56efaa3671acb2802a505743cfc1bc4d0e52f0a3f11d8f7765be1a64ad44ecd0d8a01f106

data/CLAUDE.md

@@ -61,7 +61,7 @@ Designation inheritance hierarchy (MECE):
 
 ### Dataset Loading
 
-- **`GlossaryStore`** (`glossary_store.rb`) — the dataset abstraction. Backed by `Lutaml::Store::PackageStore`, handles loading/saving from directories and ZIPs, concept CRUD, metadata, bibliography, images, and stats. Format detection is model-driven via `ConceptDocument.for_version`. **All callers that need to load concepts from a dataset should use GlossaryStore.**
+- **`GlossaryStore`** (`glossary_store.rb`) — the dataset abstraction. Backed by `Lutaml::Store::PackageStore`, handles loading/saving from directories and ZIPs, concept CRUD, metadata, bibliography, images, dataset-level non-verbal entities (`#figures`, `#tables`, `#formulas` lazy-loaded from `figures/`/`tables/`/`formulas/` subdirectories), and stats. Format detection is model-driven via `ConceptDocument.for_version`. **All callers that need to load concepts from a dataset should use GlossaryStore.**
 - **`ConceptCollector`** (`concept_collector.rb`) — legacy scanner with hand-rolled format detection (file-system heuristics, not model-driven). Being replaced by GlossaryStore. Do not add new callers.
 - **`ConceptManager`** (`concept_manager.rb`) — legacy file I/O used by `ManagedConceptCollection`. Being replaced by GlossaryStore. Do not add new callers.
 - **`ManagedConceptCollection`** (`managed_concept_collection.rb`) — legacy collection that loads via ConceptManager. Being replaced by GlossaryStore.
@@ -132,7 +132,8 @@ The `exe/glossarist` executable uses Thor. Commands:
 
 - **`ConceptToTbxTransform`** (`transforms/concept_to_tbx_transform.rb`) — converts ManagedConcept to TBX-XML using the tbx gem (ISO 30042:2019). Produces `Tbx::ConceptEntry` per concept or `Tbx::Document` for full export.
 - **`ConceptToSkosTransform`** (`transforms/concept_to_skos_transform.rb`) — converts ManagedConcept to SKOS RDF using `Glossarist::Rdf::SkosConcept`. Has `transform` (single) and `transform_document` (batch, returns `SkosVocabulary`). Produces JSON-LD and Turtle via the unified `rdf` DSL.
-- **SKOS/RDF models** (`lib/glossarist/rdf/`) — `SkosConcept`, `SkosVocabulary` (ConceptScheme container), `LocalizedLiteral` (language-tagged value), namespace classes.
+- **`ConceptToGlossTransform`** (`transforms/concept_to_gloss_transform.rb`) — converts ManagedConcept and dataset-level non-verbal entities to ontology-faithful RDF using `Glossarist::Rdf::Gloss*` view classes. `transform_document(concepts, figures:, tables:, formulas:)` and `to_turtle`/`to_jsonld` accept figures/tables/formulas kwargs (backward compatible — empty defaults). Uses a `DESIGNATION_BUILDERS` registry keyed by exact Designation subclass (OCP) instead of a case/when switch.
+- **SKOS/RDF models** (`lib/glossarist/rdf/`) — `GlossConcept`, `GlossLocalizedConcept`, `GlossDesignation` and subclasses, `GlossFigure`/`GlossTable`/`GlossFormula`/`GlossFigureImage` (dataset-level non-verbal entities per concept-model v3.1.0 K1/K2 shapes), `SkosConcept`, `SkosVocabulary`, `LocalizedLiteral`, namespace classes. `EmitsExtraTriples` is autoloaded from `lutaml_ext.rb` via the immediate parent namespace file (`rdf.rb`); `LutamlTurtleTransformExt` is prepended into `Lutaml::Turtle::Transform` so the framework asks each instance for extra triples.
 - TBX, Turtle, JSON-LD, JSONL export all write a single document file; JSON writes per-concept files.
 
 ### Dependencies
@@ -142,14 +143,28 @@ The `exe/glossarist` executable uses Thor. Commands:
 - `relaton` (>= 2.0.0, < 3) — bibliography database integration
 - `thor` — CLI commands
 
-## Gemfile Notes
+## Dependencies
 
-The Gemfile overrides relaton gems from git branches for lutaml-model 0.8 compatibility:
-- 5 repos use `fix/lutaml-model-0.8` branches (relaton-bib, relaton-iso, relaton-3gpp, relaton-bipm, relaton-bsi)
-- 5 repos use `lutaml-integration` branches (relaton-calconnect, relaton-ccsds, relaton-cen, relaton-iec, relaton-itu)
-- Released 2.0.0 gems have untyped lutaml-model attributes that fail with 0.8+
-- relaton-bib 2.1.0 is released but sub-gems pin `~> 2.0.0`, blocking 2.1.0 adoption until upstream updates constraints
-- Remove git overrides once relaton gems release versions with lutaml-model 0.8 support
+- `relaton` (>= 2.0.0, < 3) — bibliography database integration. Upstream
+  shipped 2.1.0 with lutaml-model 0.8 compatibility, so the historical
+  git-branch overrides are no longer needed and the Gemfile pins the
+  released gem directly.
+- `lutaml-model` (~> 0.8.5), `lutaml-store` (~> 0.2.0) — serialization
+  framework (YAML/XML/JSON-LD/Turtle) and package store.
+- `tbx` — ISO 30042:2019 TBX model classes.
+- `thor` — CLI commands.
+- `rdf-turtle` (~> 3.3), `shacl` (~> 0.4) — Turtle emission + SHACL
+  validation against vendored concept-model shapes.
+
+## SchemaMigration module split
+
+`SchemaMigration` is a thin facade over three single-concern modules:
+
+- `SchemaMigration::V0ToV1` — hash-to-hash transform (IEV legacy YAML → V1 shape). Single `#migrate` entry point.
+- `SchemaMigration::V2ToV3` — model-to-model transform (`V2::ManagedConcept` → `V3::ManagedConcept`). Class methods `migrate_concept` / `concept_version`.
+- `SchemaMigration::CliPipeline` — file I/O + dispatch + output writing for `glossarist upgrade`. Single `#run` entry point; output can be a directory of YAML files or a `.gcr` ZIP package.
+
+The facade preserves the historical class-method API (`SchemaMigration.new`, `.migrate_concept`, `.concept_version`, `.upgrade_directory`) so existing callers don't break. Adding V3→V4 later means adding a new module under `SchemaMigration::`, not editing these.
 
 ## Schema Version Subclasses Are NOT Duplication
 
@@ -170,8 +185,6 @@ See `TODO.improve/` for detailed plans.
 
 1. **Migrate callers to GlossaryStore** — ConceptCollector (8 call sites) and ConceptManager (1 call site) duplicate format detection with file-system heuristics. GlossaryStore is model-driven, framework-aligned, and handles both directory and ZIP. All callers should go through GlossaryStore.
 
-2. **Split SchemaMigration into focused modules** — Currently handles V0→V1 hash migration, V2→V3 model migration, and a CLI pipeline at three different abstraction levels. Each should be its own module.
-
 ### Rejected candidates (do not re-suggest)
 
 - **Collapse V2/V3 ManagedConceptData** — Version subclasses are a real seam, not duplication. See "Schema Version Subclasses Are NOT Duplication" above.

data/lib/glossarist/cli/export_command.rb

@@ -52,13 +52,17 @@ module Glossarist
       private
 
       def load_concepts
-        if @path.end_with?(".gcr")
-          package = GcrPackage.load(@path)
-          resolve_metadata_from_package(package)
-          package.concepts
-        else
-          GlossaryStore.new.tap { |s| s.load(@path) }.concepts
-        end
+        store.concepts
+      end
+
+      def store
+        @store ||= if @path.end_with?(".gcr")
+                     pkg = GcrPackage.load(@path)
+                     resolve_metadata_from_package(pkg)
+                     pkg
+                   else
+                     GlossaryStore.new.tap { |s| s.load(@path) }
+                   end
       end
 
       def resolve_metadata_from_package(package)
@@ -106,6 +110,22 @@ module Glossarist
         @options.fetch(:validate, false)
       end
 
+      # Dataset-level non-verbal entities come from the GlossaryStore (which
+      # lazy-loads figures/tables/formulas from the dataset directory). GCR
+      # packages don't yet expose these — empty arrays keep the call site
+      # uniform. Future: extend GcrPackage to surface them.
+      def dataset_figures
+        @store.is_a?(GlossaryStore) ? @store.figures : []
+      end
+
+      def dataset_tables
+        @store.is_a?(GlossaryStore) ? @store.tables : []
+      end
+
+      def dataset_formulas
+        @store.is_a?(GlossaryStore) ? @store.formulas : []
+      end
+
       def per_concept_supported?(format)
         PER_CONCEPT_FORMATS.include?(format)
       end
@@ -136,7 +156,10 @@ module Glossarist
         transform = Transforms::ConceptToGlossTransform.new(nil,
                                                             transform_options)
         File.write(File.join(output_dir, "#{name}.jsonld"),
-                   transform.to_jsonld(concepts))
+                   transform.to_jsonld(concepts,
+                                       figures: dataset_figures,
+                                       tables: dataset_tables,
+                                       formulas: dataset_formulas))
       end
 
       def export_turtle(concepts, name, output_dir)
@@ -144,7 +167,10 @@ module Glossarist
         transform = Transforms::ConceptToGlossTransform.new(nil,
                                                             transform_options)
         File.write(File.join(output_dir, "#{name}.ttl"),
-                   transform.to_turtle(concepts))
+                   transform.to_turtle(concepts,
+                                       figures: dataset_figures,
+                                       tables: dataset_tables,
+                                       formulas: dataset_formulas))
       end
 
       def export_tbx(concepts, name, output_dir)

data/lib/glossarist/glossary_store.rb

@@ -9,11 +9,16 @@ module Glossarist
       @concept_document_class = V3::ConceptDocument
       @v1_concepts = nil
       @localized_concepts_dir_name = nil
+      @dataset_path = nil
+      @figures = nil
+      @tables = nil
+      @formulas = nil
     end
 
     # ── Load ──
 
     def load_directory(path, format: nil)
+      @dataset_path = File.expand_path(path)
       if v1_dataset?(path)
         load_v1_fallback(path)
         return self
@@ -44,6 +49,7 @@ module Glossarist
     end
 
     def load_zip(path, format: nil)
+      @dataset_path = File.expand_path(path)
       metadata = load_metadata_from_zip(path)
       @concept_document_class = resolve_concept_document_class(metadata)
 
@@ -174,6 +180,28 @@ module Glossarist
       @package.asset_paths.select { |p| p.start_with?("images/") }
     end
 
+    # ── Dataset-level non-verbal entities ──
+    #
+    # Loaded lazily from the dataset's figures/, tables/, formulas/
+    # subdirectories. Each YAML file is parsed as the corresponding model
+    # (Figure, Table, Formula). The entities are referenced from
+    # ManagedConceptData via FigureReference/TableReference/FormulaReference
+    # but live as standalone shared entities at the dataset level.
+    # Wired into ConceptToGlossTransform via the figures:/tables:/formulas:
+    # kwargs on transform_document.
+
+    def figures
+      @figures ||= load_dataset_entities("figures", Figure)
+    end
+
+    def tables
+      @tables ||= load_dataset_entities("tables", Table)
+    end
+
+    def formulas
+      @formulas ||= load_dataset_entities("formulas", Formula)
+    end
+
     # ── Stats ──
 
     def stats
@@ -201,6 +229,21 @@ module Glossarist
       @package = Lutaml::Store::PackageStore.new(definition)
     end
 
+    # Scans `{dataset_path}/{subdir}/*.{yaml,yml}` and parses each file as
+    # the given model class. Returns [] when the directory doesn't exist
+    # (e.g., datasets that don't carry this entity kind) — absent directory
+    # is not an error, just an empty collection.
+    def load_dataset_entities(subdir, klass)
+      return [] unless @dataset_path
+
+      dir = File.join(@dataset_path, subdir)
+      return [] unless File.directory?(dir)
+
+      Dir.glob(File.join(dir, "*.{yaml,yml}")).filter_map do |path|
+        klass.from_file(path)
+      end
+    end
+
     def resolve_concept_document_class(metadata)
       version = metadata&.schema_version.to_s
       ConceptDocument.for_version(version)

data/lib/glossarist/rdf/gloss_concept.rb

@@ -51,6 +51,9 @@ module Glossarist
 
     class GlossDocument < Lutaml::Model::Serializable
       attribute :concepts, GlossConcept, collection: true
+      attribute :figures, GlossFigure, collection: true
+      attribute :tables, GlossTable, collection: true
+      attribute :formulas, GlossFormula, collection: true
 
       rdf do
         namespace Namespaces::GlossaristNamespace,
@@ -61,6 +64,9 @@ module Glossarist
                   Namespaces::RdfNamespace
 
         members :concepts
+        members :figures
+        members :tables
+        members :formulas
       end
     end
   end

data/lib/glossarist/rdf/gloss_figure.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Glossarist
+  module Rdf
+    # RDF view for a dataset-level Figure entity (concept-model v3.1.0 K1+K2).
+    #
+    # Emits a `gloss:Figure` subject with:
+    #   - gloss:image — xsd:anyURI (the first image variant's src, per K1
+    #     FigureShape which constrains it to min 1)
+    #   - gloss:caption — xsd:string (one language picked from the localized hash)
+    #   - dcterms:description — xsd:string (one language picked)
+    #
+    # Per-variant foaf:Image subjects (K2 ImageShape) are emitted via the
+    # `images` collection — each variant becomes its own subject with
+    # dcterms:format and gloss:imageRole.
+    #
+    # The Figure domain model (Glossarist::Figure) stores caption/description
+    # as language-keyed hashes; the K1 FigureShape constrains them to single
+    # xsd:string values, so the transform picks one language at build time.
+    class GlossFigure < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :identifier, :string
+      attribute :image, :string
+      attribute :caption, :string
+      attribute :description, :string
+      attribute :images, GlossFigureImage, collection: true
+
+      rdf do
+        namespace Namespaces::GlossaristNamespace,
+                  Namespaces::DctermsNamespace
+
+        subject { |f| "figure/#{f.id}" }
+
+        types "gloss:Figure"
+
+        predicate :image, namespace: Namespaces::GlossaristNamespace,
+                          to: :image
+        predicate :caption, namespace: Namespaces::GlossaristNamespace,
+                            to: :caption
+        predicate :description, namespace: Namespaces::DctermsNamespace,
+                                to: :description
+        members :images
+      end
+    end
+  end
+end

data/lib/glossarist/rdf/gloss_figure_image.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Glossarist
+  module Rdf
+    # RDF view for one image variant within a Figure (concept-model v3.1.0 K2).
+    #
+    # Emits a `foaf:Image` subject with:
+    #   - dcterms:format — required by K2 ImageShape (e.g. "svg", "png")
+    #   - dcterms:language — optional (max 1) — when the variant is localized
+    #   - dcat:byteSize — optional (max 1) — when the source model carries it
+    #   - gloss:imageRole — the variant's role (vector/raster/dark/light/print)
+    #
+    # The FigureImage domain model carries src, format, role, width, height,
+    # scale. byte_size isn't on the model (it would require file-system
+    # inspection); we emit nil when absent, which the RDF layer skips.
+    class GlossFigureImage < Lutaml::Model::Serializable
+      attribute :src, :string
+      attribute :format, :string
+      attribute :role, :string
+      attribute :byte_size, :integer
+
+      rdf do
+        namespace Namespaces::DctermsNamespace,
+                  Namespaces::FoafNamespace,
+                  Namespaces::DcatNamespace,
+                  Namespaces::GlossaristNamespace
+
+        subject { |i| "image/#{i.src}" }
+
+        types "foaf:Image"
+
+        predicate :format, namespace: Namespaces::DctermsNamespace,
+                           to: :format
+        predicate :byteSize, namespace: Namespaces::DcatNamespace,
+                             to: :byte_size
+        predicate :imageRole, namespace: Namespaces::GlossaristNamespace,
+                              to: :role
+      end
+    end
+  end
+end

data/lib/glossarist/rdf/gloss_formula.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Glossarist
+  module Rdf
+    # RDF view for a dataset-level Formula entity (concept-model v3.1.0 K1).
+    #
+    # Emits a `gloss:Formula` subject with:
+    #   - gloss:expression — xsd:string (one language picked from the localized hash)
+    #   - gloss:latexForm — xsd:string (the LaTeX form, when notation is latex)
+    #   - dcterms:description — xsd:string (one language picked)
+    class GlossFormula < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :identifier, :string
+      attribute :expression, :string
+      attribute :latex_form, :string
+      attribute :description, :string
+
+      rdf do
+        namespace Namespaces::GlossaristNamespace,
+                  Namespaces::DctermsNamespace
+
+        subject { |f| "formula/#{f.id}" }
+
+        types "gloss:Formula"
+
+        predicate :expression, namespace: Namespaces::GlossaristNamespace,
+                               to: :expression
+        predicate :latexForm, namespace: Namespaces::GlossaristNamespace,
+                              to: :latex_form
+        predicate :description, namespace: Namespaces::DctermsNamespace,
+                                to: :description
+      end
+    end
+  end
+end

data/lib/glossarist/rdf/gloss_table.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Glossarist
+  module Rdf
+    # RDF view for a dataset-level Table entity (concept-model v3.1.0 K1).
+    #
+    # Emits a `gloss:Table` subject with:
+    #   - gloss:content — xsd:string (serialized table content)
+    #   - gloss:caption — xsd:string (one language picked)
+    #   - dcterms:title — xsd:string (the table identifier, used as title)
+    class GlossTable < Lutaml::Model::Serializable
+      attribute :id, :string
+      attribute :identifier, :string
+      attribute :content, :string
+      attribute :caption, :string
+
+      rdf do
+        namespace Namespaces::GlossaristNamespace,
+                  Namespaces::DctermsNamespace
+
+        subject { |t| "table/#{t.id}" }
+
+        types "gloss:Table"
+
+        predicate :content, namespace: Namespaces::GlossaristNamespace,
+                            to: :content
+        predicate :caption, namespace: Namespaces::GlossaristNamespace,
+                            to: :caption
+        predicate :title, namespace: Namespaces::DctermsNamespace,
+                          to: :identifier
+      end
+    end
+  end
+end

data/lib/glossarist/rdf/namespaces/dcat_namespace.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Rdf
+    module Namespaces
+      class DcatNamespace < Lutaml::Rdf::Namespace
+        uri "http://www.w3.org/ns/dcat#"
+        prefix "dcat"
+      end
+    end
+  end
+end

data/lib/glossarist/rdf/namespaces/foaf_namespace.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Rdf
+    module Namespaces
+      class FoafNamespace < Lutaml::Rdf::Namespace
+        uri "http://xmlns.com/foaf/0.1/"
+        prefix "foaf"
+      end
+    end
+  end
+end

data/lib/glossarist/rdf/namespaces.rb

@@ -3,7 +3,9 @@
 module Glossarist
   module Rdf
     module Namespaces
-      autoload :DctermsNamespace, "#{__dir__}/namespaces/dcterms_namespace"
+      autoload :DcatNamespace,       "#{__dir__}/namespaces/dcat_namespace"
+      autoload :DctermsNamespace,    "#{__dir__}/namespaces/dcterms_namespace"
+      autoload :FoafNamespace,       "#{__dir__}/namespaces/foaf_namespace"
       autoload :GlossaristNamespace,
                "#{__dir__}/namespaces/glossarist_namespace"
       autoload :IsoThesNamespace,    "#{__dir__}/namespaces/iso_thes_namespace"

data/lib/glossarist/rdf/v3.rb

@@ -25,6 +25,10 @@ module Glossarist
         GlossLocalizedConcept
         GlossConcept
         GlossDocument
+        GlossFigure
+        GlossFigureImage
+        GlossTable
+        GlossFormula
       ].freeze
 
       VIEW_CLASS_NAMES.each do |name|

data/lib/glossarist/rdf.rb

@@ -4,10 +4,18 @@ require "lutaml/rdf"
 require "lutaml/turtle"
 require "lutaml/jsonld"
 
-require_relative "rdf/lutaml_ext"
-
 module Glossarist
   module Rdf
+    # lutaml_ext.rb defines EmitsExtraTriples (mixed into RDF model classes
+    # that want to emit extra triples) and LutamlTurtleTransformExt (prepended
+    # into Lutaml::Turtle::Transform so the framework asks each instance for
+    # its extra triples). The prepend must run before the first transform
+    # call; autoload here fires the first time EmitsExtraTriples is
+    # referenced (i.e., when GlossLocalizedConcept includes it during its
+    # own autoload), which is before any transform runs.
+    autoload :EmitsExtraTriples,        "#{__dir__}/rdf/lutaml_ext"
+    autoload :LutamlTurtleTransformExt, "#{__dir__}/rdf/lutaml_ext"
+
     autoload :Namespaces,             "#{__dir__}/rdf/namespaces"
     autoload :LocalizedLiteral,       "#{__dir__}/rdf/localized_literal"
     autoload :RelationshipPredicates, "#{__dir__}/rdf/relationship_predicates"
@@ -30,6 +38,10 @@ module Glossarist
     autoload :GlossLocalizedConcept,  "#{__dir__}/rdf/gloss_localized_concept"
     autoload :GlossConcept,           "#{__dir__}/rdf/gloss_concept"
     autoload :GlossDocument,          "#{__dir__}/rdf/gloss_concept"
+    autoload :GlossFigure,            "#{__dir__}/rdf/gloss_figure"
+    autoload :GlossFigureImage,       "#{__dir__}/rdf/gloss_figure_image"
+    autoload :GlossTable,             "#{__dir__}/rdf/gloss_table"
+    autoload :GlossFormula,           "#{__dir__}/rdf/gloss_formula"
     autoload :V3,                     "#{__dir__}/rdf/v3"
   end
 end

data/lib/glossarist/schema_migration/cli_pipeline.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Glossarist
+  class SchemaMigration
+    # Orchestrator for the `glossarist upgrade` CLI command.
+    #
+    # Reads source concepts from a directory, dispatches each file to the
+    # right migrator (V0ToV1 for IEV-legacy hashes, V2ToV3 for model-level
+    # version bumps), reads register.yaml, and writes the output either as
+    # a directory of YAML files or as a `.gcr` ZIP package.
+    #
+    # This is the third concern that previously lived tangled in
+    # SchemaMigration itself (alongside V0ToV1 and V2ToV3). Splitting it
+    # out keeps each module at a single abstraction level:
+    #   - V0ToV1: hash → hash transform
+    #   - V2ToV3: model → model transform
+    #   - CliPipeline (this file): file I/O + dispatch + output writing
+    class CliPipeline
+      attr_reader :source_dir, :output, :target_version, :cross_references,
+                  :dry_run
+
+      def initialize(source_dir, output:, target_version:,
+                     cross_references: nil, dry_run: false)
+        @source_dir = File.expand_path(source_dir)
+        @output = output
+        @target_version = target_version
+        @cross_references = cross_references
+        @dry_run = dry_run
+      end
+
+      def run
+        validate_source!
+        concepts = read_and_migrate_concepts
+        register_data = read_register_yaml
+        write_output(concepts, register_data)
+
+        {
+          concepts: concepts,
+          register_data: register_data,
+          source_version: source_version,
+          target_version: target_version,
+          output: File.expand_path(output),
+          count: concepts.length,
+        }
+      end
+
+      private
+
+      def validate_source!
+        unless File.directory?(source_dir)
+          raise ArgumentError, "#{source_dir} is not a directory"
+        end
+        return if concepts_dir
+
+        raise ArgumentError, "No concept YAML files found in #{source_dir}"
+      end
+
+      def concepts_dir
+        @concepts_dir ||= [
+          File.join(source_dir, "concepts"),
+          source_dir,
+        ].find { |dir| Dir.glob(File.join(dir, "*.yaml")).any? }
+      end
+
+      def source_version
+        @source_version ||= begin
+          register = V1::Register.from_file(File.join(source_dir,
+                                                      "register.yaml"))
+          register&.schema_version || "0"
+        end
+      end
+
+      def ref_maps
+        @ref_maps ||= begin
+          xref = V1::CrossReferences.from_file(cross_references)
+          xref ? xref.to_ref_maps : {}
+        end
+      end
+
+      def read_and_migrate_concepts
+        files = Dir.glob(File.join(concepts_dir, "*.yaml"))
+        concepts = []
+        errors = 0
+
+        files.each do |file|
+          v1 = V1::Concept.from_file(file)
+          next unless v1
+
+          migration = V0ToV1.new(
+            v1.to_yaml_hash,
+            from_version: source_version,
+            to_version: target_version,
+            ref_maps: ref_maps,
+          )
+          concepts << migration.migrate
+        rescue Errors::Base, Psych::SyntaxError => e
+          errors += 1
+          warn "  Error migrating #{File.basename(file)}: #{e.message}" if errors <= 5
+        end
+
+        warn "  ... #{errors - 5} more errors" if errors > 5
+        concepts
+      end
+
+      def read_register_yaml
+        register = V1::Register.from_file(File.join(source_dir,
+                                                    "register.yaml"))
+        return nil unless register
+
+        data = register.to_h
+        data["schema_version"] = target_version
+        data
+      end
+
+      def write_output(concepts, register_data)
+        output_path = File.expand_path(output)
+
+        if File.extname(output).downcase == ".gcr"
+          write_gcr(concepts, register_data, output_path)
+        else
+          write_directory(concepts, register_data, output_path)
+        end
+      end
+
+      def write_gcr(concepts, register_data, output_path)
+        if dry_run
+          puts "Would package #{concepts.length} concepts into #{output_path}"
+          return
+        end
+
+        v1_concepts = concepts.map { |h| V1::Concept.of_yaml(h).to_managed_concept }
+        rd = register_data ? RegisterData.of_yaml(register_data) : nil
+        metadata = GcrMetadata.from_concepts(v1_concepts, register_data: rd)
+        GcrPackage.create(
+          concepts: v1_concepts,
+          metadata: metadata,
+          register_data: rd,
+          output_path: output_path,
+        )
+      end
+
+      def write_directory(concepts, register_data, output_path)
+        if dry_run
+          puts "Would write #{concepts.length} concepts to #{File.join(
+            output_path, 'concepts/'
+          )}"
+          return
+        end
+
+        concepts_out = File.join(output_path, "concepts")
+        FileUtils.mkdir_p(concepts_out)
+
+        concepts.each do |concept|
+          termid = concept["termid"]
+          mc = V1::Concept.of_yaml(concept).to_managed_concept
+          File.write(File.join(concepts_out, "#{termid}.yaml"), mc.to_yaml)
+        end
+
+        return unless register_data
+
+        rd = RegisterData.of_yaml(register_data)
+        File.write(File.join(output_path, "register.yaml"), rd.to_yaml)
+      end
+    end
+  end
+end

data/lib/glossarist/schema_migration.rb

@@ -1,14 +1,29 @@
 # frozen_string_literal: true
 
-require "fileutils"
-
+# Facade for schema migration. Each abstraction level lives in its own
+# module under SchemaMigration:: — the facade preserves the historical
+# class-method API so existing callers (CLI upgrade command, V2/V3
+# namespace specs, downstream gems) don't break.
+#
+# Architecture (MECE):
+#   - V0ToV1: hash to hash transform (IEV legacy YAML to V1 shape).
+#   - V2ToV3: model to model transform (V2::ManagedConcept to V3::ManagedConcept).
+#   - CliPipeline: file I/O + dispatch + output writing for the
+#     `glossarist upgrade` CLI command.
+#
+# Each module has a single public entry point (V0ToV1#migrate,
+# V2ToV3.migrate_concept, CliPipeline#run) and is independently testable.
+# Adding V3ToV4 later = adding a new module, not editing these.
 module Glossarist
   class SchemaMigration
     CURRENT_SCHEMA_VERSION = "1"
 
-    autoload :V0ToV1, "glossarist/schema_migration/v0_to_v1"
-    autoload :V2ToV3, "glossarist/schema_migration/v2_to_v3"
+    autoload :V0ToV1,      "glossarist/schema_migration/v0_to_v1"
+    autoload :V2ToV3,      "glossarist/schema_migration/v2_to_v3"
+    autoload :CliPipeline, "glossarist/schema_migration/cli_pipeline"
 
+    # Convenience: `SchemaMigration.new(input, **opts)` is shorthand for
+    # `V0ToV1.new(input, **opts)`. Preserved for backward compatibility.
     def self.new(...)
       V0ToV1.new(...)
     end
@@ -21,142 +36,15 @@ module Glossarist
       V2ToV3.concept_version(concept)
     end
 
-    def self.upgrade_directory(source_dir, output:, # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
-                              target_version: CURRENT_SCHEMA_VERSION,
-                              cross_references: nil,
-                              dry_run: false)
-      source_dir = File.expand_path(source_dir)
-
-      concepts_dir = find_concepts_dir(source_dir)
-      unless File.directory?(source_dir)
-        raise ArgumentError,
-              "#{source_dir} is not a directory"
-      end
-      unless concepts_dir
-        raise ArgumentError,
-              "No concept YAML files found in #{source_dir}"
-      end
-
-      source_version = detect_schema_version(source_dir)
-      ref_maps = load_ref_maps(cross_references)
-      concepts = read_and_migrate_concepts(concepts_dir, source_version,
-                                           target_version, ref_maps)
-      register_data = read_register_yaml(source_dir, target_version)
-
-      write_output(concepts, register_data, output, dry_run)
-
-      {
-        concepts: concepts,
-        register_data: register_data,
-        source_version: source_version,
+    def self.upgrade_directory(source_dir, output:, target_version: CURRENT_SCHEMA_VERSION,
+                               cross_references: nil, dry_run: false)
+      CliPipeline.new(
+        source_dir,
+        output: output,
         target_version: target_version,
-        output: File.expand_path(output),
-        count: concepts.length,
-      }
-    end
-
-    class << self
-      private
-
-      def find_concepts_dir(source_dir)
-        candidates = [
-          File.join(source_dir, "concepts"),
-          source_dir,
-        ]
-        candidates.find { |dir| Dir.glob(File.join(dir, "*.yaml")).any? }
-      end
-
-      def detect_schema_version(source_dir)
-        register = V1::Register.from_file(File.join(source_dir,
-                                                    "register.yaml"))
-        register&.schema_version || "0"
-      end
-
-      def load_ref_maps(cross_references_path)
-        xref = V1::CrossReferences.from_file(cross_references_path)
-        xref ? xref.to_ref_maps : {}
-      end
-
-      def read_and_migrate_concepts(concepts_dir, source_version, # rubocop:disable Metrics/MethodLength
-                                    target_version, ref_maps)
-        files = Dir.glob(File.join(concepts_dir, "*.yaml"))
-        concepts = []
-        errors = 0
-
-        files.each do |file|
-          v1 = V1::Concept.from_file(file)
-          next unless v1
-
-          migration = V0ToV1.new(
-            v1.to_yaml_hash,
-            from_version: source_version,
-            to_version: target_version,
-            ref_maps: ref_maps,
-          )
-          concepts << migration.migrate
-        rescue Errors::Base, Psych::SyntaxError => e
-          errors += 1
-          warn "  Error migrating #{File.basename(file)}: #{e.message}" if errors <= 5
-        end
-
-        warn "  ... #{errors - 5} more errors" if errors > 5
-        concepts
-      end
-
-      def read_register_yaml(source_dir, target_version)
-        register = V1::Register.from_file(File.join(source_dir,
-                                                    "register.yaml"))
-        return nil unless register
-
-        data = register.to_h
-        data["schema_version"] = target_version
-        data
-      end
-
-      def write_output(concepts, register_data, output, dry_run) # rubocop:disable Metrics/MethodLength
-        output_path = File.expand_path(output)
-
-        if File.extname(output).downcase == ".gcr"
-          if dry_run
-            puts "Would package #{concepts.length} concepts into #{output_path}"
-            return
-          end
-
-          v1_concepts = concepts.map { |h| V1::Concept.of_yaml(h).to_managed_concept }
-          rd = register_data ? RegisterData.of_yaml(register_data) : nil
-          metadata = GcrMetadata.from_concepts(v1_concepts,
-                                               register_data: rd)
-          GcrPackage.create(
-            concepts: v1_concepts,
-            metadata: metadata,
-            register_data: rd,
-            output_path: output_path,
-          )
-        else
-          if dry_run
-            puts "Would write #{concepts.length} concepts to #{File.join(
-              output_path, 'concepts/'
-            )}"
-            return
-          end
-
-          concepts_out = File.join(output_path, "concepts")
-          FileUtils.mkdir_p(concepts_out)
-
-          concepts.each do |concept|
-            termid = concept["termid"]
-            mc = V1::Concept.of_yaml(concept).to_managed_concept
-            File.write(File.join(concepts_out, "#{termid}.yaml"),
-                       mc.to_yaml)
-          end
-
-          if register_data
-            rd = RegisterData.of_yaml(register_data)
-            File.write(File.join(output_path, "register.yaml"),
-                       rd.to_yaml)
-          end
-        end
-      end
+        cross_references: cross_references,
+        dry_run: dry_run,
+      ).run
     end
   end
 end

data/lib/glossarist/transforms/concept_to_gloss_transform.rb

@@ -37,8 +37,10 @@ module Glossarist
         new(managed_concept, options).build
       end
 
-      def self.transform_document(concepts, options = {})
-        new(nil, options).build_document(concepts)
+      def self.transform_document(concepts, figures: [], tables: [],
+                                  formulas: [], **options)
+        new(nil, options).build_document(concepts, figures: figures,
+                                                   tables: tables, formulas: formulas)
       end
 
       def initialize(managed_concept, options = {})
@@ -50,15 +52,22 @@ module Glossarist
         build_gloss_concept(concept)
       end
 
-      def build_document(concepts)
+      def build_document(concepts, figures: [], tables: [], formulas: [])
         gloss_concepts = concepts.map { |c| build_gloss_concept(c) }
-        doc = Rdf::GlossDocument.new(concepts: gloss_concepts)
+        doc = Rdf::GlossDocument.new(
+          concepts: gloss_concepts,
+          figures: figures.map { |f| build_gloss_figure(f) },
+          tables: tables.map { |t| build_gloss_table(t) },
+          formulas: formulas.map { |f| build_gloss_formula(f) },
+        )
         Rdf::GlossDocument.to_turtle(doc)
       end
 
-      def to_turtle(concepts_or_concept = nil)
+      def to_turtle(concepts_or_concept = nil, figures: [], tables: [],
+                    formulas: [])
         if concepts_or_concept.is_a?(Array)
-          build_document(concepts_or_concept)
+          build_document(concepts_or_concept, figures: figures,
+                                              tables: tables, formulas: formulas)
         else
           target = concepts_or_concept || @concept
           return "" unless target
@@ -68,12 +77,18 @@ module Glossarist
         end
       end
 
-      def to_jsonld(concepts_or_concept = nil)
+      def to_jsonld(concepts_or_concept = nil, figures: [], tables: [],
+                    formulas: [])
         if concepts_or_concept.is_a?(Array)
           gloss_concepts = concepts_or_concept.map do |c|
             build_gloss_concept(c)
           end
-          doc = Rdf::GlossDocument.new(concepts: gloss_concepts)
+          doc = Rdf::GlossDocument.new(
+            concepts: gloss_concepts,
+            figures: figures.map { |f| build_gloss_figure(f) },
+            tables: tables.map { |t| build_gloss_table(t) },
+            formulas: formulas.map { |f| build_gloss_formula(f) },
+          )
           Rdf::GlossDocument.to_jsonld(doc)
         else
           target = concepts_or_concept || @concept
@@ -353,6 +368,73 @@ desig_index)
       def status_uri(status)
         status ? "gloss:status/#{status}" : nil
       end
+
+      # ── Dataset-level non-verbal entity builders (concept-model v3.1.0 K1) ──
+      #
+      # The K1 shapes (FigureShape, TableShape, FormulaShape) constrain
+      # caption/description to a single xsd:string per subject. The domain
+      # models store these as language-keyed hashes; we pick one language
+      # (defaulting to eng, falling back to the first available) at build
+      # time. Multi-language emission would require per-language subjects,
+      # which is beyond K1's scope.
+
+      DEFAULT_RDF_LANG = "eng"
+
+      def build_gloss_figure(figure)
+        Rdf::GlossFigure.new(
+          id: figure.id,
+          identifier: figure.identifier,
+          image: figure.images.first&.src,
+          caption: localized_pick(figure.caption),
+          description: localized_pick(figure.description),
+          images: Array(figure.images).map { |img| build_gloss_figure_image(img) },
+        )
+      end
+
+      def build_gloss_figure_image(image)
+        Rdf::GlossFigureImage.new(
+          src: image.src,
+          format: image.format,
+          role: image.role,
+          # FigureImage doesn't carry byte_size — emit nil so the RDF layer
+          # skips dcat:byteSize rather than emitting a spurious "0".
+          byte_size: nil,
+        )
+      end
+
+      def build_gloss_table(table)
+        Rdf::GlossTable.new(
+          id: table.id,
+          identifier: table.identifier,
+          content: serialize_table_content(table.content),
+          caption: localized_pick(table.caption),
+        )
+      end
+
+      def build_gloss_formula(formula)
+        expression_str = localized_pick(formula.expression)
+        Rdf::GlossFormula.new(
+          id: formula.id,
+          identifier: formula.identifier,
+          expression: expression_str,
+          latex_form: formula.notation == "latex" ? expression_str : nil,
+          description: localized_pick(formula.description),
+        )
+      end
+
+      def localized_pick(localized_hash)
+        return nil unless localized_hash.is_a?(Hash) && !localized_hash.empty?
+
+        localized_hash[DEFAULT_RDF_LANG] ||
+          localized_hash[DEFAULT_RDF_LANG.to_sym] ||
+          localized_hash.values.first
+      end
+
+      def serialize_table_content(content)
+        return nil if content.nil?
+
+        content.is_a?(Hash) ? content.to_yaml : content.to_s
+      end
     end
   end
 end

data/lib/glossarist/version.rb

@@ -4,5 +4,5 @@
 #
 
 module Glossarist
-  VERSION = "2.10.3"
+  VERSION = "2.11.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: glossarist
 version: !ruby/object:Gem::Version
-  version: 2.10.3
+  version: 2.11.0
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-06 00:00:00.000000000 Z
+date: 2026-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -303,16 +303,22 @@ files:
 - lib/glossarist/rdf/gloss_concept_source.rb
 - lib/glossarist/rdf/gloss_designation.rb
 - lib/glossarist/rdf/gloss_detailed_definition.rb
+- lib/glossarist/rdf/gloss_figure.rb
+- lib/glossarist/rdf/gloss_figure_image.rb
+- lib/glossarist/rdf/gloss_formula.rb
 - lib/glossarist/rdf/gloss_grammar_info.rb
 - lib/glossarist/rdf/gloss_locality.rb
 - lib/glossarist/rdf/gloss_localized_concept.rb
 - lib/glossarist/rdf/gloss_non_verbal_rep.rb
 - lib/glossarist/rdf/gloss_pronunciation.rb
 - lib/glossarist/rdf/gloss_reference.rb
+- lib/glossarist/rdf/gloss_table.rb
 - lib/glossarist/rdf/localized_literal.rb
 - lib/glossarist/rdf/lutaml_ext.rb
 - lib/glossarist/rdf/namespaces.rb
+- lib/glossarist/rdf/namespaces/dcat_namespace.rb
 - lib/glossarist/rdf/namespaces/dcterms_namespace.rb
+- lib/glossarist/rdf/namespaces/foaf_namespace.rb
 - lib/glossarist/rdf/namespaces/glossarist_namespace.rb
 - lib/glossarist/rdf/namespaces/iso_thes_namespace.rb
 - lib/glossarist/rdf/namespaces/owl_namespace.rb
@@ -335,6 +341,7 @@ files:
 - lib/glossarist/resolution_adapter/remote.rb
 - lib/glossarist/resolution_adapter/route.rb
 - lib/glossarist/schema_migration.rb
+- lib/glossarist/schema_migration/cli_pipeline.rb
 - lib/glossarist/schema_migration/v0_to_v1.rb
 - lib/glossarist/schema_migration/v2_to_v3.rb
 - lib/glossarist/section.rb