glossarist 2.8.14 → 2.8.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 411f9be5f441296d22581729529924c738bdee6538d99c9085c7b1dc0bbaacc7
-  data.tar.gz: a36be3a51a93fe075f00caec109a80d293edcd18031d85f04eaed4ce9224872f
+  metadata.gz: 3dff1f025f20e6cfad5028acb99816984ddef4cd4a231991345a633c42ae5794
+  data.tar.gz: 7eed6c0df552c7206225460f212500fac6e4c7f3bc47d04bf75bb11acd53af7d
 SHA512:
-  metadata.gz: 37cc79709b04222aa05297f68dfbcde6b1f087027d9e8b7e6fd5c7894b7b6c629a42a4a02f26e8b388fcbedeccf07b23ad3b4bad42290ad8ba4c1d7715f01847
-  data.tar.gz: 1f71874261f1e5e610314106fe5afb08a34f0612cea7aaae6618476e8b743eab4491f8ee01a3393d3463e794e97dc491e18385c482363270ae6c7791867d8c40
+  metadata.gz: 01bda07bdfcff32b5526b33e19bd38074f0eeeab585bdf739593c95f9edacdd85cff549ce7430b53a027b18b1cd011a99a33454f71fdb2163c57be6bb1a1affb
+  data.tar.gz: f9e036c52fa7fa63dab55c8623bd47bc46af544d1fa3660368c8f41ef9c9155373ca92ac91116c8f8d7ff18b1ca9e093fde4f6e25ce0ca7b8194c9724b2df75d

data/CLAUDE.md

@@ -71,6 +71,31 @@ Designation inheritance hierarchy (MECE):
 - Supports both camelCase and snake_case keys in YAML (e.g., `localizedConcepts` / `localized_concepts`) using `%i[key1 key2]` mapping syntax.
 - Also supports V1 format (`concept-*.yaml` files at root level).
 
+### V3 Dataset Syntax (collection files are single-key mappings)
+
+A dataset collection file — `bibliography.yaml`, `images.yaml`, and any future
+equivalent — is the *V3 glossarist dataset syntax*: a YAML **mapping with a
+single wrapper key** whose value is an **array of typed items**. No keyed maps
+(indexing items by an out-of-band reference string), and no stray top-level
+arrays — the array is always grouped under one named key. Each item carries its
+own `id` field. (A keyed bibliography was tried and rejected as wrong — a
+bibliography is an ordered collection, not a map, and keying forced the entry to
+degenerate into `citation_key` + an untyped `data` hash. A bare top-level array
+was also rejected — the user does not want stray arrays at the document root.)
+
+Canonical models: `BibliographyData` + typed `BibliographyEntry`;
+`V3::ImageFile` + `V3::ImageEntry`. `bibliography.yaml` wraps its entries under a
+single `bibliography:` key. Because the root is a mapping, one `key_value` map
+(`map "bibliography", to: :entries`) drives both the file (`to_yaml`/`from_yaml`)
+and the in-memory store (`to_hash`/`from_hash`) — no overrides, no nested
+Collection, no `YAML.safe_load`. `BibliographyData#shortname` is the
+PackageStore record key only — never serialized. Documentation lives in
+`README.adoc` (`== Bibliography`); this note is internal guidance, not user docs.
+
+The remaining `map nil` keyed patterns live only in the **V1 legacy adapters**
+(`v1/register.rb`, `v1/concept.rb`), which are intentional passthroughs for old
+IEV-format datasets — do not "fix" them; that would break reading V1 data.
+
 ### Configuration & Extensibility
 
 - **`Config`** (`config.rb`) — singleton that holds registered classes for `:localized_concept` and `:managed_concept`. Allows swapping implementations via `register_class`.

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]
 ----
@@ -779,23 +911,35 @@ result.diffs            # Array of ConceptDiff with similarity scores
 
 === NonVerbRep
 
-Non-verbal representations are associated resources (images, tables, formulas) used to help define a concept (ISO 10241-1 §6.5). They live outside the concept model and are referenced by URI. Resources can be shared across concepts and belong either to the dataset package (relative path) or are externally referenced (URL/URN).
+Non-verbal representations are associated resources (images, tables, formulas) used to help define a concept (ISO 10241-1 §6.5). NonVerbRep is the concept-local form — attached directly to a concept's data; the dataset-shared form is xref:figure[Figure] / Table / Formula. Both share the same accessibility payload via `NonVerbalEntity`.
 
-type:: String — the type of representation: `image`, `table`, or `formula`.
-ref:: String — URI reference to the resource (relative path within the GCR package, URN, or URL).
-text:: String — optional text description or alt text.
+type:: String — the kind of representation: `image`, `table`, or `formula`.
+images:: Collection of `FigureImage` variants (responsive, format fallbacks, dark/light). Used when `type: image`.
+caption:: Localized hash — short title keyed by ISO 639 code (e.g. `{ eng: "..." }`).
+description:: Localized hash — long description for accessibility.
+alt:: Localized hash — short alternative text for screen readers.
 sources:: Collection of <<concept-source,ConceptSource>> entries — bibliographic sources for the representation.
 
 Example:
 +
 [,yaml]
 ----
-non_verbal_rep:
+non_verb_rep:
   - type: image
-    ref: assets/images/figure-1.svg
-    text: Diagram showing the concept hierarchy
+    images:
+      - src: assets/images/figure-1.svg
+        format: svg
+        role: vector
+      - src: assets/images/figure-1.png
+        format: png
+        role: raster
+    caption:
+      eng: Concept hierarchy
+    alt:
+      eng: Diagram showing the concept hierarchy
   - type: formula
