Edoxen information models

Purpose

Edoxen is a generic, semantically clear information model for meetings, agendas, and the decisions they produce. It provides a common framework that allows interoperability between standards bodies, parliaments, conferences, corporate boards, technical communities, and any other organization that runs formal meetings with published records.

This repository holds the canonical LutaML UML definition of the model. The Ruby gem that implements it lives at metanorma/edoxen and mirrors the LutaML files 1:1 — attribute declarations, enum values, and field shapes.

Applicability

The model is GENERIC. Core entities cover every domain; profile extensions (ISO 8601-2 §15) cover domain-specific concepts.

Tested against (see references/):

• Standards bodies: ISO, ISO/TMB, ITU-T, ITU-D, WTSA, BIPM/CGPM, OIML, ILO

• Parliamentary: UK Hansard, HK LegCo (16 OData entities), US Congress (govinfo CHRG)

• Technical community: IETF (multi-track), W3C TPAC, Apache Foundation

• Academic conferences: Crossref-registered (ACM, IEEE, Springer)

• Corporate governance: Apache Board, general corporate boards

• Generic web/virtual: iCalendar (RFC 5545/7986/5546/9253) semantics

Architectural principle: generic core + profile extensions

The core schema is the intersection of all meeting domains — every meeting has identity, time, place, people, agenda, decisions, minutes. Domain-specific concepts (Bill, Witness, Petition, Address, Statement, QuorumBell, etc.) live in profile extensions, not in the core.

Every core entity has an extensions: MeetingExtension[0..*] slot. Adopters register their own profile namespace (e.g. legco, us-congress, ietf, apache-board) and define extension kinds within it. See references/profiles/legco.adoc for the canonical example.

This pattern follows ISO 8601-2 §15 (Profiles) — see references/iso8601-2.adoc.

Information model

The information models are in the LutaML UML format.

See the models/ directory. One .lutaml file per concept, organized by concern:

