glossarist 2.8.14 → 2.8.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 411f9be5f441296d22581729529924c738bdee6538d99c9085c7b1dc0bbaacc7
-  data.tar.gz: a36be3a51a93fe075f00caec109a80d293edcd18031d85f04eaed4ce9224872f
+  metadata.gz: 2265855682bc867f2ea15fc26c9a2329cf651cb8b34b71634aed79de302565db
+  data.tar.gz: a9b2a8c2df61b61bc9587834448c001286688462eeaa673d48a40afca992abf0
 SHA512:
-  metadata.gz: 37cc79709b04222aa05297f68dfbcde6b1f087027d9e8b7e6fd5c7894b7b6c629a42a4a02f26e8b388fcbedeccf07b23ad3b4bad42290ad8ba4c1d7715f01847
-  data.tar.gz: 1f71874261f1e5e610314106fe5afb08a34f0612cea7aaae6618476e8b743eab4491f8ee01a3393d3463e794e97dc491e18385c482363270ae6c7791867d8c40
+  metadata.gz: 3544b511f83935f75a5ee1e0535f3c2333b914a792fb5c2fe15744f7d5f631d55a8a501a84a4614acf53f676d760e164acd29ed788d85c5b31f8628fc0f4b46c
+  data.tar.gz: 7ca97c724f07c1abaab2198a2f6710e8d477d24a13b933896e928eb0d7be2d24b3644062b46a342642a683f646cc990cc3136564d5bbd30093545e62527f9114

data/README.adoc

@@ -423,7 +423,7 @@ related_concept.ref = Glossarist::ConceptRef.new(source: "IEC", id: "102-03-02")
 [[relationship-types]]
 ==== Relationship Types
 
-Relationship types are drawn from ISO 10241-1, ISO 25964/SKOS, and ISO 12620/TBX. The table below shows each type with its provenance and cross-standard equivalents.
+Relationship types span five standards (ISO 10241-1, ISO 25964/SKOS, ISO 12620/TBX, ISO 19135). The table below shows each of the 52 types with its category and cross-standard equivalents.
 
 [cols="1,1,1,1,1"]
 |===
@@ -435,6 +435,12 @@ Relationship types are drawn from ISO 10241-1, ISO 25964/SKOS, and ISO 12620/TBX
 |—
 |—
 
+|`deprecated_by`
+|Lifecycle
+|deprecated by
+|—
+|—
+
 |`supersedes`
 |Lifecycle
 |supersedes
@@ -447,6 +453,42 @@ Relationship types are drawn from ISO 10241-1, ISO 25964/SKOS, and ISO 12620/TBX
 |—
 |—
 
+|`replaces`
+|Lifecycle (ISO 19135)
+|—
+|—
+|—
+
+|`replaced_by`
+|Lifecycle (ISO 19135)
+|—
+|—
+|—
+
+|`invalidates`
+|Lifecycle (ISO 19135)
+|—
+|—
+|—
+
+|`invalidated_by`
+|Lifecycle (ISO 19135)
+|—
+|—
+|—
+
+|`retires`
+|Lifecycle (ISO 19135)
+|—
+|—
+|—
+
+|`retired_by`
+|Lifecycle (ISO 19135)
+|—
+|—
+|—
+
 |`broader`
 |Hierarchical
 |broader concept
@@ -483,6 +525,18 @@ Relationship types are drawn from ISO 10241-1, ISO 25964/SKOS, and ISO 12620/TBX
 |NTP (narrowerPartitive)
 |narrowerTermPartitive
 
+|`has_part`
+|Hierarchical (partitive)
+|has part
+|—
+|—
+
+|`is_part_of`
+|Hierarchical (partitive)
+|is part of
+|—
+|—
+
 |`broader_instantial`
 |Hierarchical (instantial)
 |—
@@ -495,6 +549,18 @@ Relationship types are drawn from ISO 10241-1, ISO 25964/SKOS, and ISO 12620/TBX
 |NTI (narrowerInstantial)
 |narrowerTermInstantial
 
