edoxen 0.1.1 → 0.3.0

data/README.adoc

@@ -1,258 +1,202 @@
 = Edoxen
 
 https://github.com/metanorma/edoxen[image:https://img.shields.io/github/stars/metanorma/edoxen.svg?style=social[GitHub Stars]]
-https://github.com/metanorma/edoxen[image:https://img.shields.io/github/forks/metanorma/edoxen.svg?style=social[GitHub Forks]]
 image:https://img.shields.io/github/license/metanorma/edoxen.svg[License]
 image:https://img.shields.io/github/actions/workflow/status/metanorma/edoxen/test.yml?branch=main[Build Status]
 image:https://img.shields.io/gem/v/edoxen.svg[RubyGems Version]
 
 == Purpose
 
-Edoxen is a set of information models used for representing resolution and
-decision information. They are designed to provide a structured way to model
-formal resolutions, including their metadata, actions, considerations, and
-approvals.
+Edoxen is a Ruby library for the canonical Edoxen information model of
+formal resolutions and decisions. It is built on top of the
+https://github.com/lutaml/lutaml[ lutaml-model] serialization framework.
 
-The `edoxen` gem provides a Ruby library for working with these 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.
+The information model is defined in
+https://github.com/metanorma/edoxen-model/tree/main/models[ LutaML UML
+files] (one `.lutaml` per concept). This gem mirrors that model exactly —
+attribute declarations, enum values, and field shapes — so that anything
+you can express in LutaML you can also construct, serialize, and validate
+in Ruby.
 
-This library is particularly useful for standards organizations, committees,
-and governance bodies that need to maintain structured records of their
-decision-making processes.
-
-
-== Origin
-
-"Edoxen" is how all resolutions of Ancient Athens started.
-
-____
-"It was the opinion of... (the people and city that...)"
-____
-
-The word "edoxen" originates from the Ancient Greek word edokeō (ἔδοξεν),
-meaning "it was the opinion of" or "it seemed good to". This term was used in
-the context of formal resolutions and decisions made by the Athenian assembly,
-reflecting the collective will and judgment of the citizens.
-
-
-== Features
-
-* Classes for modeling resolutions, actions, considerations, and approvals
-* Support for resolution collections with metadata
-* YAML and JSON serialization with round-trip compatibility
-* Structured identifiers and meeting information
-* Resolution relationships and dependencies
-* Integration with the `lutaml-model` serialization framework
-* Comprehensive YAML schema for validation
-* Real-world data compatibility with ISO/TC 154 resolution formats
+The intended users are standards organizations and governance bodies that
+need to publish structured records of formal decision-making. Real-world
+samples (ISO/TC 154, CIPM, OIML CIML) ship in `spec/fixtures/`.
 
 == Installation
 
-Add this line to your application's Gemfile:
-
 [source,ruby]
 ----
 gem 'edoxen'
 ----
 
-And then execute:
-
-[source,sh]
-----
-$ bundle install
-----
-
-Or install it yourself as:
-
-[source,sh]
-----
-$ gem install edoxen
-----
+Then `bundle install`, or `gem install edoxen` standalone.
 
 == Quick start
 
-Here's a minimal example to get you started:
-
 [source,ruby]
 ----
 require 'edoxen'
 
-# Create a simple resolution
-resolution = Edoxen::Resolution.new(
-  title: "Adoption of new standard",
-  type: "resolution",
-  category: "Technical resolutions",
-  identifier: "2024-01"
-)
-
-# Add an action to the resolution
-action = Edoxen::Action.new(
-  type: "resolves",
-  message: "to adopt ISO 12345 as a new standard",
-  date_effective: Date.new(2024, 1, 15)
-)
-resolution.actions = [action]
-
-# Add a consideration
-consideration = Edoxen::Consideration.new(
-  type: "having",
-  message: "reviewed the technical specifications"
-)
-resolution.considerations = [consideration]
-
-# Serialize to YAML
-puts resolution.to_yaml
-
-# Create a resolution collection
-collection = Edoxen::ResolutionCollection.new(
-  metadata: {
-    title: "Resolutions of the 42nd plenary meeting",
-    date: "2024-01-15",
-    source: "ISO/TC 154 Secretariat"
-  },
-  resolutions: [resolution]
-)
-
-# Serialize collection to YAML
-puts collection.to_yaml
-----
-
-== Documentation
-
-=== Data models
-
-The library provides these main model classes:
-
-`Edoxen::Resolution`::
-Core model representing a formal resolution with title, type, category, and
-associated elements.
+yaml = File.read('resolutions.yaml')
+collection = Edoxen::ResolutionCollection.from_yaml(yaml)
 