File	Concept
Identity & classification	meeting.lutaml
A single Meeting (event) with all broadened-scope fields.	meeting_collection.lutaml
Top-level wrapper for many Meetings.	meeting_series.lutaml
Parent of recurring meetings (Crossref proceedings-series, IETF, etc.).	meeting_identifier.lutaml
Lightweight venue + date reference.	structured_identifier.lutaml
prefix + number identifier (1..* per Meeting).	meeting_type.lutaml
Closed value set: plenary, working_group, committee, conference, hearing, markup, board_meeting, etc.	meeting_status.lutaml, visibility.lutaml
Status + access classification (public/private/confidential).	meeting_relation.lutaml, meeting_relation_type.lutaml
Directed links, aligned to RFC 9253 RELTYPE.	Time & place
date_range.lutaml	ISO 8601-2 §10 time interval.
recurrence.lutaml	ISO 8601-2 §13 structured, queryable.
recurrence_freq.lutaml, recurrence_by_day.lutaml	Recurrence subcomponents.
venue.lutaml	Polymorphic base class (kind discriminator + common fields).
physical_venue.lutaml	class PhysicalVenue < Venue — UNLOCODE + IATA + address.
virtual_venue.lutaml	class VirtualVenue < Venue — uri + features + passcode.
venue_kind.lutaml, virtual_feature.lutaml	Closed value sets.
Structure	agenda.lutaml
The business-order document of a Meeting.	agenda_item.lutaml
One entry on an Agenda (carries topics[0..*]).	meeting_component.lutaml
Flat sub-events (track, session, debate, opening, closing, break, etc.).	component_kind.lutaml
18 values: substantive + procedural (subsumes ScheduleItem).	component_localization.lutaml
Per-language content for a Component.	deadline.lutaml
A time-bound requirement.	People
person.lutaml	Identity + contact + affiliation + kind.
officer.lutaml, officer_role.lutaml	Chair/secretary/treasurer/etc. with role enum.
attendance.lutaml	One record per person present, with role + response.
participation_status.lutaml	In-meeting observation enum.
attendance_role.lutaml	iCalendar ROLE, plain English (chair/required/optional/non_participant).
attendance_response.lutaml	iCalendar PARTSTAT, plain English (pending/confirmed/declined/tentative/delegated).
Outcomes (procedural core)	decision.lutaml
Base type for formal outcomes (was Resolution).	decision_kind.lutaml
9 values: resolution, order, ruling, determination, recommendation, statement, finding, opinion, other.	decision_status.lutaml
State machine: draft → proposed → under_consideration → decided/negatived/withdrawn/deferred.	decision_collection.lutaml, decision_metadata.lutaml
Top-level Decision container.	decision_date.lutaml, decision_date_type.lutaml
Typed dates (adoption, drafted, decided, etc.).	decision_relation.lutaml, decision_relation_type.lutaml
Directed links between Decisions.	motion.lutaml, motion_status.lutaml
Procedural act with 9-state machine: introduced → seconded → debating → question_put → voting → carried/negatived/withdrawn/lapsed.	voting.lutaml
State machine: called → in_progress → decided/withdrawn/deferred.	voting_status.lutaml, voting_method.lutaml, voting_outcome.lutaml
Enums.	voting_counts.lutaml
ayes / noes / abstentions / absent counts.	vote_record.lutaml, vote_type.lutaml
Per-person vote; links to Voting via votingRef.	Topics
topic.lutaml	Subject of discussion with status + cross-meeting resumptionOf.
topic_status.lutaml	open / under_discussion / decided / deferred / withdrawn.
topic_document.lutaml	Text-bearing (bill, draft, report).
topic_asset.lutaml	Non-text (image, dataset, model, video).
reference.lutaml	Generic external pointer.
Records	minutes.lutaml
The narrative record of a Meeting (one per language).	minutes_section.lutaml
Section of Minutes (typically keyed by agenda-item).	localization.lutaml, meeting_localization.lutaml, schedule_item_localization.lutaml
Glossarist-style per-language content.	Sources
url.lutaml, source_url.lutaml, source_url_kind.lutaml	URLs — generic and per-language source PDFs.
Hosts	host_ref.lutaml, host_type.lutaml
Typed reference to an organization.	Identity (Decision-side)
subject_body.lutaml	Structured body for a Decision’s subject (committee/WG/project).
action.lutaml, action_type.lutaml	Per-localization action statements.
consideration.lutaml, consideration_type.lutaml	Per-localization consideration statements.
approval.lutaml, approval_degree.lutaml, approval_type.lutaml	Per-localization approval statements.
Profile mechanism (ISO 8601-2 §15)	meeting_extension.lutaml
Profile-based extension: profile + kind + attributes[].	extension_attribute.lutaml

The Meeting trinity (+ 2)

A Meeting owns five distinct artifacts, each with its own lifetime and structure:

Artifact	Concept
Agenda	The business order, drafted before the meeting. Items, opening_session, closing_session, source_doc.
Decision[]	The formal outcomes adopted by the meeting. Joined to the Meeting by URN.
Minutes	The running narrative record of what was said at the meeting.
Motion[]	Procedural acts that bring decisions (someone says "I move that…​"). State machine.
Voting[]	State-machine votings on motions, with per-member vote records.

Plus five Meeting-side collections:

Collection	Concept
attendance[]	One Attendance per person present.
officers[]	Chair, secretary, treasurer, etc. with role enum.
hosts[]	Organizations hosting the Meeting.
venues[]	Polymorphic: physical (with UNLOCODE/IATA) or virtual (with URI/features).
components[]	Flat sub-events: tracks, sessions, debates, breaks, openings, closings.

Polymorphic Venue

A Meeting has multiple Venue instances, each either PhysicalVenue or VirtualVenue. This is polymorphic via inheritance (LutaML class PhysicalVenue < Venue), NOT via composition.