+|`instance_of`
+|Hierarchical (instantial)
+|instance of
+|—
+|—
+
+|`has_instance`
+|Hierarchical (instantial)
+|has instance
+|—
+|—
+
 |`equivalent`
 |Equivalence
 |equivalent
@@ -543,6 +609,12 @@ Relationship types are drawn from ISO 10241-1, ISO 25964/SKOS, and ISO 12620/TBX
 |RT (relatedTerm)
 |crossReference
 
+|`references`
+|Associative
+|references
+|—
+|—
+
 |`related_concept`
 |Associative
 |—
@@ -561,23 +633,23 @@ Relationship types are drawn from ISO 10241-1, ISO 25964/SKOS, and ISO 12620/TBX
 |—
 |relatedConceptNarrower
 
-|`sequentially_related_concept`
+|`sequentially_related`
 |Associative (sequential)
 |—
 |—
-|sequentiallyRelatedConcept
+|sequentiallyRelated
 
-|`spatially_related_concept`
+|`spatially_related`
 |Associative (spatial)
 |—
 |—
-|spatiallyRelatedConcept
+|spatiallyRelated
 
-|`temporally_related_concept`
+|`temporally_related`
 |Associative (temporal)
 |—
 |—
-|temporallyRelatedConcept
+|temporallyRelated
 
 |`homograph`
 |Lexical
@@ -590,6 +662,66 @@ Relationship types are drawn from ISO 10241-1, ISO 25964/SKOS, and ISO 12620/TBX
 |—
 |—
 |falseFriend
+
+|`has_concept`
+|Register (ISO 19135)
+|—
+|—
+|—
+
+|`is_concept_of`
+|Register (ISO 19135)
+|—
+|—
+|—
+
+|`has_definition`
+|Register (ISO 19135)
+|—
+|—
+|—
+
+|`definition_of`
+|Register (ISO 19135)
+|—
+|—
+|—
+
+|`inherits`
+|Register (ISO 19135)
+|—
+|—
+|—
+
+|`inherited_by`
+|Register (ISO 19135)
+|—
+|—
+|—
+
+|`has_version`
+|Versioning (ISO 19135)
+|—
+|—
+|—
+
+|`version_of`
+|Versioning (ISO 19135)
+|—
+|—
+|—
+
+|`current_version`
+|Versioning (ISO 19135)
+|—
+|—
+|—
+
+|`current_version_of`
+|Versioning (ISO 19135)
+|—
+|—
+|—
 |===
 
 [[id,concept-reference]]
@@ -598,12 +730,12 @@ Relationship types are drawn from ISO 10241-1, ISO 25964/SKOS, and ISO 12620/TBX
 A typed reference to another concept, either local (within the same glossary) or external (in another concept registry).
 
 term:: String — the display text for the referenced concept.
-concept_id:: String — the identifier of the target concept.
+concept_id:: String — the identifier of the target concept. Also accepts the `id` key in YAML (alias for backward compatibility with the concept-model format).
 source:: String — the registry URI prefix for external references (e.g. `urn:iec:std:iec:60050`).
-ref_type:: String — the reference type: `local`, `designation`, or `urn`.
+ref_type:: String — the reference type: `local`, `designation`, `cite`, `section`, `domain`, or `urn`.
 urn:: String — a direct URN for the target concept (e.g. `urn:iec:std:iec:60050-102-01-01`).
 
-Local references use `concept_id` without `source`. External references use `source` + `concept_id` or a direct `urn`.
+Local references use `concept_id` without `source`. External references use `source` + `concept_id` or a direct `urn`. `cite` references resolve against a `ConceptSource#id` in the same concept. `section` references point to a section defined in `register.yaml`.
 
 [,ruby]
 ----
@@ -812,6 +944,58 @@ origin:: The bibliographic <<citation,citation>> for the managed term.
 modification:: A description of the modification to the cited definition of the term, if any, as it is to be applied in the present context.
 
 