-    ref: urn:gcr:assets:formula-eq1
+    images:
+      - src: urn:gcr:assets:formula-eq1
     sources:
       - type: authoritative
         status: identical
@@ -812,6 +956,100 @@ 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`).
+
+
+[[bibliography,Bibliography]]
+== Bibliography
+
+A dataset directory may contain a `bibliography.yaml` — the dataset's bibliography, an ordered collection of the bibliographic references cited by its concepts. It is a YAML *mapping with a single key*, `bibliography`, whose value is an array of typed entries. This is the **V3 glossarist dataset syntax** for a collection file: a typed list grouped under one wrapper key, never a keyed map and never a stray top-level array. Each entry carries its own `id` — the identifier is a field on the item, not an out-of-band hash key.
+
+[,yaml]
+----
+bibliography:
+- id: ref_1
+  reference: ISO 704
+  title: Terminology work — Principles and methods
+- id: ref_23
+  reference: UNECE TRANS/WP29/1045
+  title: Common definitions of vehicle categories, masses and dimensions
+  link: https://www.unece.org/fileadmin/DAM/trans/doc/2005/wp29/TRANS-WP29-1045e.pdf
+- id: iso_std_iso_15704_en
+  reference: ISO 15704
+----
+
+`BibliographyEntry` fields:
+
+[cols="1,4"]
+|===
+|Field |Description
+
+|`id` |Entry identifier, dataset-unique. Cited from concept sources and inline `{{cite:...}}` mentions.
+|`reference` |Publication reference string (e.g. `ISO 704`, `IEC 60050`).
+|`title` |Title of the referenced document.
+|`link` |Optional URL to the referenced document.
+|`type` |Optional document type (e.g. `standard`).
+|===
+
+[,ruby]
+----
+bib = Glossarist::BibliographyData.from_file("path/to/bibliography.yaml")
+bib.entries            # => [#<BibliographyEntry id: "ref_1", ...>, ...]
+bib.find("ref_1")      # => #<BibliographyEntry ...>
+bib.keys               # => ["ref_1", "ref_23", ...]
+----
+
+The same single-key convention applies to every dataset collection file (`images.yaml`, and any future equivalent): the collection is an array of typed items grouped under one wrapper key.
+
 == Commands
 
 === generate_latex
@@ -1351,6 +1589,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/bibliography_data.rb

@@ -1,41 +1,49 @@
 # frozen_string_literal: true
 
 module Glossarist
+  # The bibliography of a dataset, persisted as bibliography.yaml.
+  #
+  # The file is the *V3 glossarist dataset syntax* for a collection: a YAML
+  # mapping with a single key, +bibliography+, whose value is an array of typed
+  # BibliographyEntry items. A bibliography is an ordered collection of
+  # references, not a keyed map, so each item carries its own +id+ field rather
+  # than being indexed by an out-of-band reference string. The single wrapper
+  # key keeps the document root a mapping (no stray top-level array).
+  #
+  # Because the root is a mapping, a single +key_value+ mapping drives both the
+  # file (#to_yaml / .from_yaml) and the in-memory store (#to_hash /
+  # .from_hash) — no special-case serialization.
+  #
+  # +shortname+ is internal bookkeeping only: lutaml-store's PackageStore needs
+  # a key field to store the bibliography as a single record. It is never
+  # serialized — only the +bibliography+ key appears in the file.
   class BibliographyData < Lutaml::Model::Serializable
     attribute :shortname, :string, default: -> { "bibliography" }
     attribute :entries, BibliographyEntry, collection: true,
                                            initialize_empty: true
 
     key_value do
-      map nil, to: :entries,
-               with: { from: :entries_from_hash, to: :entries_to_hash }
+      map "bibliography", to: :entries
     end
 
-    def find(citation_key)
-      entries.find { |e| e.citation_key == citation_key }
-    end
+    class << self
+      def from_file(path)
+        return nil unless File.exist?(path)
 
-    def keys
-      entries.map(&:citation_key)
+        from_yaml(File.read(path, encoding: "utf-8"))
+      end
     end
 
-    def [](citation_key)
-      entry = find(citation_key)
-      entry&.data
+    def find(id)
+      entries.find { |e| e.id == id.to_s }
     end
 
-    def entries_from_hash(model, value)
-      return unless value.is_a?(Hash)
-
-      model.entries = value.map do |key, data|
-        BibliographyEntry.new(citation_key: key, data: data || {})
-      end
+    def keys
+      entries.map(&:id)
     end
 
-    def entries_to_hash(model, doc)
-      model.entries.each do |entry|
-        doc[entry.citation_key] = entry.data
-      end
+    def [](id)
+      find(id)
     end
   end
 end

data/lib/glossarist/bibliography_entry.rb

@@ -1,13 +1,24 @@
 # frozen_string_literal: true
 
 module Glossarist
+  # A single bibliographic item in a dataset's bibliography.
+  #
+  # A bibliography is an ordered collection of references, so bibliography.yaml
+  # is a YAML sequence (array) of these typed entries. The entry's identifier is
+  # the +id+ field on each item — never an out-of-band hash key.
   class BibliographyEntry < Lutaml::Model::Serializable
-    attribute :citation_key, :string
-    attribute :data, :hash, default: -> { {} }
+    attribute :id, :string
+    attribute :reference, :string
+    attribute :title, :string
+    attribute :link, :string
+    attribute :type, :string
 
     key_value do
-      map "citation_key", to: :citation_key
-      map "data", to: :data
+      map :id, to: :id
+      map :reference, to: :reference
+      map :title, to: :title
+      map :link, to: :link
+      map :type, to: :type
     end
   end
 end

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