edoxen 0.7.2 → 0.8.1

data/edoxen.gemspec

@@ -8,25 +8,24 @@ Gem::Specification.new do |spec|
   spec.authors = ["Ribose Inc."]
   spec.email = ["open.source@ribose.com"]
 
-  spec.summary = "Edoxen is a set of information models used for representing resolution and decision information."
+  spec.summary = "Edoxen is a generic information model for meetings, agendas, and decisions."
   spec.description = <<~HEREDOC
-    Edoxen provides a Ruby library for working with resolution models, allowing
-    users to create, manipulate, and serialize resolution data in a structured
-    format. It is built on top of the lutaml-model serialization framework,
-    which provides a flexible and extensible way to define data models and
-    serialize them to YAML or JSON formats.
+    Edoxen provides a Ruby library for working with a generic meeting/decision
+    model, allowing users to create, manipulate, and serialize meeting, agenda,
+    motion, voting, and decision data in a structured format. Built on top of
+    the lutaml-model serialization framework, with profile-based customization
+    (ISO 8601-2 §15) for domain-specific extensions.
   HEREDOC
 
   spec.homepage = "https://github.com/metanorma/edoxen"
   spec.license = "BSD-2-Clause"
-  spec.required_ruby_version = ">= 3.0.0"
+  spec.required_ruby_version = ">= 3.1.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/metanorma/edoxen"
   spec.metadata["changelog_uri"] = "https://github.com/metanorma/edoxen"
+  spec.metadata["rubygems_mfa_required"] = "true"
 
