edoxen 0.7.2 → 0.8.2

data/lib/edoxen/motion.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Motion — a procedural act that brings a Decision. "I move that..."
+  # Distinct from a Decision (formal outcome) and from a TopicDocument
+  # (written text). A Motion does NOT require any document.
+  #
+  # State machine (MotionStatus):
+  #   introduced → seconded → debating → question_put → voting
+  #                                                ├── carried → resulting_decision set
+  #                                                ├── negatived
+  #                                                ├── withdrawn
+  #                                                └── lapsed
+  class Motion < Lutaml::Model::Serializable
+    attribute :identifier, :string
+    attribute :urn, :string
+    attribute :text, LocalizedString, collection: true
+    attribute :mover, Person
+    attribute :seconders, Person, collection: true
+    attribute :status, :string, values: Enums::MOTION_STATUS
+    attribute :introduced_at, :date_time
+    attribute :proposed_decision, :string
+    attribute :resulting_decision, :string
+    # Pilot EntityRef field (1.0, 1.0 design review). Parallel to
+    # `resulting_decision` (String). Prefer the typed form in new code;
+    # the bare String form is removed in 1.0.
+    attribute :resulting_decision_ref, EntityRef
+    attribute :votings, :string, collection: true
+    attribute :extensions, MeetingExtension, collection: true
+
+    def carried?
+      status == "carried"
+    end
+
+    def pending?
+      status && !Enums::MOTION_TERMINAL.include?(status)
+    end
+
+    # --- 1.0 derivation accessor (1.0 design review) --------------------
+    # Storage side: Voting.on_motion (SSOT for the Motion→Voting
+    # relationship). This computed method returns the Voting instances
+    # in `meeting` whose `on_motion` points at this Motion's URN.
+    # The stored `votings[]` field remains on the wire for back-compat
+    # through v2.x; 1.0 removes it and this becomes the only path.
+    def votings_in(meeting:)
+      return [] unless meeting && urn
+
+      meeting.votings.select { |voting| voting.on_motion == urn }
+    end
+  end
+end

data/lib/edoxen/name.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Structured personal/organisational name. VCARD conventions
+  # (RFC 6350): separate structured components (N) from a pre-formatted
+  # display string (FN). Either or both may be populated.
+  #
+  # `formatted` is the display string when callers have it pre-built;
+  # the structured fields (`family`, `given`, `additional`, `prefix`,
+  # `suffix`) let adopters store parsed components for sorting, indexing,
+  # or locale-aware rendering.
+  class Name < Lutaml::Model::Serializable
+    attribute :formatted, :string
+    attribute :family, :string
+    attribute :given, :string
+    attribute :additional, :string
+    attribute :prefix, :string
+    attribute :suffix, :string
+    attribute :extensions, MeetingExtension, collection: true
+
+    # Convenience: returns `formatted` if present, else builds one from
+    # the structured components. Useful for callers that always want a
+    # display string regardless of how the name was authored.
+    def display
+      formatted || [prefix, given, additional, family, suffix]
+        .reject { |s| s.to_s.empty? }.join(" ")
+    end
+  end
+end

data/lib/edoxen/officer.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Officer — a person holding a structural role in a Meeting.
+  # Replaces legacy Meeting#chair and Meeting#secretary direct shortcuts.
+  # One list, role discriminates. Open for adopter extension via `other`.
+  class Officer < Lutaml::Model::Serializable
+    attribute :role, :string, values: Enums::OFFICER_ROLE
+    attribute :person, Person
+    attribute :term_start, :date
+    attribute :term_end, :date
+    attribute :extensions, MeetingExtension, collection: true
+
+    def current?(date = Date.today)
+      (term_start.nil? || date >= term_start) &&
+        (term_end.nil? || date <= term_end)
+    end
+  end
+end

data/lib/edoxen/officers_host.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Mixed into entities that carry an `officers` collection. Provides
+  # `officers_with_role(role)` and the `chair` accessor so Meeting and
+  # MeetingComponent share a single implementation.
+  #
+  # The including class must declare an `officers` attribute whose
+  # entries expose `role` and `person`.
+  module OfficersHost
+    def officers_with_role(role)
+      (officers || []).select { |o| o.role == role.to_s }
+    end
+
+    def chair
+      officers_with_role("chair").first&.person
+    end
+  end
+end