-`Edoxen::ResolutionCollection`::
-Container for multiple resolutions with metadata about the meeting or
-collection context.
+collection.resolutions.each do |resolution|
+  prefix = resolution.identifier.first.prefix
+  number = resolution.identifier.first.number
+  puts "#{prefix}/#{number}"
 
-`Edoxen::Action`::
-Represents actions taken within a resolution (e.g., "resolves", "requests",
-"thanks").
+  resolution.localizations.each do |loc|
+    puts "  [#{loc.language_code}/#{loc.script}] #{loc.title}"
+    loc.actions.each do |action|
+      puts "    - #{action.type}: #{action.message}"
+    end
+  end
+end
 
-`Edoxen::Consideration`::
-Models considerations that lead to a resolution (e.g., "having", "noting",
-"recognizing").
-
-`Edoxen::Approval`::
-Captures approval information including type and degree of consensus.
-
-`Edoxen::MeetingIdentifier`::
-Contains meeting identification information such as venue, date, and identifier.
-
-`Edoxen::ResolutionRelationship`::
-Defines relationships between resolutions (e.g., "supersedes", "amends").
-
-=== Architecture overview
-
-The library is built on `lutaml-model` and follows these design principles:
-
-**Model-based approach**::
-Each entity is represented as a Ruby class with defined attributes and
-serialization mappings.
-
-**Flexible serialization**::
-Support for both YAML and JSON formats with automatic type conversion and
-round-trip compatibility.
-
-**Extensible structure**::
-Models allow additional properties beyond the core schema, enabling
-customization for specific organizational needs.
-
-**Real-world compatibility**::
-Designed to work with existing resolution data formats used by standards
-organizations.
-
-== Usage workflow
-
-The `edoxen` workflow follows a straightforward approach:
-
-=== 1. Data modeling
+# Round-trip back to YAML
+puts collection.to_yaml
+----
 
-. **Create resolutions**: Instantiate `Resolution` objects with required
-  attributes
-. **Add components**: Attach actions, considerations, approvals as needed
-. **Build collections**: Group resolutions into collections with metadata
+== Data model
 
-=== 2. Serialization and persistence
+The full model is in `lib/edoxen/*.rb` (Ruby) and `schema/edoxen.yaml`
+(JSON-Schema). Both are kept in lockstep by
+`spec/edoxen/schema_enum_sync_spec.rb`.
 
-. **Export to YAML/JSON**: Use built-in serialization methods
-. **Validate structure**: Leverage the provided YAML schema for validation
-. **Round-trip processing**: Load and save data while preserving structure
+[source]
+----
+ResolutionCollection
+├── metadata:  ResolutionMetadata
+│                ├── title / title_localized[]
+│                ├── date
+│                ├── source
+│                ├── source_urls: SourceUrl[]
+│                ├── city, country_code
+└── resolutions: Resolution[]
+                   ├── identifier: StructuredIdentifier[1..*]
+                   ├── type: ResolutionType (resolution | recommendation | decision | declaration)
+                   ├── doi, urn, agenda_item
+                   ├── dates: ResolutionDate[]
+                   ├── categories: String[]
+                   ├── meeting: MeetingIdentifier
+                   ├── relations: ResolutionRelation[]
+                   ├── urls: Url[]
+                   └── localizations: Localization[1..*]
+                                      ├── language_code (ISO 639-3)
+                                      ├── script       (ISO 15924)
+                                      ├── title, subject, message, considering
+                                      ├── considerations: Consideration[]
+                                      ├── approvals: Approval[]
+                                      └── actions: Action[]
+----
 