-  # Specify which files should be added to the gem when it is released.
-  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
       (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
@@ -39,5 +38,6 @@ Gem::Specification.new do |spec|
   spec.add_dependency "json_schemer", "~> 2.0"
   spec.add_dependency "lutaml-model", "~> 0.7"
   spec.add_dependency "thor", "~> 1.0"
-  spec.add_dependency "unlocodes", "~> 0.1"
+  spec.add_dependency "unlocodes", "~> 0.3"
+  spec.add_dependency "iata", "~> 0.1"
 end

data/lib/edoxen/action.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 module Edoxen
-  # Verb + one effective date + human-readable message. Used inside a
-  # Localization to express the multilingual part of an action.
+  # Verb + one effective date + per-field Localized message. Each
+  # `Action` belongs to a `Decision`; the message field carries one
+  # `LocalizedString` per ISO 24229 spelling.
   class Action < Lutaml::Model::Serializable
     attribute :type, :string, values: Enums::ACTION_TYPE
-    attribute :date_effective, ResolutionDate
-    attribute :message, :string
+    attribute :date_effective, DecisionDate
+    attribute :message, LocalizedString, collection: true
   end
 end

data/lib/edoxen/agenda.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module Edoxen
-  # The business-order document of a Meeting. Distinct from the
-  # timetable (Schedule) — the Agenda orders topics; the Schedule
-  # orders time slots.
+  # The business-order document of a Meeting. Distinct from the timetable
+  # (MeetingComponent) — the Agenda orders topics; components order time
+  # slots. Opening/closing sessions are components, not agenda entries.
   #
   # An Agenda may be versioned independently of the Meeting: a draft
   # agenda circulates weeks before; a final agenda at meeting time;
@@ -14,11 +14,8 @@ module Edoxen
     attribute :status, :string, values: Enums::AGENDA_STATUS
     attribute :source_doc, :string
     attribute :items, AgendaItem, collection: true
-    attribute :opening_session, ScheduleItem
-    attribute :closing_session, ScheduleItem
+    attribute :extensions, MeetingExtension, collection: true
 
-    # Find an agenda item by its label (e.g., "5.2"). Returns nil
-    # when no item matches.
     def find_item(label)
       items&.find { |item| item.label == label.to_s }
     end

data/lib/edoxen/agenda_item.rb

@@ -3,15 +3,22 @@
 module Edoxen
   # One entry on an Agenda. `label` is the visible identifier (e.g.,
   # "5.2"); `kind` discriminates numbered/unnumbered/header/opening/
-  # closing; `outcome` records what happened; `resolution_ref`
-  # optionally links to the URN of the resolution this item produced.
+  # closing/aob; `outcome` records what happened; `decision_ref`
+  # optionally links to the URN of the decision this item produced.
+  #
+  # Topics (0..*) are the subject(s) of discussion at this agenda item.
+  # AOB (Any Other Business) items have 0 topics until raised during
+  # the meeting.
   class AgendaItem < Lutaml::Model::Serializable
     attribute :label, :string
     attribute :kind, :string, values: Enums::AGENDA_ITEM_KIND
-    attribute :title, :string
-    attribute :description, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :description, LocalizedString, collection: true
     attribute :references, Reference, collection: true
     attribute :outcome, :string, values: Enums::AGENDA_ITEM_OUTCOME
-    attribute :resolution_ref, :string
+    attribute :decision_ref, :string
+    attribute :topics, Topic, collection: true
+    attribute :components, :string, collection: true
+    attribute :extensions, MeetingExtension, collection: true
   end
 end

data/lib/edoxen/approval.rb

@@ -6,7 +6,7 @@ module Edoxen
   class Approval < Lutaml::Model::Serializable
     attribute :type, :string, values: Enums::APPROVAL_TYPE
     attribute :degree, :string, values: Enums::APPROVAL_DEGREE
-    attribute :date, ResolutionDate
-    attribute :message, :string
+    attribute :date, DecisionDate
+    attribute :message, LocalizedString, collection: true
   end
 end

data/lib/edoxen/attendance.rb

@@ -1,23 +1,29 @@
 # frozen_string_literal: true
 
 module Edoxen
-  # One attendance record per person. Mirrors the ParticipationStatus
-  # enum from edoxen-model/models/participation_status.lutaml.
-  # Optional `affiliation` and `notes` fields let callers annotate
-  # proxy representatives and any meeting-specific details.
+  # One attendance record per person. Combines:
+  #   - status: ParticipationStatus (in-meeting observation: present/absent/
+  #             apologies/observer/excused)
+  #   - role: AttendanceRole (structural importance: chair/required/optional/
+  #           non_participant — from iCalendar ROLE, plain English)
+  #   - response: AttendanceResponse (RSVP state: pending/confirmed/declined/
+  #               tentative/delegated — from iCalendar PARTSTAT, plain English)
   class Attendance < Lutaml::Model::Serializable
     attribute :person, Person
     attribute :status, :string, values: Enums::PARTICIPATION_STATUS
+    attribute :role, :string, values: Enums::ATTENDANCE_ROLE
+    attribute :response, :string, values: Enums::ATTENDANCE_RESPONSE
     attribute :affiliation, :string
     attribute :proxy_for, Person
     attribute :notes, :string
+    attribute :extensions, MeetingExtension, collection: true
 
-    key_value do
-      map "person", to: :person
-      map "status", to: :status
-      map "affiliation", to: :affiliation
-      map "proxy_for", to: :proxy_for
-      map "notes", to: :notes
+    def present?
+      status == "present"
+    end
+
+    def declined?
+      response == "declined"
     end
   end
 end

data/lib/edoxen/body_vocabulary_entry.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # BodyVocabularyEntry — one entry in a per-dataset body_vocabulary
+  # list (1.0, 1.0 design review).
+  #
+  # Maps a free-form `body_type` (e.g. "CIML Meeting", "Plenary") to a
+  # short canonical value (e.g. "plenary"). Bodies declare their
+  # vocabulary on the collection metadata; consumers look up the
+  # canonical_type via the parent collection's vocabulary.
+  #
+  # SSOT: the body_vocabulary list on collection metadata is the single
+  # source of truth for body_type → canonical_type resolution within
+  # that dataset.
+  #
+  # Permissive: when no vocabulary entry matches a body_type, the gem
+  # returns the body_type string itself (with a warning at debug
+  # level). Strict mode is a v3.x concern.
+  class BodyVocabularyEntry < Lutaml::Model::Serializable
+    attribute :body_type, :string
+    attribute :canonical_type, :string
+    attribute :definition, :string
+  end
+end

data/lib/edoxen/body_vocabulary_host.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Mixed into metadata classes that carry a per-dataset
+  # `body_vocabulary[]` collection (1.0, 1.0 design review). Provides
+  # the attribute declaration and the `canonical_type_for` lookup in
+  # one place so DecisionMetadata and MeetingCollectionMetadata share
+  # a single implementation.
+  #
+  # Permissive by design: when no vocabulary entry matches a
+  # body_type, the body_type string itself is returned (with no
+  # warning). Strict mode is a v3.x concern.
+  #
+  # == Why the `included` hook declares the attribute
+  #
+  # The block-form `included` callback calls
+  # `base.attribute :body_vocabulary, ...` on the includer so both
+  # consumers (DecisionMetadata, MeetingCollectionMetadata) pick up
+  # the attribute and the lookup method from one source. This is a
+  # deliberate DRY trade-off: the alternative — declaring the
+  # attribute in each metadata class — leaves the lookup method
+  # without its required backing field on any class that forgets the
+  # declaration. The hook makes the field and the method inseparable.
+  module BodyVocabularyHost
+    def self.included(base)
+      base.attribute :body_vocabulary, BodyVocabularyEntry, collection: true
+    end
+
+    # Resolve a body_type to its canonical_type via this collection's
+    # vocabulary. Returns the body_type unchanged when nil/empty or
+    # when no matching entry exists.
+    def canonical_type_for(body_type)
+      return body_type if body_type.nil? || body_type.to_s.empty?
+      return body_type unless body_vocabulary
+
+      entry = body_vocabulary.find { |e| e.body_type == body_type }
+      entry ? entry.canonical_type : body_type
+    end
+  end
+end

data/lib/edoxen/cli.rb

@@ -5,17 +5,60 @@ require "fileutils"
 
 module Edoxen
   class Cli < Thor
+    # Each top-level YAML document is either a Decision collection or a
+    # Meeting (single or collection). The two share the same batch
+    # scaffold (expand → header → loop → tally → exit) but differ in
+    # which schema validates them and which model class loads them.
+    #
+    # A Profile bundles those two facts so the Thor command methods are
+    # one-line delegations. Adding a third document kind (e.g. an
+    # attendance-only file) is one Profile constant + one desc block —
+    # no new scaffolding.
+    Profile = Struct.new(:name, :schema_file, :loader) do
+      def schema_path
+        File.expand_path("../../schema/#{schema_file}", __dir__)
+      end
+
+      # Returns the loaded model object, raising StandardError on failure.
+      # Single-vs-collection detection is up to the loader (Meeting side
+      # sniffs the top-level key; Decision side always returns a
+      # DecisionCollection).
+      def load(content)
+        loader.call(content)
+      end
+    end
+
+    PROFILES = {
+      decisions: Profile.new(
+        "decisions", "edoxen.yaml",
+        lambda do |content|
+          data = YAML.safe_load(content, permitted_classes: [Date, Time])
+          case Batch.decision_kind(data)
+          when :contacts then ContactCollection.from_yaml(content)
+          when :venues   then VenueCollection.from_yaml(content)
+          else                DecisionCollection.from_yaml(content)
+          end
+        end
+      ),
+      meetings: Profile.new(
+        "meetings", "meeting.yaml",
+        lambda do |content|
+          data = YAML.safe_load(content, permitted_classes: [Date, Time])
+          case Batch.meetings_kind(data)
+          when :collection then MeetingCollection.from_yaml(content)
+          when :series     then MeetingSeries.from_yaml(content)
+          else                  Meeting.from_yaml(content)
+          end
+        end
+      )
+    }.freeze
+
     # Deep module behind the per-command interface. Owns the
     # expand/sort/empty/header/loop/tally/summary/exit scaffold so
-    # `validate` and `normalize` collapse to per-file blocks.
-    #
-    # Commands call `Batch.run(self, pattern, header:)` and yield a block
-    # that returns `Result.ok(message)` or `Result.bad(errors)`. The
-    # batch runner prints progress, tallies, prints the summary, and
-    # exits with the right code.
-    #
-    # In-process; no adapter. The seam is the call site in each
-    # command method — internal to the CLI.
+    # `validate` and `normalize` collapse to one-line delegations.
+    # Also owns the per-profile shape sniffers that pick the correct
+    # model class for each YAML file (one of N shapes accepted by the
+    # canonical `oneOf` roots).
     module Batch
       # Per-file outcome. `ok` carries an optional message appended to
       # the success indicator (e.g. "NORMALIZED → /out/path"). `bad`
@@ -32,11 +75,38 @@ module Edoxen
 
       module_function
 
-      # Run a batch over every YAML file matching `pattern`.
+      # Discriminate the three top-level shapes the canonical
+      # `schema/edoxen.yaml` accepts via `oneOf`:
       #
-      # Yields each file path to the caller's block. Block must return
-      # a Batch::Result. The batch runner handles progress output,
-      # tallies, summary, and the exit code.
+      #   * :contacts   — `{ contacts: [...] }` (ContactCollection registry).
+      #   * :venues     — `{ venues: [...] }`   (VenueCollection registry).
+      #   * :decisions  — anything else (DecisionCollection, the default).
+      def decision_kind(data)
+        return :decisions unless data.is_a?(Hash)
+
+        return :contacts if data["contacts"].is_a?(Array)
+        return :venues if data["venues"].is_a?(Array)
+
+        :decisions
+      end
+
+      # Discriminate the three top-level shapes the canonical
+      # `schema/meeting.yaml` accepts via `oneOf`:
+      #
+      #   * :collection — `{ meetings: [...] }`
+      #   * :series     — `{ identifier: [...], meeting_refs: [...] }`
+      #                   (or any hash with `identifier` + `recurrence`)
+      #   * :meeting    — anything else (single Meeting).
+      def meetings_kind(data)
+        return :meeting unless data.is_a?(Hash)
+
+        return :collection if data["meetings"].is_a?(Array)
+        return :series if data["identifier"].is_a?(Array) &&
+                          (data.key?("meeting_refs") || data.key?("recurrence"))
+
+        :meeting
+      end
+
       def run(cli, pattern, header:, summary_extra: [])
         files = expand(pattern)
         if files.empty?
@@ -84,62 +154,32 @@ module Edoxen
 
     package_name "edoxen"
 
+    # --- Decision-side commands -----------------------------------------
+
     desc "validate YAML_FILE_PATTERN",
-         "Validate one or more Edoxen YAML files against the schema and the model."
+         "Validate Decision YAML file(s) against schema/edoxen.yaml and the model."
 
     def validate(pattern)
-      validator = SchemaValidator.new
-      Batch.run(self, pattern, header: "🔍 Validating") do |file|
-        schema_errors = validator.validate_file(file)
-        model_errors = collect_model_errors(file)
-        if schema_errors.empty? && model_errors.empty?
-          Batch::Result.ok("VALID")
-        else
-          errors = (schema_errors + model_errors).map(&:to_clickable_format)
-          Batch::Result.bad(errors)
-        end
-      end
+      run_validate(PROFILES.fetch(:decisions), pattern)
     end
 
     desc "normalize YAML_FILE_PATTERN",
-         "Round-trip YAML file(s) through the Edoxen model (--output DIR or --inplace)."
+         "Round-trip Decision YAML file(s) through the model (--output DIR or --inplace)."
 
     option :output, type: :string, desc: "Output directory for normalized files"
     option :inplace, type: :boolean, desc: "Modify files in place (no backup)"
 
     def normalize(pattern)
-      unless valid_normalize_options?
-        say normalize_options_error, :red
-        exit 1
-      end
-
-      summary_extra = [
-        ["  Output directory", options[:output]],
-        ["  Mode", options[:inplace] ? "in place" : "--output"]
-      ].compact
-
-      Batch.run(self, pattern, header: "🔄 Normalizing", summary_extra: summary_extra) do |file|
-        Batch::Result.ok(normalize_file(file))
-      rescue StandardError => e
-        Batch::Result.bad(["#{file}:1:1: #{e.message}"])
-      end
+      run_normalize(PROFILES.fetch(:decisions), pattern)
     end
 
+    # --- Meeting-side commands ------------------------------------------
+
     desc "validate-meetings YAML_FILE_PATTERN",
          "Validate Meeting/Agenda YAML file(s) against schema/meeting.yaml."
 
     def validate_meetings(pattern)
-      validator = SchemaValidator.new(meeting_schema_path)
-      Batch.run(self, pattern, header: "🔍 Validating meetings") do |file|
-        schema_errors = validator.validate_file(file)
-        model_errors = collect_meeting_model_errors(file)
-        if schema_errors.empty? && model_errors.empty?
-          Batch::Result.ok("VALID")
-        else
-          errors = (schema_errors + model_errors).map(&:to_clickable_format)
-          Batch::Result.bad(errors)
-        end
-      end
+      run_validate(PROFILES.fetch(:meetings), pattern)
     end
 
     desc "normalize-meetings YAML_FILE_PATTERN",
@@ -149,24 +189,34 @@ module Edoxen
     option :inplace, type: :boolean, desc: "Modify files in place (no backup)"
 
     def normalize_meetings(pattern)
-      unless valid_normalize_options?
-        say normalize_options_error, :red
+      run_normalize(PROFILES.fetch(:meetings), pattern)
+    end
+
+    # --- Cross-document link checking ----------------------------------
+
+    desc "check-links DIRECTORY",
+         "Scan a directory of Meeting/DecisionCollection YAML and report " \
+         "any cross-document URN that does not resolve."
+
+    def check_links(directory)
+      unless File.directory?(directory)
+        say "Error: #{directory} is not a directory", :red
         exit 1
       end
 
-      summary_extra = [
-        ["  Output directory", options[:output]],
-        ["  Mode", options[:inplace] ? "in place" : "--output"]
-      ].compact
+      say "🔗 Checking cross-document URN links in #{directory}...", :blue
+      errors = Edoxen::LinkChecker.check(directory)
+      return say("✅ No broken or duplicate links found", :green) if errors.empty?
 
-      Batch.run(self, pattern, header: "🔄 Normalizing meetings", summary_extra: summary_extra) do |file|
-        Batch::Result.ok(normalize_meeting_file(file))
-      rescue StandardError => e
-        Batch::Result.bad(["#{file}:1:1: #{e.message}"])
-      end
+      say "❌ Found #{errors.size} link error(s):", :red
+      errors.each { |e| say "  #{e.message}", :red }
+      exit 1
     end
 
+    # --- Reference-data lookups -----------------------------------------
+
     desc "unlocode CODE", "Resolve a UN/LOCODE via the canonical registry."
+
     def unlocode(code)
       entry = Edoxen::ReferenceData.find_unlocode(code)
       if entry.nil?
@@ -180,18 +230,59 @@ module Edoxen
       say "  Subdiv:    #{entry.subdivision}" if entry.subdivision
       coords = entry.coordinates
       say "  Coords:    #{coords}" if coords
-      funcs = entry.functions.compact.map(&:to_s)
+      funcs = entry.function_codes.compact
       say "  Functions: #{funcs.join(", ")}" unless funcs.empty?
     end
 
+    desc "iata CODE", "Resolve an IATA airport/city code via the canonical registry."
+
+    def iata(code)
+      entry = Edoxen::ReferenceData.find_iata(code)
+      if entry.nil?
+        say "No entry for #{code.upcase} in the IATA registry.", :red
+        exit 1
+      end
+
+      say "IATA:       #{entry.code}", :blue
+      say "  Name:      #{entry.name}"
+      say "  Country:   #{entry.country_iso2}"
+    end
+
     private
 
-    def meeting_schema_path
-      File.expand_path("../../schema/meeting.yaml", __dir__)
+    def run_validate(profile, pattern)
+      validator = SchemaValidator.new(profile.schema_path)
+      Batch.run(self, pattern, header: "🔍 Validating #{profile.name}") do |file|
+        schema_errors = validator.validate_file(file)
+        model_errors = collect_model_errors(profile, file)
+        if schema_errors.empty? && model_errors.empty?
+          Batch::Result.ok("VALID")
+        else
+          Batch::Result.bad((schema_errors + model_errors).map(&:to_clickable_format))
+        end
+      end
     end
 
-    def collect_model_errors(file)
-      ResolutionCollection.from_yaml(File.read(file))
+    def run_normalize(profile, pattern)
+      unless valid_normalize_options?
+        say normalize_options_error, :red
+        exit 1
+      end
+
+      summary_extra = [
+        ["  Output directory", options[:output]],
+        ["  Mode", options[:inplace] ? "in place" : "--output"]
+      ].compact
+
+      Batch.run(self, pattern, header: "🔄 Normalizing #{profile.name}", summary_extra: summary_extra) do |file|
+        Batch::Result.ok(normalize_file(profile, file))
+      rescue StandardError => e
+        Batch::Result.bad(["#{file}:1:1: #{e.message}"])
+      end
+    end
+
+    def collect_model_errors(profile, file)
+      profile.load(File.read(file))
       []
     rescue StandardError => e
       [Edoxen::ValidationError.new(
@@ -201,27 +292,26 @@ module Edoxen
       )]
     end
 
-    def collect_meeting_model_errors(file)
-      load_meeting_document(file)
-      []
+    def normalize_file(profile, file)
+      original = File.read(file)
+      schema_comment = extract_yaml_language_server_comment(original)
+      normalized = profile.load(original).to_yaml
+      write_normalized(file, normalized, schema_comment)
     rescue StandardError => e
-      [Edoxen::ValidationError.new(
-        file: file, line: 1, column: 1,
-        message_text: "Meeting model parsing failed: #{e.message}",
-        source: Edoxen::ValidationError::SOURCE_MODEL
-      )]
+      raise "#{file}: #{e.message}"
     end
 
-    # A meeting YAML may be either a single Meeting or a
-    # MeetingCollection. Detect by the presence of a top-level
-    # `meetings:` key and parse accordingly. Returns whichever
-    # model object was successfully constructed.
-    def load_meeting_document(file)
-      data = YAML.safe_load(File.read(file), permitted_classes: [Date, Time])
-      if data.is_a?(Hash) && data.key?("meetings")
-        MeetingCollection.from_yaml(File.read(file))
+    def write_normalized(file, normalized, schema_comment)
+      normalized = "#{schema_comment}\n#{normalized}" if schema_comment
+
+      if options[:inplace]
+        File.write(file, normalized)
+        "NORMALIZED"
       else
-        Meeting.from_yaml(File.read(file))
+        out = File.join(options[:output], File.basename(file))
+        FileUtils.mkdir_p(File.dirname(out))
+        File.write(out, normalized)
+        "NORMALIZED → #{out}"
       end
     end
 
@@ -244,35 +334,5 @@ module Edoxen
         "Error: Must specify either --output or --inplace option"
       end
     end
-
-    # Writes the normalized YAML either to the original file (--inplace)
-    # or under the --output directory. Returns a one-line status message
-    # for the batch runner to print after the ✅.
-    def normalize_file(file)
-      original = File.read(file)
-      yaml_language_server_comment = extract_yaml_language_server_comment(original)
-      normalized = ResolutionCollection.from_yaml(original).to_yaml
-      write_normalized(file, normalized, yaml_language_server_comment)
-    end
-
-    def normalize_meeting_file(file)
-      yaml_language_server_comment = extract_yaml_language_server_comment(File.read(file))
-      normalized = load_meeting_document(file).to_yaml
-      write_normalized(file, normalized, yaml_language_server_comment)
-    end
-
-    def write_normalized(file, normalized, yaml_language_server_comment)
-      normalized = "#{yaml_language_server_comment}\n#{normalized}" if yaml_language_server_comment
-
-      if options[:inplace]
-        File.write(file, normalized)
-        "NORMALIZED"
-      else
-        out = File.join(options[:output], File.basename(file))
-        FileUtils.mkdir_p(File.dirname(out))
-        File.write(out, normalized)
-        "NORMALIZED → #{out}"
-      end
-    end
   end
 end

data/lib/edoxen/consideration.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 module Edoxen
-  # Basis for a resolution: a verb (having, noting, considering, ...) plus
-  # one effective date and the elaborated reasoning.
+  # Basis for a Decision: a verb (having, noting, considering, ...) plus
+  # one effective date and the per-field Localized reasoning. Each
+  # `Consideration` belongs to a `Decision`; the message field carries
+  # one `LocalizedString` per ISO 24229 spelling.
   class Consideration < Lutaml::Model::Serializable
     attribute :type, :string, values: Enums::CONSIDERATION_TYPE
-    attribute :date_effective, ResolutionDate
-    attribute :message, :string
+    attribute :date_effective, DecisionDate
+    attribute :message, LocalizedString, collection: true
   end
 end

data/lib/edoxen/contact.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # VCARD-like abstract contact. Generalises Person for cases where the
+  # contact may be a person, an organisation, a department, a role
+  # ("Secretariat"), or any other entity with a name and one or more
+  # communication channels.
+  #
+  # 1.0 (per-field localization, ISO 24229):
+  #   - All translatable fields are Localized<String/Name>[0..*]
+  #     (one entry per spelling/conversion system code).
+  #   - Added: `urn` for registry storage; `ref` for reference-by-URN.
+  #
+  # Reference vs inline: when `ref` is set, treat this Contact as a
+  # reference (other fields ignored). When `ref` is unset, the Contact
+  # is inline (full data). Both patterns are valid on every field that
+  # accepts a Contact.
+  class Contact < Lutaml::Model::Serializable
+    attribute :ref, :string
+    attribute :urn, :string
+    attribute :name, LocalizedName, collection: true
+    attribute :kind, :string
+    attribute :role, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :affiliation, LocalizedString, collection: true
+    attribute :contact_methods, ContactMethod, collection: true
+    attribute :identifiers, ContactIdentifier, collection: true
+    attribute :address, LocalizedString, collection: true
+    attribute :extensions, MeetingExtension, collection: true
+
+    def reference?
+      !ref.nil? && !ref.to_s.empty?
+    end
+  end
+end