data/lib/edoxen/person.rb

@@ -1,14 +1,10 @@
 # frozen_string_literal: true
 
 module Edoxen
-  # Identity + role + affiliation + contact. Used for meeting officers
-  # (chair, secretary, local contact) and host-ref contacts.
-  class Person < Lutaml::Model::Serializable
-    attribute :name, :string
-    attribute :role, :string
-    attribute :affiliation, :string
-    attribute :email, :string
-    attribute :phone, :string
-    attribute :orcid, :string
+  # A Contact that is specifically an individual human. Inherits all
+  # Contact fields. The old `email`, `phone`, and `orcid` fields are
+  # replaced by entries in `contact_methods` (kind=email / kind=phone)
+  # and `identifiers` (kind=orcid).
+  class Person < Contact
   end
 end

data/lib/edoxen/physical_venue.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # PhysicalVenue — type marker for a Venue with kind == "physical".
+  #
+  # The wire format is flat on Venue (all fields live there). This
+  # subclass exists for type-checking and to host physical-only helpers
+  # so callers can ask `venue.is_a?(PhysicalVenue)` and validators
+  # can dispatch by type.
+  class PhysicalVenue < Venue
+    def initialize(attributes = {})
+      super(attributes.merge(kind: "physical"))
+    end
+  end
+end

data/lib/edoxen/recurrence.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Recurrence — structured representation of ISO 8601-2 §13 recurring
+  # time intervals. QUERYABLE (each BYxxx part is its own attribute).
+  #
+  # Round-trip to/from ISO 8601-2 wire string is handled by adapters
+  # in ReferenceData (NOT hand-rolled to_h — declared via lutaml-model
+  # mapping).
+  class Recurrence < Lutaml::Model::Serializable
+    attribute :freq, :string, values: Enums::RECURRENCE_FREQ
+    attribute :interval, :integer, default: 1
+    attribute :count, :integer
+    attribute :until, :date_time
+    attribute :by_day, RecurrenceByDay, collection: true
+    attribute :by_month_day, :integer, collection: true
+    attribute :by_month, :integer, collection: true
+    attribute :by_week_no, :integer, collection: true
+    attribute :by_year_day, :integer, collection: true
+    attribute :by_hour, :integer, collection: true
+    attribute :by_minute, :integer, collection: true
+    attribute :by_second, :integer, collection: true
+    attribute :by_set_pos, :integer, collection: true
+    attribute :week_start, :string, default: "MO"
+    attribute :extensions, MeetingExtension, collection: true
+  end
+end

data/lib/edoxen/recurrence_by_day.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # RecurrenceByDay — a BYDAY part of an ISO 8601-2 §13 recurrence.
+  # `ordinal` is null for "every", +1 for "first", -1 for "last", etc.
+  class RecurrenceByDay < Lutaml::Model::Serializable
+    attribute :ordinal, :integer
+    attribute :weekday, :string
+  end
+end

data/lib/edoxen/reference.rb

@@ -8,6 +8,6 @@ module Edoxen
   class Reference < Lutaml::Model::Serializable
     attribute :ref, :string
     attribute :kind, :string
-    attribute :title, :string
+    attribute :title, LocalizedString, collection: true
   end
 end

data/lib/edoxen/reference_data.rb

@@ -3,56 +3,37 @@
 module Edoxen
   # Built-in reference data for ISO codes used across the Edoxen model:
   # ISO 3166-1 alpha-2 country codes, ISO 639-3 language codes, ISO
-  # 15924 script codes, and UN/LOCODEs.
+  # 15924 script codes, UN/LOCODEs, and IATA airport codes.
   #
-  # UN/LOCODE lookups delegate to the `unlocode` gem (the canonical
-  # Ruby registry of the UNECE UN/LOCODE dataset). The frozen
-  # ReferenceData::UNLOCODES list stays as a curated offline subset
-  # — used by specs and consumers that don't want to load the full
-  # ~100k-entry registry.
+  # UN/LOCODE lookups delegate to the `unlocodes` gem (the canonical
+  # Ruby registry of the UNECE UN/LOCODE dataset).
+  # IATA lookups delegate to the `iata` gem (the canonical Ruby registry
+  # of the IATA airport code list, sourced from Wikidata).
   #
   # Reference data sources:
   # * https://www.iso.org/iso-3166-country-codes.html
   # * https://iso639-3.sil.org/
   # * https://unicode.org/iso15924/
   # * https://unece.org/trade/cefact/unlocode-code-list-country-and-territory