+[[dataset-register,Dataset Register]]
+== Dataset Register
+
+A dataset directory may contain a `register.yaml` — the self-describing metadata file. It carries identity (URN, ref, year), structure (ordering, hierarchical sections), provenance (owner, sourceRepo), and relationships (supersedes other datasets).
+
+[,yaml]
+----
+schema_type: glossarist
+schema_version: "3"
+id: iso-19111
+ref: "ISO 19111:2019"
+year: 2019
+urn: "urn:iso:std:iso:19111"
+status: current
+owner: ISO
+languages: [eng, fra]
+ordering: systematic
+sections:
+  - id: "3"
+    names: { eng: "Geometric concepts" }
+    children:
+      - id: "3.1"
+        names: { eng: "Points and lines" }
+----
+
+[[hierarchical-sections,Hierarchical Sections]]
+=== Hierarchical sections
+
+Sections provide structural organization for concepts within a dataset. A section may contain child sections, forming a tree. Concepts reference sections via `domains[]` with `ref_type: section`:
+
+[,yaml]
+----
+data:
+  domains:
+    - source: urn:iso:std:iso:19111
+      id: "3.1"
+      ref_type: section
+----
+
+==== Cascading membership
+
+Section membership is transitive: a concept in section `3.1.1` is also a member of `3.1` and `3` for filtering and display. Use `DatasetRegister#concept_section_ids(concept)` to resolve all sections a concept belongs to, including transitive ancestors.
+
+[,ruby]
+----
+register = Glossarist::DatasetRegister.from_file("path/to/register.yaml")
+register.concept_section_ids(concept)  # => ["3.1", "3"]
+----
+
+When a concept has no explicit `domains[]` entry with `ref_type: section`, section membership is derived from the concept's identifier using the longest registered section prefix (e.g. `103-01-01` → section `103`).
+
+
 == Commands
 
 === generate_latex
@@ -1351,6 +1535,15 @@ Upgrade a dataset to the current schema version.
 glossarist upgrade SOURCE_DIR -o OUTPUT_DIR
 ----
 
+=== version
+
+Show the installed Glossarist version.
+
+[,bash]
+----
+glossarist version
+----
+
 == Glossarist Concept Repository (GCR)
 
 A **GCR** (Glossarist Concept Repository) is a distributable, versioned ZIP archive containing glossary concepts and metadata. GCR packages are created from v2 datasets.

data/lib/glossarist/collections/figure_collection.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Collections
+    class FigureCollection < NonVerbalCollection
+      instances :entries, Figure
+
+      key_value { map_instances to: :entries }
+
+      def self.from_directory(dir)
+        collection = new
+        Dir.glob(File.join(dir, "*.yaml")).each do |path|
+          fig = Figure.from_file(path)
+          collection.store(fig) if fig
+        end
+        collection
+      end
+    end
+  end
+end

data/lib/glossarist/collections/formula_collection.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Collections
+    class FormulaCollection < NonVerbalCollection
+      instances :entries, Formula
+
+      key_value { map_instances to: :entries }
+
+      def self.from_directory(dir)
+        collection = new
+        Dir.glob(File.join(dir, "*.yaml")).each do |path|
+          fml = Formula.from_file(path)
+          collection.store(fml) if fml
+        end
+        collection
+      end
+    end
+  end
+end

data/lib/glossarist/collections/non_verbal_collection.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Collections
+    # Generic collection for dataset-level non-verbal entities
+    # (Figure, Table, Formula). Provides by_id lookup across top-level
+    # entities and recursive subfigures (for Figure).
+    #
+    # Subclasses declare the entity type via `instances`.
+    class NonVerbalCollection < Lutaml::Model::Collection
+      # Find an entity by ID, searching recursively (Figure subfigures).
+      #
+      # @param id [String] the entity or sub-entity ID
+      # @return [NonVerbalEntity, nil]
+      def by_id(target_id)
+        entries.each do |entity|
+          found = entity.find_by_id(target_id)
+          return found if found
+        end
+        nil
+      end
+
+      # All entity IDs including sub-entity IDs (for Figure subfigures).
+      #
+      # @return [Set<String>]
+      def ids
+        Set.new(entries.flat_map(&:all_ids).compact)
+      end
+
+      # Check if an entity with the given ID exists.
+      #
+      # @param id [String]
+      # @return [Boolean]
+      def exists?(id)
+        !by_id(id).nil?
+      end
+
+      # Store an entity.
+      #
+      # @param entity [NonVerbalEntity]
+      def store(entity)
+        entries << entity
+      end
+      alias :<< :store
+
+      def entries
+        @entries ||= []
+      end
+    end
+  end
+end