venues:
  - kind: physical
    name: BIML Headquarters, Salle Turgot
    physicalVenue:
      unlocode: FRPAR
      address: 11 Rue Turgot, 75009 Paris, France
      countryCode: FR
      lat: 48.8761
      lon: 2.3395
  - kind: virtual
    name: Main Video Conference
    label: Zoom — Host
    virtualVenue:
      uri: https://oiml.zoom.us/j/12345
      passcode: "secret"
      features: [audio, video, screen]
  - kind: virtual
    name: International Dial-in
    label: Phone bridge
    virtualVenue:
      uri: tel:+33-1-2345-6789,,,12345#
      features: [phone, audio]

UN/LOCODE and IATA codes are validated by the unlocodes and iata gems.

Multilingual support

The model supports multilingual meeting sets using the glossarist-style localizations[] pattern. Each Decision, Meeting, MeetingComponent, and Topic carries its language-agnostic admin fields plus a localizations[] array with one entry per language.

Each Localization declares its languageCode (ISO 639-3 three-letter code) and script (ISO 15924 four-letter code).

YAML representation

Wire-name convention

The LutaML files use camelCase for attribute names (agendaItem, languageCode, dateEffective). That is notation. The YAML wire form is snake_case (agenda_item, language_code, date_effective) — matching Ruby and YAML convention.

The Ruby gem’s schema_enum_sync_spec.rb and schema_model_sync_spec.rb enforce that the gem’s schema/edoxen.yaml matches the LutaML definition value-for-value.

Profile mechanism

Every core entity has an extensions: MeetingExtension[0..*] slot. Adopters define their own profile namespace and the extension kinds within it.

extensions:
  - profile: legco
    kind: summoning_bell
    attributes:
      - key: sectionCode
        value: b2d
      - key: timestamp
        value: "2024-01-15T11:30:00Z"

See: - models/meeting_extension.lutaml, models/extension_attribute.lutaml - references/profiles/legco.adoc — canonical example (8 extension kinds)

Ruby implementation

The Ruby gem at metanorma/edoxen implements this model:

• One Ruby class per LutaML class, attribute declarations mirror the LutaML definitions 1:1.

• Edoxen::Enums mirrors the LutaML enums; the schema’s enum arrays are kept in lockstep by the gem’s sync specs.

• Edoxen::Decision#in_language(code, fallback:) and #primary_localization provide the canonical lookup accessors. The same accessors exist on Edoxen::Meeting.

• JSON-Schemas (schema/edoxen.yaml for Decisions, schema/meeting.yaml for Meetings) enforce additionalProperties: false, required, enum, and pattern constraints.

• A Thor CLI wraps both layers: edoxen validate / edoxen normalize for Decisions; edoxen validate-meetings / edoxen normalize-meetings for Meetings.

Install:

gem install edoxen

Validate either document type:

edoxen validate            "decisions/*.yaml"
edoxen validate-meetings   "meetings/*.yaml"

References

The references/ directory contains 9 reference documents that ground the model in real-world source data:

• icalendar.adoc — RFC 5545/7986/5546/9253 (logistics layer)

• schema-org-event.adoc — public-web event vocabulary

• akoma-ntoso.adoc — UN/FAO parliamentary proceedings

• ietf.adoc — multi-track technical meetings

• apache-board.adoc — corporate-style published minutes

• congress-gov.adoc — US Congressional Hearings (govinfo CHRG)

• hansard.adoc — HK LegCo OData (16 entity types)

• crossref-conference.adoc — academic conference proceedings

• iso8601-2.adoc — ISO 8601-2 §10/§11/§13/§15 (date/time/recurrence/profiles)

TODO.refactor/

The TODO.refactor/ directory contains the planning documents for the v2.0.0 broadened-scope refactor:

• 00-MASTER.adoc — overview, sequencing, architectural constraints

• 01-43 — phased work units

• PROGRESS.md — cross-session state tracker