-  #
-  # UN/LOCODE format: 2-letter ISO 3166-1 country code + 3-character
-  # location alphanumeric (e.g., FRPAR = Paris, France; HKHKG = Hong
-  # Kong; THCNM = Chiang Mai). UN-maintained, supersedes the
-  # airport-centric IATA city codes edoxen previously used.
+  # * https://www.wikidata.org/wiki/Property:P238 (IATA airport code)
   module ReferenceData
-    # Hard require the unlocode gem. It's a declared runtime dep, so a
-    # clean install of edoxen brings it in. The bundled dataset ships
-    # 4 sample entries; full coverage requires `rake unlocodes:fetch`
-    # from the unlocode gem.
     require "unlocodes"
+    require "iata"
 
-    # ISO 3166-1 alpha-2 — countries ISO/TC 154 / OIML / BIPM operate in.
-    # Two-letter uppercase.
     COUNTRY_CODES = %w[
       AE AF AR AT AU BE BG BR BY CA CH CL CN CO CY CZ DE DK EE ES FI FR
       GB GR HK HR HU ID IE IL IN IS IT JP KE KR LK LT LU LV MT MX MY NL NO PH
       NZ PL PT RO RS RU SA SE SG SI SK TH TN TR TW UA US VN ZA
     ].freeze
 
-    # ISO 639-3 — languages actually used in the edoxen fixtures
-    # (eng + fra in OIML, plus the ISO official languages).
-    # Three-letter lowercase.
     LANGUAGE_CODES = %w[
       ara chi deu eng fra jpn rus spa zho
     ].freeze
 
-    # ISO 15924 — scripts. Latn + Cyrl + Hant + Hans cover every script
-    # ISO and OIML resolutions are written in.
     SCRIPT_CODES = %w[
       Arab Cyrl Hans Hant Hang Hebr Jpan Kore Latn
     ].freeze
 
-    # Curated offline subset of UN/LOCODEs — the cities ISO/TC 154 and
-    # OIML actually meet in plus the major transit hubs. Used by specs
-    # and consumers that don't want to load the full registry. For
-    # arbitrary lookups, use {find_unlocode}.
     UNLOCODES = %w[
       AUMEL ATVIE BEBRU BGSOF BRBSB CHGVA CNCAN CNHKG CNSHA CNXSZ COCTG
       CYLCA CZPRG DEBER DEHAM DEFRA DKCPH ESMAD FIHEL FRARC FRLYS FRMRS
@@ -62,34 +43,43 @@ module Edoxen
       UAIEV USMIA USNYC USORL VNSGN ZACPT
     ].freeze
 
-    # @deprecated Use {UNLOCODES}. Retained for one release to ease
-    # migration; will be removed in the next minor.
-    CITY_CODES = UNLOCODES
+    # Memoise the registries so we don't re-parse the bundled datasets on
+    # every lookup. Each gem's Registry is immutable after construction.
+    @unlocodes_registry = nil
+    @iata_registry = nil
 
     class << self
-      # Look up a UN/LOCODE entry via the canonical `unlocode` gem.
-      # Returns an `Unlocodes::Entry` (with `#name`, `#country`,
-      # `#coordinates`, `#iata`, `#functions`, etc.) or nil when the
-      # code is not in the registry.
-      #
-      # Requires the full UN/LOCODE dataset to be loaded. The gem
-      # ships a 4-entry sample by default; run `rake unlocodes:fetch`
-      # from the unlocode gem to populate the full ~100k-entry
-      # registry.
-      #
+      # @return [Unlocodes::Registry]
+      def unlocodes_registry
+        @unlocodes_registry ||= Unlocodes::Registry.load_default
+      end
+
+      # @return [Iata::Registry]
+      def iata_registry
+        @iata_registry ||= Iata::Registry.load_default
+      end
+
+      # Look up a UN/LOCODE entry via the canonical `unlocodes` gem.
       # @param code [String, #to_s] 5-character UN/LOCODE
       # @return [Unlocodes::Entry, nil]
       def find_unlocode(code)
-        Unlocodes.find(code.to_s.upcase)
+        unlocodes_registry.find(code.to_s.upcase)
       end
 