data/lib/glossarist/collections/table_collection.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Collections
+    class TableCollection < NonVerbalCollection
+      instances :entries, Table
+
+      key_value { map_instances to: :entries }
+
+      def self.from_directory(dir)
+        collection = new
+        Dir.glob(File.join(dir, "*.yaml")).each do |path|
+          tbl = Table.from_file(path)
+          collection.store(tbl) if tbl
+        end
+        collection
+      end
+    end
+  end
+end

data/lib/glossarist/collections.rb

@@ -15,6 +15,14 @@ module Glossarist
              "glossarist/collections/detailed_definition_collection"
     autoload :LocalizationCollection,
              "glossarist/collections/localization_collection"
+    autoload :NonVerbalCollection,
+             "glossarist/collections/non_verbal_collection"
+    autoload :FigureCollection,
+             "glossarist/collections/figure_collection"
+    autoload :TableCollection,
+             "glossarist/collections/table_collection"
+    autoload :FormulaCollection,
+             "glossarist/collections/formula_collection"
     autoload :TypedCollection,
              "glossarist/collections/typed_collection"
   end

data/lib/glossarist/figure.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # A dataset-level figure entity (ISO 10241-1 §6.5 — non-verbal representation).
+  #
+  # Figures are authored once at `datasets/{ds}/figures/{fig-id}.yaml` and
+  # referenced by any number of concepts via stable ID — the same sharing
+  # pattern as bibliography entries. This is the rich, shareable counterpart
+  # to concept-owned NonVerbRep entries.
+  #
+  # A Figure may carry multiple image variants (SVG + PNG + dark/light) for
+  # responsive rendering and accessibility. Composite figures use recursive
+  # subfigures.
+  #
+  # Caption, description, and alt are localized (hash keyed by ISO 639 code).
+  class Figure < NonVerbalEntity
+    attribute :images, FigureImage, collection: true
+    attribute :subfigures, Figure, collection: true
+
+    key_value do
+      map :id, to: :id
+      map :identifier, to: :identifier
+      map :caption, to: :caption
+      map :description, to: :description
+      map :alt, to: :alt
+      map :images, to: :images
+      map :sources, to: :sources
+      map :subfigures, to: :subfigures
+    end
+
+    # Recursively search for a subfigure (or self) by ID.
+    #
+    # @param target_id [String] the figure or subfigure ID
+    # @return [Figure, nil]
+    def find_by_id(target_id)
+      return self if id == target_id
+
+      Array(subfigures).each do |sub|
+        found = sub.find_by_id(target_id)
+        return found if found
+      end
+      nil
+    end
+
+    # Collect this figure's ID and all descendant subfigure IDs.
+    #
+    # @return [Array<String>]
+    def all_ids
+      [id] + Array(subfigures).flat_map(&:all_ids)
+    end
+  end
+end

data/lib/glossarist/figure_image.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # One image variant within a Figure. Multiple variants enable responsive
+  # images, format fallbacks, and accessibility (dark/light, language-specific).
+  #
+  # The `role` field drives consumer-side selection:
+  #   vector  — SVG (preferred for diagrams, resolution-independent)
+  #   raster  — PNG/JPG (preferred for photos)
+  #   dark    — optimized for dark backgrounds
+  #   light   — optimized for light backgrounds
+  #   print   — high-resolution for print output
+  class FigureImage < Lutaml::Model::Serializable
+    attribute :src, :string
+    attribute :format, :string
+    attribute :role, :string
+    attribute :width, :integer
+    attribute :height, :integer
+    attribute :scale, :integer
+
+    key_value do
+      map :src, to: :src
+      map :format, to: :format
+      map :role, to: :role
+      map :width, to: :width
+      map :height, to: :height
+      map :scale, to: :scale
+    end
+  end
+end