-== YAML format specification
+Every translatable field on a Resolution is wrapped inside one of its
+`localizations[]` entries. Language-agnostic admin fields
+(`identifier`, `doi`, `urn`, `agenda_item`, `dates`, `categories`,
+`meeting`, `relations`, `urls`) live on the parent `Resolution`.
 
-Edoxen uses a structured YAML format for resolution data. Here's an example:
+== Multilingual resolution sets
 
 [source,yaml]
 ----
-metadata:
-  title: "Resolutions of the 42nd plenary meeting of ISO/TC 154"
-  date: "2024-01-15"
-  source: "ISO/TC 154 Secretariat"
-  venue: "Virtual meeting"
-
 resolutions:
-  - identifier: "2024-01"
-    title: "Adoption of new standard"
-    type: "resolution"
-    category: "Technical resolutions"
-
-    considerations:
-      - type: "having"
-        message: "reviewed the technical specifications"
-
-    actions:
-      - type: "resolves"
-        message: "to adopt ISO 12345 as a new standard"
-        date_effective: "2024-01-15"
-
-    approvals:
-      - type: "affirmative"
-        degree: "unanimous"
+  - identifier:
+      - prefix: CIML
+        number: "2025-44"
+    doi: 10.63493/resolutions/ciml202544
+    agenda_item: "16.2"
+    dates:
+      - date: 2025-10-13
+        type: discussed
+    localizations:
+      - language_code: eng
+        script: Latn
+        title: Decision on the renewal of the contract of Mr Anthony Donnellan
+        subject: CIML
+        actions:
+          - type: decides
+            date_effective:
+              date: 2025-10-13
+              type: adoption
+            message: |
+              The Committee decides to renew the contract of
+              Mr Anthony Donnellan as BIML Director.
+      - language_code: fra
+        script: Latn
+        title: Décision sur le renouvellement du contrat de M. Anthony Donnellan
+        subject: CIML
+        actions:
+          - type: decides
+            date_effective:
+              date: 2025-10-13
+              type: adoption
+            message: |
+              Le Comité décide de renouveler le contrat de
+              M. Anthony Donnellan en tant que Directeur du BIML.
 ----
 
-=== Schema validation
+== Command-line interface
+
+The `edoxen` executable exposes two commands.
+
+=== `validate` — JSON-Schema validation + model parsing
 
-A comprehensive YAML schema is provided at `schema/edoxen.yaml` for validating
-resolution data files. The schema follows JSON Schema Draft 7 conventions and
-includes:
+[source,sh]
+----
+$ edoxen validate "spec/fixtures/*.yaml"
+----
 
-* Complete structure definitions for all model types
-* Enumerated values for type validation
-* Date format validation
-* Flexible extensibility with `additionalProperties`
+Runs both `Edoxen::SchemaValidator` and `Edoxen::ResolutionCollection.from_yaml`
+against each matching file. The schema catches `additionalProperties`,
+`required`, enum, and pattern violations; the model catches structural
+problems the schema can't express.
 
-The schema can be used with standard JSON Schema validators to ensure data
-integrity and compliance.
+Exit code is non-zero if any file fails.
 
-== Real-world examples
+=== `normalize` — round-trip every fixture through the model
 
-The library has been tested with real resolution data from ISO/TC 154 and
-other standards organizations. It successfully handles:
+[source,sh]
+----
+$ edoxen normalize "spec/fixtures/*.yaml" --output clean/
+$ edoxen normalize legacy.yaml --inplace
+----
 