-      # True when the code resolves to a real UN/LOCODE entry via the
-      # canonical registry. Use this when validating user-supplied
-      # city codes; use the schema's pattern check for cheap shape
-      # validation.
       def unlocode_exists?(code)
         !find_unlocode(code).nil?
       end
+
+      # Look up an IATA airport/city code via the canonical `iata` gem.
+      # @param code [String, #to_s] 3-character IATA code
+      # @return [Iata::Entry, nil]
+      def find_iata(code)
+        iata_registry.find(code.to_s.upcase)
+      end
+
+      def iata_exists?(code)
+        !find_iata(code).nil?
+      end
     end
   end
 end

data/lib/edoxen/schema_validator.rb

@@ -9,7 +9,7 @@ module Edoxen
   # The SchemaValidator is intentionally small and only owns one concern:
   # JSON-Schema validation with line-accurate error reporting. It does not
   # touch the Ruby model — CLI layers SchemaValidator and
-  # `ResolutionCollection.from_yaml` to catch both schema-level violations
+  # `DecisionCollection.from_yaml` to catch both schema-level violations
   # (additionalProperties, required, enum) and structural issues
   # (numeric/date coercion, missing nested classes) the schema can't express.
   #
@@ -72,7 +72,7 @@ module Edoxen
     end
 
     def load_schemer(path)
-      JSONSchemer.schema(YAML.safe_load(File.read(path), permitted_classes: [Date, Time]))
+      JSONSchemer.schema(YAML.safe_load_file(path, permitted_classes: [Date, Time]))
     end
 
     # Coerce Date/Time instances back to ISO strings before handing the
@@ -81,8 +81,7 @@ module Edoxen
     # here keeps the gem OCP-compliant (no json_schemer plugin/tweak).
     def normalize_dates(value)
       case value
-      when Date then value.iso8601
-      when Time then value.iso8601
+      when Date, Time then value.iso8601
       when Hash then value.transform_values { |v| normalize_dates(v) }
       when Array then value.map { |v| normalize_dates(v) }
       else value

data/lib/edoxen/source_url.rb

@@ -4,13 +4,13 @@ module Edoxen
   # Per-language canonical source URL (e.g. one PDF per language).
   # Carries the URL ref, its format, the ISO 639-3 language_code the URL
   # is the canonical source for, and an optional `kind` discriminator
-  # (agenda_pdf, minutes_pdf, resolutions_pdf, ...) used by the Meeting
-  # model. Existing Resolution fixtures without `kind` still parse —
-  # the field is optional.
+  # (agenda_pdf, minutes_pdf, decisions_pdf, ...) used by the Meeting
+  # model. Existing fixtures without `kind` still parse — the field is
+  # optional.
   class SourceUrl < Lutaml::Model::Serializable
     attribute :ref, :string
     attribute :format, :string
-    attribute :language_code, :string
+    attribute :spelling, :string
     attribute :kind, :string, values: Enums::SOURCE_URL_KIND
   end
 end

data/lib/edoxen/statement.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # One remark made by one or more meeting members on a topic or
+  # a minutes section. The `kind` discriminator separates the
+  # three BS 0:2006 statement types (statement, comment,
+  # standpoint); adding a new kind is a one-line StatementKind
+  # enum extension (OCP).
+  #
+  # Attachment points: `MinutesSection#statements[]` (per-meeting)
+  # and `Topic#statements[]` (standing position that travels with
+  # the topic across meetings). Same class, two attachment points
+  # — the semantic distinction comes from where the statement is
+  # attached, not from a subclass.
+  class Statement < Lutaml::Model::Serializable
+    attribute :kind, :string, values: Enums::STATEMENT_KIND
+    attribute :description, LocalizedString, collection: true
+    attribute :party, Person, collection: true
+    attribute :extensions, MeetingExtension, collection: true
+  end
+end

data/lib/edoxen/structured_identifier.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Edoxen
-  # A structured resolution identifier, e.g. prefix "ISO" + number "2019-01".
-  # A Resolution carries 1..* StructuredIdentifier so a single resolution can
+  # A structured decision identifier, e.g. prefix "ISO" + number "2019-01".
+  # A Decision carries 1..* StructuredIdentifier so a single decision can
   # hold its TC number, its SC number, and any cross-cutting reference number
   # without forcing callers to flatten them into one opaque string.
   class StructuredIdentifier < Lutaml::Model::Serializable