data/lib/glossarist/figure_reference.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # A reference from a concept to a dataset-level Figure entity.
+  #
+  # Produced by `figures: [id]` structural arrays and `{{fig:id}}` inline
+  # mentions. Both forms resolve through the same figure adapter.
+  class FigureReference < NonVerbalReference
+    key_value do
+      map :entity_id, to: :entity_id
+      map :display, to: :display
+    end
+
+    def dedup_key
+      [self.class.name, entity_id]
+    end
+  end
+end

data/lib/glossarist/formula.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # A dataset-level formula entity (ISO 10241-1 §6.5 — non-verbal representation).
+  #
+  # Formulas are authored at `datasets/{ds}/formulas/{formula-id}.yaml` and
+  # shared across concepts. The mathematical expression is stored in a
+  # notation format (LaTeX, MathML, AsciiMath). Caption, description, and
+  # alt are localized for accessibility.
+  class Formula < NonVerbalEntity
+    attribute :expression, :hash
+    attribute :notation, :string
+
+    key_value do
+      map :id, to: :id
+      map :identifier, to: :identifier
+      map :caption, to: :caption
+      map :description, to: :description
+      map :alt, to: :alt
+      map :expression, to: :expression
+      map :notation, to: :notation
+      map :sources, to: :sources
+    end
+  end
+end

data/lib/glossarist/formula_reference.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # A reference from a concept to a dataset-level Formula entity.
+  #
+  # Produced by `formulas: [id]` structural arrays and `{{formula:id}}` inline
+  # mentions.
+  class FormulaReference < NonVerbalReference
+    key_value do
+      map :entity_id, to: :entity_id
+      map :display, to: :display
+    end
+
+    def dedup_key
+      [self.class.name, entity_id]
+    end
+  end
+end

data/lib/glossarist/localized_string.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # Semantic operations on localized string fields.
+  #
+  # Localized strings are stored as hashes keyed by ISO 639 language code:
+  #   { "eng" => "Mixed reflection", "fra" => "Réflexion mixte" }
+  #
+  # This module provides typed access and fallback logic. It does not
+  # introduce a wrapper class — the hash IS the localized string, matching
+  # how Section#names, DatasetRegister#description, etc. already work.
+  module LocalizedString
+    # Fetch a localized value with language fallback.
+    #
+    # @param hash [Hash, nil] the localized string hash
+    # @param lang [String, Symbol] the desired language code
+    # @param fallback [String, nil] fallback language (default "eng")
+    # @return [String, nil] the localized value, or nil if not found
+    def self.fetch(hash, lang, fallback = "eng")
+      return nil unless hash.is_a?(Hash)
+
+      direct = hash[lang.to_s] || hash[lang.to_sym]
+      return direct if direct
+
+      fallback && fallback.to_s != lang.to_s ? hash[fallback.to_s] || hash[fallback.to_sym] : nil
+    end
+
+    # Check if a localized string hash is nil or empty.
+    #
+    # @param hash [Hash, nil]
+    # @return [Boolean]
+    def self.empty?(hash)
+      hash.nil? || hash.empty?
+    end
+
+    # Check if a localized string hash has any entries.
+    #
+    # @param hash [Hash, nil]
+    # @return [Boolean]
+    def self.present?(hash)
+      !empty?(hash)
+    end
+  end
+end

data/lib/glossarist/managed_concept_data.rb

@@ -7,6 +7,9 @@ module Glossarist
     attribute :localized_concepts, :hash
     attribute :domains, ConceptReference, collection: true
     attribute :tags, :string, collection: true
+    attribute :figures, FigureReference, collection: true
+    attribute :tables, TableReference, collection: true
+    attribute :formulas, FormulaReference, collection: true
     attribute :sources, ConceptSource, collection: true
     attribute :localizations, LocalizedConcept,
               collection: Collections::LocalizationCollection,