-* Complex resolution structures with multiple actions and considerations
-* Various resolution types (resolutions, recommendations, decisions)
-* Meeting metadata and organizational information
-* Cross-references and relationships between resolutions
-* Historical data migration and format conversion
+Loads each YAML file, parses it through the Ruby model, and writes the
+result back. Used to migrate between model versions. Either `--output DIR`
+or `--inplace` is required (mutually exclusive).
+
+== Architecture
+
+* `lib/edoxen.rb` is the single entry-point. It configures
+  `Lutaml::Model::Config` and `autoload`s every model class and service.
+* Each model lives in its own file under `lib/edoxen/`. No `require_relative`
+  — all cross-references resolve through Ruby autoload.
+* `lib/edoxen/enums.rb` is the single source of truth for every enum
+  value used by the gem. Both the Ruby model (`attribute :type, :string,
+  values: Enums::ACTION_TYPE`) and `schema/edoxen.yaml` refer to the
+  same constant; `spec/edoxen/schema_enum_sync_spec.rb` asserts equality
+  at runtime.
+* `lib/edoxen/schema_validator.rb` is intentionally small: a
+  `SchemaValidator::ValidationError`, a `validate_file` method, a
+  `validate_content` method, and a `LineMap` module for line-accurate
+  error reporting. Adding new collection paths never requires touching
+  it — the lookup is longest-prefix match against an indent-heuristic
+  line map.
+* `lib/edoxen/cli.rb` is the Thor surface that glues SchemaValidator and
+  `ResolutionCollection.from_yaml` together for the two CLI commands.
 
 == Contributing
 
-Bug reports and pull requests are welcome on GitHub at
-https://github.com/metanorma/edoxen.
+Follow the rules in `CLAUDE.md`:
 
-== License and Copyright
+* All public methods have specs.
+* Specs use real model instances — never `double()`.
+* Serialization goes through `lutaml-model` only — no hand-rolled
+  `to_h`, `from_h`, `to_yaml`, or `to_json` on a model class.
+* Schema and Ruby enum values must agree; the schema_sync_spec catches
+  drift.
+* All changes go through PRs. Never commit to `main`, never push tags.
 
-This project is licensed under the BSD 2-clause License.
-See the link:LICENSE[] file for details.
+== License
 
-Copyright Ribose.
+BSD-2-Clause. Copyright Ribose Inc.

data/edoxen.gemspec

@@ -10,7 +10,11 @@ Gem::Specification.new do |spec|
 
   spec.summary = "Edoxen is a set of information models used for representing resolution and decision information."
   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 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.
   HEREDOC
 
   spec.homepage = "https://github.com/metanorma/edoxen"
@@ -32,5 +36,7 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "json_schemer", "~> 2.0"
   spec.add_dependency "lutaml-model", "~> 0.7"
+  spec.add_dependency "thor", "~> 1.0"
 end

data/exe/edoxen

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/edoxen"
+
+Edoxen::Cli.start(ARGV)

data/lib/edoxen/_metadata.rb.deprecated

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "resolution_date"
+require_relative "url"
+require_relative "localization"
+
+module Edoxen
+  # A per-language source-URL record. Carries the URL ref, its format
+  # (pdf, html, ...), and the language_code (ISO 639-3) for which the
+  # URL is the canonical source.
+  class SourceUrl < Lutaml::Model::Serializable
+    attribute :ref, :string
+    attribute :format, :string
+    attribute :language_code, :string
+
+    key_value do
+      map "ref", to: :ref
+      map "format", to: :format
+      map "language_code", to: :language_code
+    end
+  end
+
+  class Metadata < Lutaml::Model::Serializable
+    attribute :title, :string
+    attribute :identifier, :string
+    attribute :dates, ResolutionDate, collection: true
+    attribute :source, :string
+    attribute :venue, :string
+    attribute :chair, :string
+    attribute :urls, Url, collection: true
+
+    # OIML extensions — see TODO.complete/14 for the glossarist-style
+    # i18n model. `title_localized` carries the per-language title
+    # parallel to Resolution#localizations. `source_urls` carries the
+    # per-language PDF URLs. `city`/`country_code` carry the IATA /
+    # ISO 3166-1 alpha-2 codes for the host venue.
+    attribute :title_localized, Localization, collection: true
+    attribute :source_urls, SourceUrl, collection: true
+    attribute :city, :string
+    attribute :country_code, :string
+
+    key_value do
+      map "title", to: :title
+      map "identifier", to: :identifier
+      map "dates", to: :dates
+      map "source", to: :source
+      map "venue", to: :venue
+      map "chair", to: :chair
+      map "urls", to: :urls
+      map "title_localized", to: :title_localized
+      map "source_urls", to: :source_urls
+      map "city", to: :city
+      map "country_code", to: :country_code
+    end
+  end
+end