data/lib/edoxen/topic.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Topic — the subject of discussion at a Meeting.
+  # A Topic can have documents (text), assets (non-text), references
+  # (external pointers), and is the anchor for Motions and Decisions.
+  #
+  # Cross-meeting threading via `resumption_of` (URN to a prior Topic
+  # in a prior Meeting) — pattern from HK LegCo OData schema.
+  class Topic < Lutaml::Model::Serializable
+    attribute :identifier, :string
+    attribute :urn, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :description, LocalizedString, collection: true
+    attribute :status, :string, values: Enums::TOPIC_STATUS
+    attribute :resumption_of, :string
+    attribute :documents, TopicDocument, collection: true
+    attribute :assets, TopicAsset, collection: true
+    attribute :references, Reference, collection: true
+    attribute :motions, :string, collection: true
+    attribute :decisions, :string, collection: true
+    attribute :statements, Statement, collection: true
+    attribute :declarations, Declaration, collection: true
+    attribute :extensions, MeetingExtension, collection: true
+
+    # --- 1.0 derivation accessor (1.0 design review) --------------------
+    # Returns the Decisions in `collection` whose `about_topics` includes
+    # this Topic's URN.
+    #
+    # Storage side: Decision.aboutTopics (SSOT for the relationship).
+    # The stored `decisions[]` field remains on the wire for back-compat
+    # through v2.x; 1.0 removes it and this becomes the only path.
+    def decisions_in(collection:)
+      return [] unless collection && urn
+
+      collection.decisions.select { |decision| decision.about_topics&.include?(urn) }
+    end
+  end
+end

data/lib/edoxen/topic_asset.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # TopicAsset — non-text resource about a Topic.
+  # Examples: image, dataset, model, video.
+  class TopicAsset < Lutaml::Model::Serializable
+    attribute :identifier, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :kind, :string
+    attribute :url, :string
+    attribute :format, :string
+    attribute :extensions, MeetingExtension, collection: true
+  end
+end

data/lib/edoxen/topic_document.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # TopicDocument — text-bearing document about a Topic.
+  # Examples: bill text, ISO draft, report, agenda attachment.
+  class TopicDocument < Lutaml::Model::Serializable
+    attribute :identifier, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :version, :string
+    attribute :status, :string
+    attribute :url, :string
+    attribute :format, :string
+    attribute :spelling, :string
+    attribute :extensions, MeetingExtension, collection: true
+  end
+end

data/lib/edoxen/urn_for.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # URN helpers for entities that don't carry their URN inline (e.g.
+  # AgendaItem which derives its URN from the parent Meeting). The
+  # scheme is hierarchical:
+  #
+  #   urn:oiml:{body}:{kind}:{slug}(:{sub-kind}:{sub-id})*
+  #
+  # Examples:
+  #   urn:oiml:ciml:meeting:ciml-60
+  #   urn:oiml:ciml:meeting:ciml-60:agenda:6.2
+  #   urn:oiml:doc:ciml:resolution:2025-01
+  #
+  # Use {UrnFor.agenda_item} to compute an agenda item URN from its
+  # parent meeting URN + label, and {UrnFor.parse} to decompose one.
+  module UrnFor
+    AGENDA_SEGMENT = "agenda"
+    SEGMENT_RE = /[^:]+/
+
+    # Build an AgendaItem URN from its parent Meeting URN and the
+    # agenda item label (e.g. "6.2"). Returns nil if either input is
+    # blank so callers can use this as a default-value generator
+    # without raising.
+    def self.agenda_item(meeting_urn:, label:)
+      m = meeting_urn.to_s
+      l = label.to_s
+      return nil if m.empty? || l.empty?
+
+      "#{m}:#{AGENDA_SEGMENT}:#{l}"
+    end
+
+    # Parse an agenda item URN into its component parts. Returns a Hash
+    # with :meeting_urn and :label keys, or nil if the URN doesn't
+    # match the expected shape.
+    #
+    #   UrnFor.parse("urn:oiml:ciml:meeting:ciml-60:agenda:6.2")
+    #   # => { meeting_urn: "urn:oiml:ciml:meeting:ciml-60",
+    #   #      label: "6.2" }
+    def self.parse(urn)
+      return nil unless urn
+
+      s = urn.to_s
+      idx = s.rindex(":#{AGENDA_SEGMENT}:")
+      return nil unless idx
+
+      meeting_urn = s[0...idx]
+      label = s[(idx + AGENDA_SEGMENT.length + 2)..]
+      return nil if meeting_urn.empty? || label.to_s.empty?
+
+      { meeting_urn: meeting_urn, label: label }
+    end
+
+    # Walk an Agenda tree and set each item's `urn` based on the
+    # parent meeting URN. Skips items that already have a URN. Useful
+    # as a backfill step in data-fix scripts.
+    def self.assign_to_agenda!(agenda, meeting_urn)
+      return nil unless agenda && meeting_urn
+
+      (agenda.items || []).each do |item|
+        next if item.urn && !item.urn.to_s.empty?
+
+        item.urn = agenda_item(meeting_urn: meeting_urn, label: item.label)
+      end
+      agenda
+    end
+  end
+end