@@ -21,6 +24,12 @@ module Glossarist
       map %i[domains groups], to: :domains,
                               with: { from: :domains_from_yaml, to: :domains_to_yaml }
       map :tags, to: :tags
+      map :figures, to: :figures,
+                    with: { from: :figures_from_yaml, to: :figures_to_yaml }
+      map :tables, to: :tables,
+                   with: { from: :tables_from_yaml, to: :tables_to_yaml }
+      map :formulas, to: :formulas,
+                     with: { from: :formulas_from_yaml, to: :formulas_to_yaml }
       map :sources, to: :sources
       map :localizations, to: :localizations,
                           with: { from: :localizations_from_yaml, to: :localizations_to_yaml }
@@ -63,6 +72,46 @@ module Glossarist
       doc["domains"] = model.domains.map(&:to_hash)
     end
 
+    def figures_from_yaml(model, value)
+      model.figures = parse_non_verbal_refs(value, FigureReference)
+    end
+
+    def figures_to_yaml(model, doc)
+      serialize_non_verbal_refs(model.figures, doc, "figures")
+    end
+
+    def tables_from_yaml(model, value)
+      model.tables = parse_non_verbal_refs(value, TableReference)
+    end
+
+    def tables_to_yaml(model, doc)
+      serialize_non_verbal_refs(model.tables, doc, "tables")
+    end
+
+    def formulas_from_yaml(model, value)
+      model.formulas = parse_non_verbal_refs(value, FormulaReference)
+    end
+
+    def formulas_to_yaml(model, doc)
+      serialize_non_verbal_refs(model.formulas, doc, "formulas")
+    end
+
+    private
+
+    def parse_non_verbal_refs(value, ref_class)
+      return unless value.is_a?(Array)
+
+      value.map { |item| ref_class.of_yaml(item) }
+    end
+
+    def serialize_non_verbal_refs(refs, doc, key)
+      return if refs.nil? || refs.empty?
+
+      doc[key] = refs.map do |ref|
+        ref.display ? { "ref" => ref.entity_id, "display" => ref.display } : ref.entity_id
+      end
+    end
+
     def authoritative_source
       return [] unless sources
 

data/lib/glossarist/non_verb_rep.rb

@@ -13,17 +13,23 @@ module Glossarist
   # - +type+: one of "image", "table", "formula"
   # - +ref+: URI reference to the resource (relative path, URN, or URL)
   # - +text+: optional text description or alt text
+  # - +caption+: localized title/caption (accessibility)
+  # - +description+: localized long description (accessibility)
   # - +sources+: bibliographic sources for the representation
   class NonVerbRep < Lutaml::Model::Serializable
     attribute :type, :string
     attribute :ref, :string
     attribute :text, :string
+    attribute :caption, :hash
+    attribute :description, :hash
     attribute :sources, ConceptSource, collection: true
 
     key_value do
       map :type, to: :type
       map :ref, to: :ref
       map :text, to: :text
+      map :caption, to: :caption
+      map :description, to: :description
       map :sources, to: :sources
     end
   end

data/lib/glossarist/non_verbal_entity.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # Abstract base for dataset-level non-verbal representation entities.
+  #
+  # Figures, Tables, and Formulas share common metadata: stable identity,
+  # localized caption/description (accessibility), and provenance sources.
+  # Each is authored once at the dataset level and referenced by any number
+  # of concepts — the same pattern as bibliography entries.
+  #
+  # This is the dataset-level counterpart to NonVerbRep (ISO 10241-1 §6.5),
+  # which remains the concept-owned inline form.
+  #
+  # Subclasses (Figure, Table, Formula) add type-specific content fields.
+  class NonVerbalEntity < Lutaml::Model::Serializable
+    attribute :id, :string
+    attribute :identifier, :string
+    attribute :caption, :hash
+    attribute :description, :hash
+    attribute :alt, :hash
+    attribute :sources, ConceptSource, collection: true
+
+    key_value do
+      map :id, to: :id
+      map :identifier, to: :identifier
+      map :caption, to: :caption
+      map :description, to: :description
+      map :alt, to: :alt
+      map :sources, to: :sources
+    end
+
+    # Find self by ID. Figure overrides for recursive subfigure search.
+    #
+    # @param target_id [String]
+    # @return [NonVerbalEntity, nil]
+    def find_by_id(target_id)
+      id == target_id ? self : nil
+    end
+
+    # This entity's IDs. Figure overrides to include subfigure IDs.
+    #
+    # @return [Array<String>]
+    def all_ids
+      [id]
+    end
+
+    def self.from_file(path)
+      return nil unless File.exist?(path)
+
+      from_yaml(File.read(path, encoding: "utf-8"))
+    end
+  end
+end

