glossarist-ruby

Ruby gem implementing the Glossarist concept model in Ruby. All the entities in the concept model are available as classes and all the attributes are available as methods of those classes. The gem reads and writes Glossarist V2 and V3 datasets, packages them as portable GCR archives, and exports to TBX, SKOS, and Turtle with SHACL validation.

Current version: v2.10.4 — synced to concept-model v3.1.0.

Install

Add this line to your application’s Gemfile:

gem 'glossarist'

And then execute:

bundle install

Or install it yourself as:

gem install glossarist

Usage

Reading a Glossarist model V2/V3 from files

A Glossarist dataset is a collection of concepts and their localizations in YAML, optionally accompanied by a register.yaml (V3 dataset metadata), bibliography.yaml, and dataset-level figures/tables/formulas.

The storage structure has 2 forms:

1. Each concept is stored in a concept YAML file and its localized concepts are stored in separate YAML files. The concept files live in concept/ and localizations in localized_concept/.
2. Each concept and its related localizations are stored in a single YAML file, placed directly in the specified path.

collection = Glossarist::ManagedConceptCollection.new
collection.load_from_files("path/to/glossarist-dataset")

Writing a Glossarist model to files

collection = Glossarist::ManagedConceptCollection.new
collection.load_from_files("path/to/glossarist-dataset")
# ... Update the collection ...
collection.save_to_files("path/to/glossarist-dataset")

To write with concepts and their localizations grouped into single files:

collection.save_grouped_concepts_to_files("path/to/glossarist-dataset")

GCR packages

A GCR (Glossarist Concept Resource) package is a portable ZIP archive of a dataset — concepts, register, bibliography, images, and any pre-compiled machine formats (TBX, JSON-LD, Turtle, JSONL).

collection = Glossarist::ManagedConceptCollection.new
collection.load_from_files("path/to/dataset")

# Write a GCR package
collection.save_to_gcr("my-dataset.gcr")

# Read a GCR package
collection2 = Glossarist::ManagedConceptCollection.new
collection2.load_from_gcr("my-dataset.gcr")

ManagedConcept

concept = Glossarist::ManagedConcept.new({
  "data" => {
    "id" => "123",
    "localized_concepts" => { "ara" => "<uuid>", "eng" => "<uuid>" },
    "localizations" => [...],
    "domains" => [
      Glossarist::ConceptReference.new(concept_id: "103", ref_type: "domain"),
    ],
    "tags" => ["time-scales"],
  },
})

LocalizedConcept

What’s new in 2.8–2.10

Recent releases sync glossarist-ruby to concept-model v3.1.0:

Serialization refactor (v2.10.0)

v2.10.0 removes the last hand-rolled to_h / from_h pairs from the model layer. Attribute mappings now live entirely on the model classes via lutaml-model — wire names, renames, and shape changes are declaration-only. Adding a new wire-name mapping is a one-line map :foo, to: :bar instead of a new branch in a to_h body.

Dataset-level non-verbal RDF (v2.10.4)

The RDF exporter now emits dataset-level gloss:Figure, gloss:Table, and gloss:Formula individuals per the K1 shapes added in concept-model v3.1.0. Previously these were only emitted as concept-level NonVerbRep attachments; the dataset-level identity is now first-class, matching the way the model treats figures/tables/formulas as dataset-owned resources.

Dataset model (v3)

V3 datasets are self-describing — a register.yaml at the root captures identity, URNs, owner, languages, sections, and ordering. The gem reads and writes this structure:

register = Glossarist::Register.from_yaml(File.read("datasets/vim/register.yaml"))
register.sections            # => [#<Section id="1" ...>, ...]
register.sections.first.children  # transitive section tree
register.ordering            # => "systematic"

Sections support transitive cascading membership — a concept placed in section 1.2.3 is automatically a member of 1.2 and 1.

Non-verbal entities (v3.1)

The gem models dataset-level non-verbal entities as first-class resources:

figure = Glossarist::Figure.new(
  id: "quantity-classification",
  caption: { eng: "Classification of quantities" },
  alt: { eng: "Diagram showing the hierarchy of quantity types" },
  images: [{ src: "quantity-classification.svg", format: "svg" }],
)

See Non-verbal entities for the model details.

Reference protocol (v2.9.0)

A shared Reference protocol underpins ConceptReference, RelatedConcept, DesignationRelationship, and other reference-shaped entities — eliminating duplicated logic and ensuring consistent UUID fallback behavior across all reference types.

Per-concept SKOS export + SHACL gate (WS-B)

v2.9.0 introduces per-concept SKOS export with deterministic UUID v5 identifiers (based on dataset URN + concept id) and an optional SHACL validation gate that runs before serialization. This makes round-tripping through SKOS lossless and verifiable.

Links

• GitHub
• RubyGems
• Concept model schemas
• CHANGELOG

See Also

• Concept Model docs — the entity model this gem implements
• Datasets & sections — V3 self-describing dataset model
• Non-verbal entities — figures, tables, formulas
• Standards compliance — ISO standard mappings for TBX, SKOS, and Turtle export