glossarist 2.6.4 → 2.6.6

data/README.adoc

@@ -101,7 +101,7 @@ related:: Array of <<related-concept,RelatedConcept>>
 status:: Enum for the normative status of the term.
 dates:: Array of <<concept-date,ConceptDate>>
 localized_concepts:: Hash of all localizations where keys are language codes and values are uuid of the localized concept.
-groups:: Array of groups in string format
+domains:: Array of <<concept-reference,ConceptReference>> — upper concepts (subject areas, concept schemes, organizing concepts) that this concept belongs to across all languages. Each domain is a typed reference (e.g. `{ concept_id: "103", ref_type: "domain" }`).
 localizations:: Hash of all localizations for this concept where keys are language codes and values are instances of <<localized-concept,LocalizedConcept>>.
 
 There are two ways to initialize and populate a managed concept
@@ -118,9 +118,8 @@ concept = Glossarist::ManagedConcept.new({
       "eng" => "<uuid>"
     },
     "localizations" => <Array of localized concepts or localized concept hashes>,
-    "groups" => [
-      "foo",
-      "bar",
+    "domains" => [
+      { "concept_id" => "103", "ref_type" => "domain" },
     ],
   },
 })
@@ -132,7 +131,9 @@ concept = Glossarist::ManagedConcept.new({
 ----
 concept = Glossarist::ManagedConcept.new
 concept.id = "123"
-concept.groups = ["foo", "bar"]
+concept.data.domains = [
+  Glossarist::ConceptReference.new(concept_id: "103", ref_type: "domain"),
+]
 concept.localizations = <Array of localized concepts or localized concept hashes>
 ----
 
@@ -146,55 +147,252 @@ Localized concept has the following fields
 id:: An optional identifier for the term, to be used in cross-references.
 uuid:: UUID for the concept
 designations:: Array of <<designation,Designations>> under which the term being defined is known. This method will also accept an array of hashes for designation and will convert them to their respective classes.
-domain:: An optional semantic domain for the term being defined, in case the term is ambiguous between several semantic domains.
+domain:: URI reference to the subject area or section concept. Can be a relative URI (e.g. `section-103-01`), a URN (e.g. `urn:iec:std:iec:60050-103-01`), or a URL (e.g. `https://www.electropedia.org/iev/iev.nsf/display?openform&ievref=103-01`). This is the per-language upper concept reference — the subject area for this specific localization. Different languages may assign the same abstract concept to different domains.
+related:: Array of <<related-concept,RelatedConcept>> — per-language concept relationships. Concept hierarchies can differ across languages (e.g. Russian distinguishes голубой/siniy as coordinate basic colors, while English unifies them under "blue"). Language-specific broader/narrower/equivalent relationships go here.
 subject:: Subject of the term.
 definition:: Array of <<detailed-definition,Detailed Definition>> of the term.
 non_verb_rep:: Array of <<non-verbal,non-verbal>> representations used to help define the term.
 notes:: Zero or more notes about the term. A note is in <<detailed-definition,Detailed Definition>> format.
 examples:: Zero or more examples of how the term is to be used in <<detailed-definition,Detailed Definition>> format.
 language_code:: The language of the localization, as an ISO-639 3-letter code.
+script:: The script of the localization, as an ISO 15924 4-letter code (e.g. `Hans` for Simplified Chinese, `Latn` for Latin, `Cyrl` for Cyrillic). Optional — when omitted, the default script for the language is assumed.
+system:: The ISO 24229 conversion system code used to produce this localization (e.g. `Var:jpn-Hrkt:Latn:Hepburn-1886` for Hepburn-romanized Japanese). Optional — only set when the localization is a romanization or transliteration.
 entry_status:: Entry status of the concept. Must be one of the following: +notValid+, +valid+, +superseded+, +retired+.
 classification:: Classification of the concept. Must be one of the following: +preferred+, +admitted+, +deprecated+.
 
 [[id,designation]]
-=== Designation::Base
+=== Designation
+
+A name under which a managed term is known. Designations follow an
+inheritance hierarchy based on ISO 10241-1 and the Metanorma concept model.
+
+==== Designation::Base (common to all types)
+
+designation:: String — the term text or symbol.
+normative_status:: Enum — one of `preferred`, `admitted`, `deprecated`, `superseded`.
+geographical_area:: String — geographic usage region (ISO 3166-1 country code).
+language:: String — language of this designation (ISO 639 code). Usually inherited from the LocalizedConcept's `language_code`, but can differ for borrowed terms.
+script:: String — script of the designation text (ISO 15924 code, e.g. `Hani` for Kanji, `Latn` for Latin, `Cyrl` for Cyrillic).
+system:: String — ISO 24229 conversion system code used to produce this designation (e.g. `Var:jpn-Hrkt:Latn:Hepburn-1886` for Hepburn romanization). Optional — only set when the designation is a romanization or transliteration.
+international:: Boolean — whether the designation is used internationally.
+absent:: Boolean — whether the designation is intentionally absent in this language.
+pronunciation:: Collection of `Pronunciation` entries — phonetic or romanized representations of the designation.
+sources:: Collection of `ConceptSource` entries — bibliographic sources for this designation (ISO 10241-1 §6.8).
+term_type:: Enum (ISO 12620) — optional classification of the designation's term type. See <<iso12620-term-types>> below.
+related:: Collection of `RelatedConcept` entries — term-level (designation-to-designation) relationships within the same concept entry. Used for linking abbreviated forms to full forms, short forms to expanded forms, etc. (TBX xref types).
++
+Each `Pronunciation` entry has:
++
+[cols="1,1,2"]
+|===
+|Attribute |Standard |Description
+
+|`content` |— |The pronunciation text
+|`language` |ISO 639 |Language/dialect being pronounced (3-letter code)
+|`script` |ISO 15924 |Script of the pronunciation text (4-letter code)
+|`country` |ISO 3166-1 |Country variant (2-letter code, optional)
+|`system` |ISO 24229 |Conversion system code or identifier (e.g. `IPA`, `Var:jpn-Hrkt:Latn:Hepburn-1886`)
+|===
++
+Example:
++
+[,yaml]
+----
+pronunciation:
+  - content: "toːkjoː"
+    language: jpn
+    script: Latn
+    system: IPA
+  - content: "Tōkyō"
+    language: jpn
+    script: Latn
+    system: "Var:jpn-Hrkt:Latn:Hepburn-1886"
+----
+
+==== Designation::Expression (text-based, inherits Base)
+
+prefix:: String — text before the designation.
+usage_info:: String — disambiguation text for the designation.
+field_of_application:: String — IEC "specific use", appears in angle brackets after the designation (e.g. "in communication theory").
+grammar_info:: Array of GrammarInfo — gender, number, part of speech.
+
+==== Designation::Abbreviation (inherits Expression)
+
+acronym:: Boolean — is this an acronym?
+initialism:: Boolean — is this an initialism?
+truncation:: Boolean — is this a truncation?
+
+==== Designation::Symbol (inherits Base)
+
+No additional attributes beyond Base.
+
+==== Designation::LetterSymbol (inherits Symbol)
+
+text:: String — the letter symbol text.
 
-A name under which a managed term is known.
+==== Designation::GraphicalSymbol (inherits Symbol)
 
-Methods::
-  `from_h(options)`::: Creates a new designation instance based on the specified type.
+text:: String — description of the symbol.
+image:: String — the graphical symbol (emoji, path, or data URL).
+
+==== Factory Method
+
+`Designation::Base.from_h(options)` creates a new designation instance based on the specified type.
 
 Parameters::
   * options (Hash) - The options for creating the designation.
-  * "type" (String) - The type of designation (expression, symbol, abbreviation, graphical_symbol, letter_symbol). Note: type key should be string and not a symbol so { type: "expression" } will not work.
+  * "type" (String) - The type of designation (`expression`, `symbol`, `abbreviation`, `graphical_symbol`, `letter_symbol`). Note: type key should be string and not a symbol so `{ type: "expression" }` will not work.
   * Additional options depend on the specific designation type.
 
 Returns::
-  Designation::{type}::: A new instance of specified type. e.g `Glossarist::Designation::Base.from_h("type" => "expression")` will return `Glossarist::Designation::Expression`
+  Designation::{type}::: A new instance of specified type.
 
 Example
 [,ruby]
 ----
-# Example usage of Designation::Base class
+# Expression with field of application
+expr = Designation::Base.from_h({
+  "type" => "expression",
+  "designation" => "information",
+  "normative_status" => "preferred",
+  "field_of_application" => "in communication theory",
+})
+
+# International abbreviation
+abbr = Designation::Base.from_h({
+  "type" => "abbreviation",
+  "designation" => "ISO",
+  "international" => true,
+  "acronym" => true,
+})
+----
+
+[[iso12620-term-types]]
+==== ISO 12620 Term Types
+
+The `term_type` attribute on `Designation::Base` classifies designations
+according to ISO 12620 (also used as TBX `termType`). This is orthogonal to
+the structural designation `type` (expression/abbreviation/symbol): the
+structural type determines how the designation is serialized, while
+`term_type` provides ISO 12620 semantic classification.
+
+[cols="1,2"]
+|===
+|Term type |Description
+
+|`abbreviation`
+|A shortened form of a word or phrase (general category)
+
+|`acronym`
+|An abbreviation pronounced as a word (e.g. NATO, laser)
+
+|`clipped_term`
+|A term formed by clipping part of a longer term (e.g. "phone" from "telephone")
+
+|`common_name`
+|A name in common use for a concept (e.g. "water" vs H₂O)
+
+|`entry_term`
+|The headword or main term in a terminological entry
+
+|`equation`
+|A mathematical equation used as a designation
+
+|`formula`
+|A chemical or mathematical formula (e.g. H₂O, E=mc²)
 
-attributes_for_expression = { designation: "foobar", geographical_area: "abc", normative_status: "status" }
-designation_expression = Designation::Base.from_h({ "type" => "expression" }.merge(attributes_for_expression))
+|`full_form`
+|The complete, unabbreviated form of a designation (e.g. "World Wide Web")
 
-attributes_for_abbreviation = { designation: "foobar", geographical_area: "abc", normative_status: "status", international: true }
-designation_abbreviation = Designation::Base.from_h({ "type" => "abbreviation" }.merge(attributes_for_abbreviation))
+|`initialism`
+|An abbreviation pronounced letter by letter (e.g. "URL", "FBI")
 
+|`internationalism`
+|A term used with the same meaning across many languages (e.g. "computer", "algorithm")
+
+|`international_scientific_term`
+|A term established by international scientific agreement (e.g. "hydrogen")
+
+|`logical_expression`
+|A logical or Boolean expression used as a designation
+
+|`part_number`
+|A part number or catalog identifier used as a designation
+
+|`phraseological_unit`
+|A multi-word expression or phrase functioning as a term (e.g. "software engineering")
+
+|`transcribed_form`
+|A designation produced by phonetic transcription from another script
+
+|`transliterated_form`
+|A designation produced by transliteration from another script (e.g. "Moskva" from "Москва")
+
+|`short_form`
+|A shortened form of a designation that is not an abbreviation (e.g. "US" for "United States")
+
+|`shortcut`
+|A keyboard shortcut or command sequence (e.g. "Ctrl+V" for paste)
+
+|`sku`
+|A stock keeping unit identifier
+
+|`standard_text`
+|A standardized text passage used as a designation
+
+|`symbol`
+|A non-verbal symbol representing the concept (e.g. Ω for ohm)
+
+|`synonym`
+|A term with the same meaning in the same language, used as an alternative designation
+
+|`synonymous_phrase`
+|A phrase that is synonymous with the preferred designation
+
+|`variant`
+|A spelling, regional, or stylistic variant of another designation
+|===
+
+==== Designation-Level Relationships (TBX xref)
+
+Designations can have intra-entry relationships — links between
+designations of the *same* concept. These correspond to TBX `xref`
+elements on term information groups (`<tig>`).
+
+[cols="1,2"]
+|===
+|Relationship type |Description
+
+|`abbreviated_form_for`
+|This designation is an abbreviated form of the target (e.g. "WWW" → "World Wide Web")
+
+|`short_form_for`
+|This designation is a short form of the target (e.g. "US" → "United States of America")
+|===
+
+Example:
+[,yaml]
+----
+terms:
+  - designation: WWW
+    type: abbreviation
+    term_type: acronym
+    related:
+      - type: abbreviated_form_for
+        content: "World Wide Web"
+  - designation: World Wide Web
+    type: expression
+    term_type: full_form
 ----
 
 [[id,related-concept]]
 === RelatedConcept
 
-A term related to the current term.
-
-Following fields are available for the Related Concept
+A concept related to the current concept with a typed relationship.
 
-type:: An enum to denote the relation of the term to the current term.
-content:: The designation of the related term.
-ref:: A <<citation, citation>> of the related term, in a Termbase.
+type:: Enum — the relationship type (see <<relationship-types,Relationship Types>> below).
+content:: String — free-text content describing the related concept.
+ref:: A <<citation,Citation>> reference to the related concept.
 
 There are two ways to initialize and populate a related concept
 
@@ -219,6 +417,208 @@ related_concept.content = "designation of the related concept"
 related_concept.ref = <Citation object>
 ----
 
+[[relationship-types]]
+==== Relationship Types
+
+Relationship types are drawn from ISO 10241-1, ISO 25964/SKOS, and ISO 12620/TBX. The table below shows each type with its provenance and cross-standard equivalents.
+
+[cols="1,1,1,1,1"]
+|===
+|Glossarist type |Category |ISO 10241-1 |ISO 25964 / SKOS |ISO 12620 / TBX
+
+|`deprecates`
+|Lifecycle
+|deprecates
+|—
+|—
+
+|`supersedes`
+|Lifecycle
+|supersedes
+|—
+|—
+
+|`superseded_by`
+|Lifecycle
+|superseded by
+|—
+|—
+
+|`broader`
+|Hierarchical
+|broader concept
+|BT (broaderTerm)
+|broaderTerm
+
+|`narrower`
+|Hierarchical
+|narrower concept
+|NT (narrowerTerm)
+|narrowerTerm
+
+|`broader_generic`
+|Hierarchical (generic)
+|—
+|BTG (broaderGeneric, is-a)
+|broaderTermGeneric
+
+|`narrower_generic`
+|Hierarchical (generic)
+|—
+|NTG (narrowerGeneric)
+|narrowerTermGeneric
+
+|`broader_partitive`
+|Hierarchical (partitive)
+|—
+|BTP (broaderPartitive, part-whole)
+|broaderTermPartitive
+
+|`narrower_partitive`
+|Hierarchical (partitive)
+|—
+|NTP (narrowerPartitive)
+|narrowerTermPartitive
+
+|`broader_instantial`
+|Hierarchical (instantial)
+|—
+|BTI (broaderInstantial, instance-of)
+|broaderTermInstantial
+
+|`narrower_instantial`
+|Hierarchical (instantial)
+|—
+|NTI (narrowerInstantial)
+|narrowerTermInstantial
+
+|`equivalent`
+|Equivalence
+|equivalent
+|exactMatch
+|—
+
+|`close_match`
+|Approx. equiv.
+|—
+|closeMatch
+|—
+
+|`broad_match`
+|Cross-vocab mapping
+|—
+|broadMatch
+|—
+
+|`narrow_match`
+|Cross-vocab mapping
+|—
+|narrowMatch
+|—
+
+|`related_match`
+|Cross-vocab mapping
+|—
+|relatedMatch
+|—
+
+|`compare`
+|Comparative
+|compare
+|—
+|—
+
+|`contrast`
+|Comparative
+|contrast
+|—
+|—
+
+|`see`
+|Associative
+|see also
+|RT (relatedTerm)
+|crossReference
+
+|`related_concept`
+|Associative
+|—
+|—
+|relatedConcept
+
+|`related_concept_broader`
+|Associative (broader)
+|—
+|—
+|relatedConceptBroader
+
+|`related_concept_narrower`
+|Associative (narrower)
+|—
+|—
+|relatedConceptNarrower
+
+|`sequentially_related_concept`
+|Associative (sequential)
+|—
+|—
+|sequentiallyRelatedConcept
+
+|`spatially_related_concept`
+|Associative (spatial)
+|—
+|—
+|spatiallyRelatedConcept
+
+|`temporally_related_concept`
+|Associative (temporal)
+|—
+|—
+|temporallyRelatedConcept
+
+|`homograph`
+|Lexical
+|—
+|—
+|homograph
+
+|`false_friend`
+|Lexical
+|—
+|—
+|falseFriend
+|===
+
+[[id,concept-reference]]
+=== ConceptReference
+
+A typed reference to another concept, either local (within the same glossary) or external (in another concept registry).
+
+term:: String — the display text for the referenced concept.
+concept_id:: String — the identifier of the target concept.
+source:: String — the registry URI prefix for external references (e.g. `urn:iec:std:iec:60050`).
+ref_type:: String — the reference type: `local`, `designation`, or `urn`.
+urn:: String — a direct URN for the target concept (e.g. `urn:iec:std:iec:60050-102-01-01`).
+
+Local references use `concept_id` without `source`. External references use `source` + `concept_id` or a direct `urn`.
+
+[,ruby]
+----
+# Local reference
+ref = Glossarist::ConceptReference.new(term: "latitude", concept_id: "200", ref_type: "local")
+
+# External reference via URN
+ref = Glossarist::ConceptReference.new(
+  term: "equality",
+  concept_id: "102-01-01",
+  source: "urn:iec:std:iec:60050",
+  ref_type: "urn",
+)
+
+ref.local?    # => false
+ref.external? # => true
+----
+
 [[id,concept-date]]
 === Concept Date
 
@@ -324,12 +724,27 @@ citation.clause = "some clause"
 
 === NonVerbRep
 
-Non-verbal Representation have the following fields
+Non-verbal representations are associated resources (images, tables, formulas) used to help define a concept (ISO 10241-1 §6.5). They live outside the concept model and are referenced by URI. Resources can be shared across concepts and belong either to the dataset package (relative path) or are externally referenced (URL/URN).
+
+type:: String — the type of representation: `image`, `table`, or `formula`.
+ref:: String — URI reference to the resource (relative path within the GCR package, URN, or URL).
+text:: String — optional text description or alt text.
+sources:: Collection of <<concept-source,ConceptSource>> entries — bibliographic sources for the representation.
 
-image:: An image used to help define a term.
-table:: A table used to help define a term.
-formula:: A formula used to help define a term.
-sources:: Bibliographic <<concept-source,concept source>> for the non-verbal representation of the term.
+Example:
++
+[,yaml]
+----
+non_verbal_rep:
+  - type: image
+    ref: assets/images/figure-1.svg
+    text: Diagram showing the concept hierarchy
+  - type: formula
+    ref: urn:gcr:assets:formula-eq1
+    sources:
+      - type: authoritative
+        status: identical
+----
 
 [[id,concept-source]]
 === ConceptSource
@@ -626,12 +1041,14 @@ skipped_count:: `Integer` — concepts skipped due to duplicates (strategy: skip
 
 === validate
 
-Validate a dataset directory or `.gcr` file for schema compliance.
+Validate a dataset directory or `.gcr` file for schema compliance, structural
+integrity, cross-reference resolution, and data quality.
 
 [,bash]
 ----
 glossarist validate PATH
 glossarist validate PATH --reference-path path/to/gcrs/
+glossarist validate PATH --strict
 ----
 
 Options:
@@ -657,6 +1074,210 @@ result.errors   # => [...]
 result.warnings # => [...]
 ----
 
+== Validation System
+
+Glossarist provides a rule-based validation framework that checks dataset
+directories and GCR packages for structural, schema, reference, integrity,
+quality, and localization issues.
+
+=== Architecture
+
+The validation system uses the **rule-registry pattern** (Open/Closed
+Principle). Each check is a self-describing rule class that subclasses
+`Glossarist::Validation::Rules::Base`. New rules are added by subclassing and
+registering — no existing code is modified.
+
+```
+Glossarist::Validation
+├── Rules
+│   ├── Base                    # Abstract rule: code, category, severity, scope, check
+│   ├── Registry                # Global registry: register, all, for_category, for_scope
+│   ├── DatasetContext          # Lazy-loaded access to a directory dataset
+│   ├── GcrContext              # Lazy-loaded access to a .gcr package
+│   └── (26 rule classes)      # One file per rule
+├── ValidationIssue             # Single finding: severity, code, message, location, suggestion
+├── BibliographyIndex           # Index of bibliography anchors from sources + bibliography.yaml
+├── AssetIndex                  # Index of asset paths from images/ directory or GCR ZIP
+├── ConceptValidator            # Orchestrator: runs per-concept rules
+├── GcrValidator                # Orchestrator: runs GCR-level rules
+└── DatasetValidator            # Orchestrator: runs directory-level + collection rules
+```
+
+=== Rule Categories
+
+Rules are classified into six MECE (Mutually Exclusive, Collectively
+Exhaustive) categories:
+
+[cols="1,2"]
+|===
+|Category |What it checks
+
+|`structure` |File/directory layout, ZIP contents, required parts
+|`schema` |Field types, enum values, required fields, YAML syntax
+|`references` |Cross-references between concepts, bibliography, assets
+|`integrity` |Metadata vs. reality, filename vs. ID, UUID cross-references
+|`quality` |Empty content, missing preferred terms, duplicate terms
+|`localization` |Language coverage, orphaned/missing localization files
+|===
+
+=== Built-in Rules
+
+The following rules are registered by default. Each rule has a unique code
+(e.g. `GLS-001`), a severity (`error` or `warning`), and a scope (`:concept`
+for per-concept checks or `:collection` for dataset-wide checks).
+
+==== Structure Rules
+
+[cols="1,2,1,1"]
+|===
+|Code |Rule |Severity |Scope
+
+|GLS-001 |Concept ID is present |error |`:concept`
+|GLS-002 |At least one localization per concept |error |`:concept`
+|GLS-005 |Each localization has at least 1 term |error |`:concept`
+|GLS-020-YAML |bibliography.yaml is valid YAML |error |`:collection`
+|===
+
+==== Schema Rules
+
+[cols="1,2,1,1"]
+|===
+|Code |Rule |Severity |Scope
+
+|GLS-003 |Entry status is a valid enum value |error |`:concept`
+|GLS-201 |Concept status is a valid enum value |error |`:concept`
+|GLS-202/203 |Source type and status are valid enums |error |`:concept`
+|GLS-200 |Related concept type is valid |error |`:concept`
+|GLS-204 |Designation normative_status is valid |error |`:concept`
+|GLS-205 |Date type is a valid enum |warning |`:concept`
+|GLS-206 |Language code is exactly 3 lowercase letters |error |`:concept`
+|GLS-207 |Designation type maps to a known subclass |error |`:concept`
+|===
+
+==== Reference Rules
+
+[cols="1,2,1,1"]
+|===
+|Code |Rule |Severity |Scope
+
+|GLS-100 |`{{...}}` concept mentions resolve locally |warning |`:concept`
+|GLS-102 |`<<anchor>>` AsciiDoc xrefs resolve in bibliography index |warning |`:concept`
+|GLS-103-105 |Image references resolve in asset index |warning |`:concept`
+|GLS-110 |Related concept references resolve |warning |`:concept`
+|GLS-020 |Orphaned bibliography entries |warning |`:collection`
+|GLS-021 |Orphaned images |warning |`:collection`
+|GLS-112 |Supersedes/superseded_by symmetry check |warning |`:collection`
+|GLS-113 |No circular related-concept chains |error |`:collection`
+|===
+
+==== Integrity Rules
+
+[cols="1,2,1,1"]
+|===
+|Code |Rule |Severity |Scope
+
+|GLS-001-U |Concept IDs are unique |error |`:collection`
+|GLS-011 |Concept count matches metadata |error |`:collection`
+|GLS-012 |Language list matches actual languages |warning |`:collection`
+|GLS-013 |Language coverage per concept |warning |`:concept`
+|GLS-015 |Filename matches concept ID (GCR) |error |`:concept`
+|GLS-016 |Concept URI is set or template is applicable |warning |`:collection`
+|GLS-018 |Localized concept UUID cross-references resolve |error |`:concept`
+|GLS-019 |Orphaned localization files |warning |`:collection`
+|===
+
+==== Quality Rules
+
+[cols="1,2,1,1"]
+|===
+|Code |Rule |Severity |Scope
+
+|GLS-300 |Definition content is non-empty |warning |`:concept`
+|GLS-301 |At least one preferred designation per localization |warning |`:concept`
+|GLS-302 |No duplicate preferred terms within a language |warning |`:collection`
+|GLS-304 |Source citation is not empty |warning |`:concept`
+|GLS-306 |At least one authoritative source |warning |`:concept`
+|GLS-307 |Date values are parseable |warning |`:concept`
+|===
+
+=== Cross-Reference Validation
+
+The validation system checks that all references in concept content point to
+resources that actually exist:
+
+* **Bibliographic cross-references** — AsciiDoc `<<anchor>>` xrefs are checked
+  against a `BibliographyIndex` built from all `ConceptSource` entries and
+  optional `bibliography.yaml`.
+* **Image/asset references** — `image::path[]` references and model-level asset
+  paths (`NonVerbRep`, `GraphicalSymbol`) are checked against an `AssetIndex`
+  built from the `images/` directory or GCR ZIP entries.
+* **Inter-concept references** — `{{...}}` concept mentions are checked against
+  the concept collection for local references, and against registered GCR
+  packages for inter-set URN references.
+
+=== Validation Result
+
+`ValidationResult` holds the aggregated findings from all rules:
+
+[,ruby]
+----
+result = DatasetValidator.new.validate("path/to/dataset")
+result.valid?    # => true if no errors
+result.errors    # => Array of error strings
+result.warnings  # => Array of warning strings
+result.issues    # => Array of ValidationIssue objects (full detail)
+----
+
+Each `ValidationIssue` carries structured metadata:
+
+[,ruby]
+----
+issue = result.issues.first
+issue.severity   # => "error" or "warning"
+issue.code       # => "GLS-300"
+issue.message    # => "definition 1 has empty content"
+issue.location   # => "concepts/100.yaml/eng"
+issue.suggestion # => "Add definition text or remove the empty entry"
+issue.to_s       # => "[ERROR] [GLS-300] concepts/100.yaml/eng: definition 1 has empty content"
+----
+
+=== Adding Custom Rules
+
+New validation rules are added by subclassing `Base` and registering with the
+global `Registry`. This extends validation without modifying existing code:
+
+[,ruby]
+----
+class MyCustomRule < Glossarist::Validation::Rules::Base
+  def code = "CUSTOM-001"
+  def category = :quality
+  def severity = "warning"
+  def scope = :concept
+
+  def applicable?(context)
+    context.concept&.localizations&.any?
+  end
+
+  def check(context)
+    issues = []
+    context.concept.localizations.each do |l10n|
+      # ... your check logic ...
+      if some_condition
+        issues << issue("something is wrong",
+          location: context.file_name,
+          suggestion: "how to fix it")
+      end
+    end
+    issues
+  end
+end
+
+Glossarist::Validation::Rules::Registry.register(MyCustomRule)
+----
+
+Custom rules are automatically picked up by `DatasetValidator`, `GcrValidator`,
+and `ConceptValidator` on the next validation run.
+
 === upgrade
 
 Upgrade a dataset to the current schema version.