data/lib/glossarist/non_verbal_reference.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # Abstract base for references to dataset-level non-verbal entities.
+  #
+  # FigureReference, TableReference, and FormulaReference all carry an
+  # entity ID and an optional display override. They are produced both by
+  # structural arrays (`figures: [id]` on ManagedConceptData) and by inline
+  # mentions (`{{fig:id}}` in text).
+  class NonVerbalReference < Lutaml::Model::Serializable
+    attribute :entity_id, :string
+    attribute :display, :string
+
+    def self.of_yaml(hash)
+      return new(entity_id: hash) if hash.is_a?(String)
+
+      new(
+        entity_id: hash["ref"] || hash["id"] || hash[:ref] || hash[:id],
+        display: hash["display"] || hash[:display],
+      )
+    end
+  end
+end

data/lib/glossarist/reference_extractor.rb

@@ -226,6 +226,15 @@ module Glossarist
       AssetReference.new(path: path.strip)
     end
 
+    # Unified non-verbal entity mention resolver for fig:/table:/formula:.
+    # Strips the prefix and produces the appropriate reference type.
+    def resolve_non_verbal_mention(prefix, identifier, display, ref_class)
+      cleaned = identifier.delete_prefix(prefix).strip
+      return nil if cleaned.empty?
+
+      ref_class.new(entity_id: cleaned, display: display)
+    end
+
     private
 
     def gather_texts(lc_hash)
@@ -293,6 +302,18 @@ module Glossarist
       ext.resolve_cite_key(identifier, display)
     end
 
+    register_identifier_resolver("fig:") do |ext, identifier, display|
+      ext.resolve_non_verbal_mention("fig:", identifier, display, FigureReference)
+    end
+
+    register_identifier_resolver("table:") do |ext, identifier, display|
+      ext.resolve_non_verbal_mention("table:", identifier, display, TableReference)
+    end
+
+    register_identifier_resolver("formula:") do |ext, identifier, display|
+      ext.resolve_non_verbal_mention("formula:", identifier, display, FormulaReference)
+    end
+
     register_identifier_resolver("urn:iec:std:iec:60050") do |ext, identifier, display|
       ext.resolve_iec_urn(identifier, display)
     end

data/lib/glossarist/table.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # A dataset-level table entity (ISO 10241-1 §6.5 — non-verbal representation).
+  #
+  # Tables are authored at `datasets/{ds}/tables/{table-id}.yaml` and shared
+  # across concepts. The content is stored as structured data (rows/columns)
+  # or as a markup string (HTML, Markdown, AsciiDoc). Caption, description,
+  # and alt are localized for accessibility.
+  class Table < NonVerbalEntity
+    attribute :content, :hash
+    attribute :format, :string
+
+    key_value do
+      map :id, to: :id
+      map :identifier, to: :identifier
+      map :caption, to: :caption
+      map :description, to: :description
+      map :alt, to: :alt
+      map :content, to: :content
+      map :format, to: :format
+      map :sources, to: :sources
+    end
+  end
+end

data/lib/glossarist/table_reference.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Glossarist
+  # A reference from a concept to a dataset-level Table entity.
+  #
+  # Produced by `tables: [id]` structural arrays and `{{table:id}}` inline
+  # mentions.
+  class TableReference < NonVerbalReference
+    key_value do
+      map :entity_id, to: :entity_id
+      map :display, to: :display
+    end
+
+    def dedup_key
+      [self.class.name, entity_id]
+    end
+  end
+end