data/lib/edoxen/action.rb

@@ -1,65 +1,17 @@
 # frozen_string_literal: true
 
-require "lutaml/model"
-
 module Edoxen
+  # Verb + one effective date + human-readable message. Used inside a
+  # Localization to express the multilingual part of an action.
   class Action < Lutaml::Model::Serializable
-    ACTION_TYPE_ENUM = %w[
-      adopts thanks approves decides declares asks invites resolves confirms
-      welcomes recommends requests congratulates instructs urges appoints
-      resolves further instructs calls-upon encourages affirms elects
-      authorizes charges states remarks judges sanctions abrogates empowers
-    ].freeze
-
-    attribute :type, :string, values: ACTION_TYPE_ENUM
-    attribute :date_effective, :date
+    attribute :type, :string, values: Enums::ACTION_TYPE
+    attribute :date_effective, ResolutionDate
     attribute :message, :string
-    attribute :subject, :string
 
     key_value do
       map "type", to: :type
       map "date_effective", to: :date_effective
       map "message", to: :message
-      map "subject", to: :subject
     end
   end
 end
-
-# Action {
-#   type: ActionType
-#   dateEffective: Date
-#   message: Text
-# }
-
-# enum ActionType {
-#   adopts
-#   thanks / expresses-appreciation (subjects)
-#   approves
-#   decides
-#   declares
-#   asks (subjects)
-#   invites / further invites (subjects)
-#   resolves
-#   confirms
-#   welcomes (subjects)
-#   recommends
-#   requests (subjects)
-#   congratulates (subjects)
-#   instructs (subjects)
-#   urges (subjects)
-#   appoints (subjects)
-#   resolves further
-#   instructs (subjects)
-#   calls upon (subjects)
-#   encourages (subjects)
-#   affirms / reaffirming (subjects)
-#   elects
-#   authorizes
-#   charges
-#   states
-#   remarks
-#   judges
-#   sanctions
-#   abrogates
-#   empowers
-# }

data/lib/edoxen/approval.rb

@@ -1,32 +1,12 @@
 # frozen_string_literal: true
 
-# Approval {
-#   type: ApprovalType
-#   degree: ApprovalDegree
-#   date: Date
-#   message: Text
-# }
-
-# enum ApprovalType {
-#   affirmative
-#   negative
-# }
-
-# enum ApprovalDegree {
-#   unanimous
-#   majority
-#   minority
-# }
-require "lutaml/model"
-
 module Edoxen
+  # Approval record: type (affirmative / negative), degree (consensus level),
+  # date of the approval event, and a human-readable elaboration.
   class Approval < Lutaml::Model::Serializable
-    APPROVAL_TYPE_ENUM = %w[affirmative negative].freeze
-    APPROVAL_DEGREE_ENUM = %w[unanimous majority minority].freeze
-
-    attribute :type, :string, values: APPROVAL_TYPE_ENUM
-    attribute :degree, :string, values: APPROVAL_DEGREE_ENUM
-    attribute :date, :date
+    attribute :type, :string, values: Enums::APPROVAL_TYPE
+    attribute :degree, :string, values: Enums::APPROVAL_DEGREE
+    attribute :date, ResolutionDate
     attribute :message, :string
 
     key_value do