data/lib/edoxen/venue.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Venue — polymorphic by discriminator, flat on the wire.
+  #
+  # The `kind` field discriminates between physical and virtual venues.
+  # All possible fields (physical-specific and virtual-specific) live on
+  # this one class as optional attributes — only the ones matching the
+  # `kind` are populated.
+  #
+  # 1.0 (per-field localization, ISO 24229):
+  #   - All translatable fields are Localized<String>[0..*].
+  #   - Added: `urn` for registry storage; `ref` for reference-by-URN.
+  class Venue < Lutaml::Model::Serializable
+    attribute :ref, :string
+    attribute :local_ref, :string
+    attribute :urn, :string
+    attribute :kind, :string, values: Enums::VENUE_KIND
+    attribute :name, LocalizedString, collection: true
+    attribute :label, LocalizedString, collection: true
+    attribute :description, LocalizedString, collection: true
+    attribute :capacity, :integer
+    attribute :url, :string
+    attribute :contact_methods, ContactMethod, collection: true
+
+    # Physical-venue fields (populated when kind == "physical").
+    attribute :unlocode, :string
+    attribute :iata_code, :string
+    attribute :address, LocalizedString, collection: true
+    attribute :city, :string
+    attribute :country_code, :string
+    attribute :lat, :float
+    attribute :lon, :float
+    attribute :building, LocalizedString, collection: true
+    attribute :floor, LocalizedString, collection: true
+    attribute :room, LocalizedString, collection: true
+    attribute :access_notes, LocalizedString, collection: true
+
+    # Virtual-venue fields (populated when kind == "virtual").
+    attribute :uri, :string
+    attribute :features, :string, collection: true, values: Enums::VIRTUAL_FEATURE
+    attribute :passcode, :string
+    attribute :meeting_id, :string
+    attribute :dial_in_numbers, :string, collection: true
+    attribute :waiting_room, :boolean
+    attribute :registration_required, :boolean
+
+    attribute :extensions, MeetingExtension, collection: true
+
+    def reference?
+      (!ref.nil? && !ref.to_s.empty?) ||
+        (!local_ref.nil? && !local_ref.to_s.empty?)
+    end
+
+    def physical?
+      kind == "physical"
+    end
+
+    def virtual?
+      kind == "virtual"
+    end
+
+    def unlocode_entry
+      return nil if unlocode.nil? || unlocode.to_s.empty?
+
+      Edoxen::ReferenceData.find_unlocode(unlocode)
+    end
+
+    def iata_entry
+      return nil if iata_code.nil? || iata_code.to_s.empty?
+
+      Edoxen::ReferenceData.find_iata(iata_code)
+    end
+
+    def features_list
+      return "" if features.nil? || features.empty?
+
+      features.join(", ")
+    end
+  end
+end

data/lib/edoxen/venue_register.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Edoxen
+  # Registry of Venues indexed by scoped URN. Mirrors ContactRegister:
+  # members carry `urn: urn:edoxen:venue:{scope}:{local-id}`; the
+  # collection's `scope` MUST match the scope segment in member URNs.
+  # Stream loading belongs to the service layer.
+  class VenueRegister < Lutaml::Model::Serializable
+    attribute :scope, :string
+    attribute :title, LocalizedString, collection: true
+    attribute :venues, Venue, collection: true
+    attribute :extensions, MeetingExtension, collection: true
+
+    def find_by_urn(urn)
+      venues&.find { |v| v.urn == urn }
+    end
+  end
+end