data/lib/glossarist/version.rb

@@ -4,5 +4,5 @@
 #
 
 module Glossarist
-  VERSION = "2.8.14"
+  VERSION = "2.8.15"
 end

data/lib/glossarist.rb

@@ -38,6 +38,16 @@ module Glossarist
   autoload :ConceptDocument,          "glossarist/concept_document"
   autoload :ConceptEnricher, "glossarist/concept_enricher"
   autoload :Config,                   "glossarist/config"
+  autoload :LocalizedString,          "glossarist/localized_string"
+  autoload :NonVerbalEntity,          "glossarist/non_verbal_entity"
+  autoload :NonVerbalReference,       "glossarist/non_verbal_reference"
+  autoload :Figure,                   "glossarist/figure"
+  autoload :FigureImage,              "glossarist/figure_image"
+  autoload :FigureReference,          "glossarist/figure_reference"
+  autoload :Table,                    "glossarist/table"
+  autoload :TableReference,           "glossarist/table_reference"
+  autoload :Formula,                  "glossarist/formula"
+  autoload :FormulaReference,         "glossarist/formula_reference"
   autoload :DatasetValidator,         "glossarist/dataset_validator"
   autoload :CustomLocality,           "glossarist/custom_locality"
   autoload :DetailedDefinition,       "glossarist/detailed_definition"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: glossarist
 version: !ruby/object:Gem::Version
-  version: 2.8.14
+  version: 2.8.15
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-16 00:00:00.000000000 Z
+date: 2026-06-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: lutaml-model
@@ -195,7 +195,11 @@ files:
 - lib/glossarist/collections/concept_source_collection.rb
 - lib/glossarist/collections/designation_collection.rb
 - lib/glossarist/collections/detailed_definition_collection.rb
+- lib/glossarist/collections/figure_collection.rb
+- lib/glossarist/collections/formula_collection.rb
 - lib/glossarist/collections/localization_collection.rb
+- lib/glossarist/collections/non_verbal_collection.rb
+- lib/glossarist/collections/table_collection.rb
 - lib/glossarist/collections/typed_collection.rb
 - lib/glossarist/comparison_result.rb
 - lib/glossarist/concept.rb
@@ -235,6 +239,11 @@ files:
 - lib/glossarist/errors/invalid_type_error.rb
 - lib/glossarist/errors/load_error.rb
 - lib/glossarist/errors/parse_error.rb
+- lib/glossarist/figure.rb
+- lib/glossarist/figure_image.rb
+- lib/glossarist/figure_reference.rb
+- lib/glossarist/formula.rb
+- lib/glossarist/formula_reference.rb
 - lib/glossarist/gcr_metadata.rb
 - lib/glossarist/gcr_package.rb
 - lib/glossarist/gcr_package_definition.rb
@@ -244,10 +253,13 @@ files:
 - lib/glossarist/glossary_store.rb
 - lib/glossarist/locality.rb
 - lib/glossarist/localized_concept.rb
+- lib/glossarist/localized_string.rb
 - lib/glossarist/managed_concept.rb
 - lib/glossarist/managed_concept_collection.rb
 - lib/glossarist/managed_concept_data.rb
 - lib/glossarist/non_verb_rep.rb
+- lib/glossarist/non_verbal_entity.rb
+- lib/glossarist/non_verbal_reference.rb
 - lib/glossarist/pronunciation.rb
 - lib/glossarist/rdf.rb
 - lib/glossarist/rdf/gloss_citation.rb
@@ -298,6 +310,8 @@ files:
 - lib/glossarist/sts/importer.rb
 - lib/glossarist/sts/term_extractor.rb
 - lib/glossarist/sts/term_mapper.rb
+- lib/glossarist/table.rb
+- lib/glossarist/table_reference.rb
 - lib/glossarist/transforms.rb
 - lib/glossarist/transforms/concept_to_gloss_transform.rb
 - lib/glossarist/transforms/concept_to_tbx_transform.rb