glossarist 2.6.6 → 2.6.7

data/lib/glossarist/validation/rules/ref_shape_rule.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Validation
+    module Rules
+      class RefShapeRule < Base
+        def code = "GLS-305"
+        def category = :schema
+        def severity = "error"
+        def scope = :concept
+
+        def applicable?(context)
+          context.concept.localizations&.any?
+        end
+
+        def check(context)
+          concept = context.concept
+          fname = context.file_name
+          issues = []
+
+          check_sources(concept, fname, issues)
+          check_related(concept, fname, issues)
+
+          issues
+        end
+
+        private
+
+        def check_sources(concept, fname, issues)
+          concept.localizations.flat_map(&:all_sources).each_with_index do |source, idx|
+            origin = source.origin
+            next unless origin
+
+            ref = origin.ref
+            if ref.nil?
+              issues << issue(
+                "source #{idx + 1} origin has nil ref (expected Citation::Ref hash)",
+                location: fname,
+                suggestion: "Set origin.ref to { source: ..., id: ... }",
+              )
+            elsif ref.source.nil? && ref.id.nil?
+              issues << issue(
+                "source #{idx + 1} origin.ref has neither source nor id",
+                location: fname,
+                suggestion: "Provide at least origin.ref.source or origin.ref.id",
+              )
+            end
+          end
+        end
+
+        def check_related(concept, fname, issues)
+          (concept.related || []).each_with_index do |rel, idx|
+            ref = rel.ref
+            next unless ref
+
+            if ref.source.nil? && ref.id.nil?
+              issues << issue(
+                "related concept #{idx + 1} has empty ref (no source or id)",
+                location: fname,
+                suggestion: "Provide at least ref.source or ref.id",
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/glossarist/validation/rules/related_concept_cycle_rule.rb

@@ -58,9 +58,7 @@ module Glossarist
           ref = rel.ref
           return nil unless ref
 
-          if ref.is_a?(Glossarist::Citation)
-            ref.id || ref.text
-          end
+          ref.id || ref.source
         end
 
         def detect_cycles(graph)

data/lib/glossarist/validation/rules/related_concept_symmetry_rule.rb

@@ -77,9 +77,7 @@ module Glossarist
           ref = rel.ref
           return nil unless ref
 
-          if ref.is_a?(Glossarist::Citation)
-            ref.id || ref.text
-          end
+          ref.id || ref.source
         end
       end
     end

data/lib/glossarist/validation/rules/related_concept_target_rule.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Validation
+    module Rules
+      # Verifies that related concept refs point to concepts that exist
+      # in the dataset (for local refs) or have valid source/URN (for external).
+      class RelatedConceptTargetRule < Base
+        URN_RE = %r{\Aurn:[a-z0-9][a-z0-9-]{0,31}:[a-z0-9()+,\-.:=@;$_!*'%/?#]+\z}i.freeze
+
+        def code = "GLS-110"
+        def category = :references
+        def severity = "warning"
+        def scope = :concept
+
+        def applicable?(context)
+          context.concept.related&.any?
+        end
+
+        def check(context)
+          concept = context.concept
+          fname = context.file_name
+          issues = []
+
+          (concept.related || []).each_with_index do |rel, idx|
+            ref = rel.ref
+            next unless ref
+
+            id = ref.id
+            source = ref.source
+
+            if id && local_ref?(source)
+              # Local ref — concept_id must exist in dataset
+              unless context.concept_ids.include?(id)
+                issues << issue(
+                  "related concept #{idx + 1} references '#{id}' which is not in the dataset",
+                  location: fname,
+                  suggestion: "Add concept '#{id}' to the dataset or fix the reference",
+                )
+              end
+            elsif source && !id
+              # Source-only ref — should be a valid URN or known format
+              if source.start_with?("urn:") && !URN_RE.match?(source)
+                issues << issue(
+                  "related concept #{idx + 1} has invalid URN '#{source}'",
+                  location: fname,
+                  suggestion: "Fix the URN format (e.g. urn:iso:std:iso:ts:14812)",
+                )
+              end
+            end
+          end
+
+          issues
+        end
+
+        private
+
+        def local_ref?(source)
+          source.nil? || source.strip.empty?
+        end
+      end
+    end
+  end
+end

data/lib/glossarist/validation/rules/schema_version_rule.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Validation
+    module Rules
+      class SchemaVersionRule < Base
+        def code = "GLS-010"
+        def category = :schema
+        def severity = "warning"
+        def scope = :concept
+
+        def applicable?(context)
+          context.concept.is_a?(ManagedConcept)
+        end
+
+        def check(context)
+          concept = context.concept
+          fname = context.file_name
+          issues = []
+
+          version = concept.schema_version
+          if version.nil? || version.to_s.strip.empty?
+            issues << issue(
+              "concept has no schema_version",
+              location: fname,
+              suggestion: "Add schema_version: \"3\" to the concept",
+            )
+          elsif version.to_s != "3"
+            issues << issue(
+              "concept has schema_version '#{version}', expected '3'",
+              location: fname,
+              suggestion: "Run schema migration to upgrade to version 3",
+            )
+          end
+
+          issues
+        end
+      end
+    end
+  end
+end

data/lib/glossarist/validation/rules/source_type_rule.rb

@@ -21,7 +21,7 @@ module Glossarist
           fname = context.file_name
           issues = []
 
-          gather_all_sources(concept).each_with_index do |source, idx|
+          concept.localizations.flat_map(&:all_sources).each_with_index do |source, idx|
             unless VALID_TYPES.include?(source.type)
               issues << issue(
                 "source #{idx + 1} has invalid type '#{source.type}'",
@@ -43,21 +43,7 @@ module Glossarist
 
           issues
         end
-
-        private
-
-        def gather_all_sources(concept)
-          sources = []
-          concept.localizations.each do |l10n|
-            (l10n.data&.sources || []).each { |s| sources << s }
-            (l10n.data&.definition || []).each { |d| (d.sources || []).each { |s| sources << s } }
-            (l10n.data&.notes || []).each { |n| (n.sources || []).each { |s| sources << s } }
-            (l10n.data&.examples || []).each { |e| (e.sources || []).each { |s| sources << s } }
-          end
-          sources
-        end
       end
     end
   end
 end
-

data/lib/glossarist/validation/rules/source_urn_format_rule.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Validation
+    module Rules
+      # Validates that every URN-format source in citations and references
+      # follows a recognized scheme (iso, iec, itu, etc).
+      class SourceUrnFormatRule < Base
+        URN_RE = %r{\Aurn:([a-z0-9][a-z0-9-]{0,31}):(.+)\z}i.freeze
+
+        KNOWN_SCHEMES = %w[
+          iso iec itu iso:std:iso iso:std:iec
+        ].freeze
+
+        def code = "GLS-310"
+        def category = :quality
+        def severity = "warning"
+        def scope = :concept
+
+        def applicable?(context)
+          context.concept.localizations&.any?
+        end
+
+        def check(context)
+          concept = context.concept
+          fname = context.file_name
+          issues = []
+
+          all_refs(concept).each_with_index do |ref_str, idx|
+            next unless ref_str && ref_str.start_with?("urn:")
+
+            match = URN_RE.match(ref_str)
+            unless match
+              issues << issue(
+                "source #{idx + 1} has malformed URN '#{ref_str}'",
+                location: fname,
+                suggestion: "Fix the URN to follow RFC 8141 format",
+              )
+            end
+          end
+
+          issues
+        end
+
+        private
+
+        def all_refs(concept)
+          refs = []
+          concept.localizations.each do |l10n|
+            (l10n.data&.sources || []).each do |s|
+              refs << s.origin&.ref&.source if s.origin&.ref&.source&.start_with?("urn:")
+            end
+          end
+          (concept.data&.domains || []).each do |d|
+            refs << d.urn if d.urn
+          end
+          (concept.related || []).each do |r|
+            refs << r.ref&.source if r.ref&.source&.start_with?("urn:")
+          end
+          refs.compact
+        end
+      end
+    end
+  end
+end

data/lib/glossarist/validation/rules/uuid_format_rule.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Glossarist
+  module Validation
+    module Rules
+      class UuidFormatRule < Base
+        UUID_RE = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i.freeze
+
+        def code = "GLS-016"
+        def category = :integrity
+        def severity = "error"
+        def scope = :concept
+
+        def check(context)
+          concept = context.concept
+          fname = context.file_name
+          issues = []
+
+          uuid = concept.uuid
+          if uuid && !uuid.to_s.empty? && !UUID_RE.match?(uuid.to_s)
+            issues << issue(
+              "concept UUID '#{uuid}' is not valid UUID format",
+              location: fname,
+              suggestion: "Use a valid UUID (e.g. 0ce27901-02ce-531e-8ba5-fdb136139d1a)",
+            )
+          end
+
+          issues
+        end
+      end
+    end
+  end
+end

data/lib/glossarist/validation/rules.rb

@@ -40,46 +40,13 @@ require_relative "rules/date_type_rule"
 require_relative "rules/language_code_format_rule"
 require_relative "rules/designation_type_rule"
 require_relative "rules/date_validity_rule"
-
-# Register all built-in rules
-module Glossarist
-  module Validation
-    module Rules
-      R = Registry
-
-      R.register(ConceptIdRule)
-      R.register(ConceptIdUniquenessRule)
-      R.register(LocalizationPresenceRule)
-      R.register(EntryStatusRule)
-      R.register(AsciidocXrefRule)
-      R.register(ImageReferenceRule)
-      R.register(ConceptMentionRule)
-      R.register(ConceptCountRule)
-      R.register(LanguageListRule)
-      R.register(LanguageCoverageRule)
-      R.register(FilenameIdRule)
-      R.register(L10nUuidIntegrityRule)
-      R.register(OrphanedL10nFilesRule)
-      R.register(OrphanedBibliographyRule)
-      R.register(OrphanedImagesRule)
-      R.register(DefinitionContentRule)
-      R.register(PreferredTermRule)
-      R.register(DuplicateTermRule)
-      R.register(CitationCompletenessRule)
-      R.register(AuthoritativeSourceRule)
-      R.register(RelatedConceptRule)
-      R.register(ConceptStatusRule)
-      R.register(SourceEnumRule)
-      R.register(TermsPresenceRule)
-      R.register(BibliographyYamlRule)
-      R.register(ConceptUriRule)
-      R.register(RelatedConceptSymmetryRule)
-      R.register(RelatedConceptCycleRule)
-      R.register(DesignationStatusRule)
-      R.register(DateTypeRule)
-      R.register(LanguageCodeFormatRule)
-      R.register(DesignationTypeRule)
-      R.register(DateValidityRule)
-    end
-  end
-end
+require_relative "rules/schema_version_rule"
+require_relative "rules/ref_shape_rule"
+require_relative "rules/locality_completeness_rule"
+require_relative "rules/domain_ref_rule"
+require_relative "rules/uuid_format_rule"
+require_relative "rules/localization_consistency_rule"
+require_relative "rules/related_concept_target_rule"
+require_relative "rules/domain_target_rule"
+require_relative "rules/source_urn_format_rule"
+require_relative "rules/model_validity_rule"

data/lib/glossarist/validation/validation_issue.rb

@@ -2,16 +2,19 @@
 
 module Glossarist
   module Validation
-    class ValidationIssue
-      attr_reader :severity, :code, :message, :location, :suggestion
+    class ValidationIssue < Lutaml::Model::Serializable
+      attribute :severity, :string
+      attribute :code, :string
+      attribute :message, :string
+      attribute :location, :string
+      attribute :suggestion, :string
 
-      def initialize(severity:, message:, code: nil, location: nil,
-suggestion: nil)
-        @severity = severity
-        @code = code
-        @message = message
-        @location = location
-        @suggestion = suggestion
+      key_value do
+        map :severity, to: :severity
+        map :code, to: :code
+        map :message, to: :message
+        map :location, to: :location
+        map :suggestion, to: :suggestion
       end
 
       def error?
@@ -29,9 +32,9 @@ suggestion: nil)
       def to_s
         parts = ["[#{severity.upcase}]"]
         parts << "[#{code}]" if code
-        parts << (location ? "#{location}: " : "")
+        parts << "#{location}: " if location
         parts << message
-        parts << " (#{suggestion})" if suggestion
+        parts << "(#{suggestion})" if suggestion
         parts.join(" ")
       end
     end

data/lib/glossarist/validation_result.rb

@@ -1,55 +1,45 @@
 # frozen_string_literal: true
 
 module Glossarist
-  class ValidationResult
-    attr_reader :issues
+  class ValidationResult < Lutaml::Model::Serializable
+    attribute :issues, Validation::ValidationIssue, collection: true,
+                                                    initialize_empty: true
 
-    def initialize(errors: [], warnings: [], issues: [])
-      @issues = []
-      errors.each { |e| add_error(e) }
-      warnings.each { |w| add_warning(w) }
-      issues.each { |i| add_issue(i) }
+    key_value do
+      map :issues, to: :issues
     end
 
     def valid?
-      @issues.none?(&:error?)
+      issues.none?(&:error?)
     end
 
     def errors
-      @issues.select(&:error?).map(&:message)
+      issues.select(&:error?).map(&:to_s)
     end
 
     def warnings
-      @issues.select(&:warning?).map(&:message)
+      issues.select(&:warning?).map(&:to_s)
     end
 
     def add_error(message)
-      @issues << Validation::ValidationIssue.new(
+      issues << Validation::ValidationIssue.new(
         severity: "error", message: message,
       )
     end
 
     def add_warning(message)
-      @issues << Validation::ValidationIssue.new(
+      issues << Validation::ValidationIssue.new(
         severity: "warning", message: message,
       )
     end
 
     def add_issue(issue)
-      @issues << issue
+      issues << issue
     end
 
     def merge(other)
-      other.issues.each { |i| @issues << i }
+      other.issues.each { |i| issues << i }
       self
     end
-
-    def to_h
-      {
-        "valid" => valid?,
-        "errors" => errors,
-        "warnings" => warnings,
-      }
-    end
   end
 end

data/lib/glossarist/version.rb

@@ -4,5 +4,5 @@
 #
 
 module Glossarist
-  VERSION = "2.6.6"
+  VERSION = "2.6.7"
 end

data/lib/glossarist.rb

@@ -18,6 +18,7 @@ module Glossarist
   autoload :Collections,              "glossarist/collections"
   autoload :Concept,                  "glossarist/concept"
   autoload :ConceptData,              "glossarist/concept_data"
+  autoload :ConceptRef,               "glossarist/concept_ref"
   autoload :ConceptReference,         "glossarist/concept_reference"
   autoload :ReferenceExtractor,       "glossarist/reference_extractor"
   autoload :ReferenceResolver,        "glossarist/reference_resolver"
@@ -28,6 +29,9 @@ module Glossarist
   autoload :ConceptSource,            "glossarist/concept_source"
   autoload :ConceptValidator,         "glossarist/concept_validator"
   autoload :ConceptCollector, "glossarist/concept_collector"
+  autoload :ConceptComparator, "glossarist/concept_comparator"
+  autoload :ComparisonResult, "glossarist/comparison_result"
+  autoload :ConceptDiff, "glossarist/concept_diff"
   autoload :ConceptDocument,          "glossarist/concept_document"
   autoload :ConceptEnricher,          "glossarist/concept_enricher"
   autoload :Config,                   "glossarist/config"
@@ -64,6 +68,8 @@ module Glossarist
   autoload :RegisterData,             "glossarist/register_data"
   autoload :ValidationResult,         "glossarist/validation_result"
   autoload :V1,                       "glossarist/v1"
+  autoload :V2,                       "glossarist/v2"
+  autoload :V3,                       "glossarist/v3"
 end
 
 require_relative "glossarist/version"
@@ -74,6 +80,9 @@ module Glossarist
   LANG_CODES = %w[eng ara deu fra spa ita jpn kor pol por srp swe zho rus fin
                   dan nld msa nob nno].freeze
 
+  SCHEMA_VERSION = "3"
+  V3_SCHEMA_VERSION = "3"
+
   def self.configure
     config = Glossarist::Config.instance
 

data/memory/project-status.md

@@ -0,0 +1,43 @@
+---
+name: V2/V3 Namespace Architecture
+description: lutaml-model mapping inheritance, model register, V2/V3 namespace design
+type: project
+---
+
+## lutaml-model mapping inheritance
+
+lutaml-model `key_value` mappings ARE inherited by subclasses — a subclass's `key_value` block merges on top of the parent's mappings, it does NOT replace them. A subclass cannot "unmap" a parent mapping by omitting it.
+
+**Why:** Discovered during V2/V3 namespace implementation. V2::ManagedConcept originally tried to define its own `key_value` block without `related`/`schema_version`/`sources`, but the parent ManagedConcept's mappings for those fields were still active.
+
+**How to apply:** For V2/V3 versioning, only V2::ManagedConceptData needs its own `key_value` (to add `related` mapping inside data). V2::ManagedConcept only overrides the `data` attribute to point to V2::ManagedConceptData — it does NOT need its own `key_value`. V2 is only for deserialization; serialization always uses v3 format via inherited base class mappings.
+
+## Model register (lutaml-model GlobalContext)
+
+Follows the plurimath/mml pattern. Each version has a Configuration module with a unique CONTEXT_ID that extends Glossarist::ContextConfiguration. Models are registered via `Configuration.register_model(ClassName, id: :symbol)`. Type resolution uses `Configuration.resolve_model(:symbol)` which delegates to `Lutaml::Model::GlobalContext.resolve_type`.
+
+**Why:** Enables context-based type resolution instead of hardcoded case/when. Each version's registry is isolated — V2::Configuration resolves `:managed_concept` to V2::ManagedConcept, V3::Configuration resolves to V3::ManagedConcept.
+
+**How to apply:** `ConceptDocument.for_version(version)` looks up the version's Configuration from a VERSION_CONFIGURATION hash and calls `resolve_model(:concept_document)`. Adding a new version requires only a new Configuration module and register_model calls.
+
+## V2 → V3 model-driven migration
+
+V2→V3 migration is fully model-driven: V2::ConceptDocument deserializes v2 YAML (data.related → model), then `SchemaMigration.migrate_concept` promotes `data.related` to `concept.related` and sets schema_version to "3". No hash-based transformation needed — `Steps::V2ToV3` was deleted.
+
+## RDF / JSON-LD / Turtle: version-agnostic
+
+RDF view classes (GlossConcept, GlossLocalizedConcept, etc.) are NOT versioned. They operate on the domain model (ManagedConcept), not on YAML serialization format. schema_version is a YAML metadata field with no SKOS/gloss ontology equivalent. ConceptToGlossTransform takes a domain-model ManagedConcept and produces view-model instances — it is format-agnostic.
+
+**Why:** Whether a concept was loaded from v2 or v3 YAML, the RDF output is identical. The domain model normalizes away format differences.
+
+**How to apply:** No RDF model changes needed for v2/v3. If a future v4 changes the domain model semantics (not just serialization), RDF view classes would need updating.
+
+## README documentation (completed 2026-05-20)
+
+The README.adoc now includes a comprehensive "Schema Versioning (v2 / v3)" section covering:
+- V2 vs V3 format differences with YAML examples
+- Namespace architecture diagram
+- Model register (GlobalContext) usage
+- Loading & migration flow diagram
+- Usage examples for v2, v3, migration, and RDF export
+- "Adding a new schema version" guide (Open/Closed Principle)