tbx 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6cd7e3da852ba1088c29f3c06a56d8d0240fd8632ac7c6169b945f72dd766827
-  data.tar.gz: 82bf5dda948c2a43cf44d2486bb7df0e9dec692ac5ff8c447376123a52421faa
+  metadata.gz: 29c3d165460b14222b4af24f6c56d95f78dd8703f1bf00c78fab244586434be2
+  data.tar.gz: 64b7c19adc52c2e1d56d76369123601ff7d34ffc498e77ffe2465a7d1a2a546d
 SHA512:
-  metadata.gz: 59d1714c344246929539249855a85656997cb94f685dfd050940ba4edc6c62e09fee8068962ad98fbc97c26221f4ec8fd5be6004fcad396ab0b83bdf18cff1aa
-  data.tar.gz: 6c391a5e86fa7f6721b766535a9ab51060b760e88113e6a4fb6072fe58240add5138bdaef5d3e97656a6e6d5321d20b532cc66c4039049d4bf896dfb89730dd4
+  metadata.gz: 0b281377ea442217305e63c273d12def6a674b9c5b168a2f3556eb3d60b3f728fee78e81eed78784ed1592b32f1f62332f2bf748e866d45e85cf3f04ed76c175
+  data.tar.gz: fc068eaeab6a216594c07e630ae9d902bb35e75ab579f2469643d84506afcc59117d83cee7105756f051e12f7a9dece4e57fee48fcecf8e65680a7520255f2d1

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-05-05 13:10:07 UTC using RuboCop version 1.86.1.
+# on 2026-05-05 23:57:36 UTC using RuboCop version 1.86.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new

data/CHANGELOG.md

@@ -1,5 +1,37 @@
 ## [Unreleased]
 
+### Added
+
+- `Tbx::DataElement` shared concern — DRY module injecting common data-category
+  attributes (id, lang, target, datatype, type, content) via `included` hook
+- `Tbx::DataElement::InlineContent` sub-concern for elements with `entity.noteText`
+  content model (hi, ec, foreign, ph, sc inline children)
+- `Tbx::Modules::Min` — Min module TYPES/VALUES constants (Min.tbxmd)
+- `Tbx::Modules::Basic` — Basic module TYPES/VALUES constants (Basic.tbxmd)
+- `Tbx::Modules::Linguist` — Linguist module TYPES/VALUES constants (Linguist.tbxmd)
+- `Tbx::Modules::CoreTypes` — Core RNG hi type constants
+- TYPES constants on all data-category elements (Admin, AdminNote, Descrip,
+  TermNote, Ref, Xref, Transac, TransacNote, Hi), composed from module hashes
+- VALUES constants on TermNote (picklist enums) and Transac (transaction types)
+- `Tbx::TermComp` — term component element `<termComp>` (TermComp module)
+- `Tbx::TermCompGrp` — term component group `<termCompGrp>` (TermComp module)
+- `Tbx::TermCompSec` — term component section `<termCompSec>` (TermComp module)
+  with TYPES for 5 decomposition methods
+- Comprehensive YARD RubyDoc on all element classes tracing schema/module sources
+- 119 new specs (165 total) covering TYPES/VALUES, DataElement concern, and
+  XML round-trips for all data-category elements and TermComp elements
+
+### Changed
+
+- Data-category elements (Admin, Descrip, TermNote, AdminNote, DescripNote,
+  TransacNote, Transac, Ref) now use `include Tbx::DataElement` instead of
+  explicit attribute declarations
+- `Tbx::TermNote::TYPES` now composes from Min + Basic + Linguist (9 types)
+- `Tbx::Sc` aligned with core RNG: removed type, subtype, target attributes
+  (only id and isolated per RNG)
+- Reference documentation downloaded from 12 LTAC-Global repositories into
+  `reference-docs/schemas/` with acknowledgements
+
 ## [0.1.1] - 2026-05-05
 
 - Simplify `Tbx::Namespaces::TbxNamespace` to `Tbx::Namespace`

data/CLAUDE.md

@@ -45,6 +45,9 @@ Tbx
 ├── LangSec          # <langSec>
 ├── TermSec          # <termSec>
 ├── Term             # <term>
+├── TermComp         # <termComp> (TermComp module)
+├── TermCompGrp      # <termCompGrp> (TermComp module)
+├── TermCompSec      # <termCompSec> (TermComp module)
 ├── TermNote         # <termNote>
 ├── TermNoteGrp      # <termNoteGrp>
 ├── Descrip          # <descrip>
@@ -72,7 +75,13 @@ Tbx
 ├── Sc               # <sc>
 ├── Ph               # <ph>
 ├── Title            # <title>
-└── Namespace         # XML namespace definition (urn:iso:std:iso:30042:ed-2)
+├── DataElement      # Shared concern for data-category elements
+├── Namespace        # XML namespace (urn:iso:std:iso:30042:ed-2)
+└── Modules
+    ├── Min          # Min module TYPES/VALUES
+    ├── Basic        # Basic module TYPES/VALUES
+    ├── Linguist     # Linguist module TYPES/VALUES
+    └── CoreTypes    # Core RNG hi types
 ```
 
 ### Key Implementation Patterns
@@ -105,6 +114,17 @@ end
 
 **Autoload Pattern**: Elements are autoloaded via `lib/tbx.rb`. When adding new elements, add autoloads in alphabetical order.
 
+**DataElement Concern** (`lib/tbx/data_element.rb`):
+- `Tbx::DataElement` — injects shared attributes (id, lang, target, datatype, type, content) via `self.included(base)` hook
+- `Tbx::DataElement::InlineContent` — adds inline child attributes (hi, ec, foreign, ph, sc) for elements with `entity.noteText` content
+- XML mappings remain explicit per class (lutaml-model's `xml do` uses `instance_eval` on a separate context)
+- Included by: Admin, Descrip, TermNote (with InlineContent); AdminNote, DescripNote, TransacNote, Transac, Ref (without)
+
+**Module TYPES/VALUES** (`lib/tbx/modules/`):
+- Each module defines `*_TYPES` and `*_VALUES` hashes keyed by Ruby symbol, valued by TBX string
+- Element classes compose TYPES via `merge` from all applicable modules (e.g., `TermNote::TYPES` merges Min + Basic + Linguist)
+- Source: Min.tbxmd, Basic.tbxmd, Linguist.tbxmd, TBXcoreStructV03.rng
+
 ### XML Namespace
 
 The TBX namespace is `urn:iso:std:iso:30042:ed-2` defined in `Tbx::Namespace`.

data/README.adoc

@@ -89,44 +89,386 @@ tbx.to_xml
 tbx.to_xml(pretty: true, declaration: true, encoding: "utf-8")
 ----
 
-=== Supported TBX elements
+=== Using TYPES and VALUES constants
 
-==== Root and structure
+Each data-category element class exposes `TYPES` (permitted `@type` values)
+and `VALUES` (permitted picklist values) constants composed from the
+TBX module definitions:
 
-`Document` (`<tbx>`), `TbxHeader`, `TextElement`, `Body`, `Back`
+[source,ruby]
+----
+# Permitted termNote types across all modules
+Tbx::TermNote::TYPES
+# => { administrative_status: "administrativeStatus", part_of_speech: "partOfSpeech",
+#      geographical_usage: "geographicalUsage", grammatical_gender: "grammaticalGender",
+#      term_location: "termLocation", term_type: "termType",
+#      grammatical_number: "grammaticalNumber", register: "register",
+#      transfer_comment: "transferComment" }
+
+# Picklist values for a specific type
+Tbx::TermNote::VALUES[:grammatical_gender]
+# => { masculine: "masculine", feminine: "feminine", neuter: "neuter", other: "other" }
+
+# Admin types from all modules
+Tbx::Admin::TYPES
+# => { customer_subset: "customerSubset", project_subset: "projectSubset",
+#      source: "source", reading: "reading" }
+
+# Descrip types
+Tbx::Descrip::TYPES
+# => { subject_field: "subjectField", context: "context", definition: "definition" }
+
+# Hi types from core RNG
+Tbx::Hi::TYPES
+# => { entailed_term: "entailedTerm", hotkey: "hotkey", italics: "italics",
+#      bold: "bold", superscript: "superscript", subscript: "subscript", math: "math" }
+
+# Create validated elements using constants
+note = Tbx::TermNote.new(
+  type: Tbx::TermNote::TYPES[:part_of_speech],
+  content: [Tbx::TermNote::VALUES[:part_of_speech][:noun]],
+)
+----
+
+== Supported TBX elements
+
+=== Structural elements (TBXcoreStructV03.rng)
+
+[cols="2,3,3",options="header"]
+|===
+| Ruby class | TBX element | Schema source
+
+| `Tbx::Document` | `<tbx>` | Core RNG `<define name="tbx">`
+| `Tbx::TbxHeader` | `<tbxHeader>` | Core RNG `<define name="tbxHeader">`
+| `Tbx::TextElement` | `<text>` | Core RNG `<define name="text">`
+| `Tbx::Body` | `<body>` | Core RNG `<define name="body">`
+| `Tbx::Back` | `<back>` | Core RNG `<define name="back">`
+| `Tbx::ConceptEntry` | `<conceptEntry>` | Core RNG `<define name="conceptEntry">`
+| `Tbx::LangSec` | `<langSec>` | Core RNG `<define name="langSec">`
+| `Tbx::TermSec` | `<termSec>` | Core RNG `<define name="termSec">`
+| `Tbx::Term` | `<term>` | Core RNG `<define name="term">`
+|===
+
+=== Header elements (TBXcoreStructV03.rng)
+
+[cols="2,3,3",options="header"]
+|===
+| Ruby class | TBX element | Schema source
+
+| `Tbx::FileDesc` | `<fileDesc>` | Core RNG `<define name="fileDesc">`
+| `Tbx::PublicationStmt` | `<publicationStmt>` | Core RNG `<define name="publicationStmt">`
+| `Tbx::TitleStmt` | `<titleStmt>` | Core RNG `<define name="titleStmt">`
+| `Tbx::SourceDesc` | `<sourceDesc>` | Core RNG `<define name="sourceDesc">`
+| `Tbx::EncodingDesc` | `<encodingDesc>` | Core RNG `<define name="encodingDesc">`
+| `Tbx::RevisionDesc` | `<revisionDesc>` | Core RNG `<define name="revisionDesc">`
+| `Tbx::Change` | `<change>` | Core RNG `<define name="change">`
+| `Tbx::Title` | `<title>` | Core RNG `<define name="title">`
+|===
+
+=== Data category elements with TYPES constants
+
+These elements carry a `type` attribute whose permitted values are defined
+by the active TBX module composition. The `TYPES` constant on each class
+contains the union of all applicable module types.
+
+==== Admin element
+
+[cols="1,2,2,3",options="header"]
+|===
+| Module | Type value | Content | Source
+
+| Min | `customerSubset` | string | Min.tbxmd (DC-165)
+| Basic | `projectSubset` | string | Basic.tbxmd (DC-406)
+| Basic | `source` | string | Basic.tbxmd (DC-471)
+| Linguist | `reading` | string | Linguist.tbxmd
+|===
+
+==== AdminNote element
+
+[cols="1,2,2,3",options="header"]
+|===
+| Module | Type value | Content | Source
+
+| Linguist | `readingNote` | noteText | Linguist.tbxmd
+|===
+
+==== Descrip element
+
+[cols="1,2,2,3",options="header"]
+|===
+| Module | Type value | Content | Source
+
+| Min | `subjectField` | string | Min.tbxmd (DC-489)
+| Basic | `context` | noteText | Basic.tbxmd (DC-149)
+| Basic | `definition` | noteText | Basic.tbxmd (DC-168)
+|===
+
+==== TermNote element
+
+[cols="1,2,2,3",options="header"]
+|===
+| Module | Type value | Content | Source
+
+| Min | `administrativeStatus` | picklist footnote:[admittedTerm-admn-sts, deprecatedTerm-admn-sts, supersededTerm-admn-sts, preferredTerm-admn-sts] | Min.tbxmd (DC-168)
+| Min | `partOfSpeech` | picklist footnote:[adjective, noun, other, verb, adverb] | Min.tbxmd (DC-396)
+| Basic | `geographicalUsage` | string | Basic.tbxmd (DC-243)
+| Basic | `grammaticalGender` | picklist footnote:[masculine, feminine, neuter, other] | Basic.tbxmd (DC-245)
+| Basic | `termLocation` | picklist footnote:[18 UI element types: checkBox, comboBox, comboBoxElement, dialogBox, groupBox, informativeMessage, interactiveMessage, menuItem, progressBar, pushButton, radioButton, slider, spinBox, tab, tableText, textBox, toolTip, user-definedType] | Basic.tbxmd (DC-1823)
+| Basic | `termType` | picklist footnote:[fullForm, acronym, abbreviation, shortForm, variant, phrase] | Basic.tbxmd (DC-2677)
+| Linguist | `grammaticalNumber` | picklist footnote:[singular, plural, dual, mass, otherNumber] | Linguist.tbxmd (DC-251)
+| Linguist | `register` | picklist footnote:[colloquialRegister, neutralRegister, technicalRegister, in-houseRegister, bench-levelRegister, slangRegister, vulgarRegister] | Linguist.tbxmd (DC-423)
+| Linguist | `transferComment` | string | Linguist.tbxmd (DC-520)
+|===
 
-==== Terminological entries
+==== Transac element
 
-`ConceptEntry`, `LangSec`, `TermSec`, `Term`
+[cols="1,2,2,3",options="header"]
+|===
+| Module | Type value | Values | Source
 
-==== Data categories
+| Basic | `transactionType` | picklist footnote:[origination, modification] | Basic.tbxmd (DC-1689)
+|===
+
+==== TransacNote element
+
+[cols="1,2,2,3",options="header"]
+|===
+| Module | Type value | Content | Source
+
+| Basic | `responsibility` | string | Basic.tbxmd (DC-451)
+|===
 
-`Admin`, `AdminGrp`, `AdminNote`, `Descrip`, `DescripGrp`, `DescripNote`,
-`TermNote`, `TermNoteGrp`, `Ref`, `Xref`
+==== Ref element
+
+[cols="1,2,2,3",options="header"]
+|===
+| Module | Type value | Content | Source
 
-==== Transactions
+| Basic | `crossReference` | string | Basic.tbxmd (DC-164)
+|===
 
-`Transac`, `TransacGrp`, `TransacNote`, `DateElement`
+==== Xref element
 
-==== Header
+[cols="1,2,2,3",options="header"]
+|===
+| Module | Type value | Content | Source
 
-`FileDesc`, `PublicationStmt`, `TitleStmt`, `SourceDesc`, `EncodingDesc`,
-`RevisionDesc`, `Change`
+| Min | `externalCrossReference` | string | TBX-Min DCA Schematron
+| Basic | `externalCrossReference` | string | Basic.tbxmd (DC-226)
+| Basic | `xGraphic` | string | Basic.tbxmd (DC-2920)
+|===
 
-==== Reference objects
+==== Hi element (core RNG, not module-specific)
 
-`RefObjectSec`, `RefObject`, `ItemSet`, `ItemGrp`, `Item`
+[cols="2,3",options="header"]
+|===
+| Type value | Description
 
-==== Inline
+| `entailedTerm` | Cross-reference to another concept within term text
+| `hotkey` | Keyboard shortcut designation
+| `italics` | Italic text emphasis
+| `bold` | Bold text emphasis
+| `superscript` | Superscript text
+| `subscript` | Subscript text
+| `math` | Mathematical notation
+|===
 
-`Hi`, `Foreign`, `Ec`, `Sc`, `Ph`, `Note`, `P`, `Title`
+=== Grouping elements (TBXcoreStructV03.rng)
+
+[cols="2,3,3",options="header"]
+|===
+| Ruby class | TBX element | Schema source
+
+| `Tbx::AdminGrp` | `<adminGrp>` | Core RNG `<define name="adminGrp">`
+| `Tbx::DescripGrp` | `<descripGrp>` | Core RNG `<define name="descripGrp">`
+| `Tbx::DescripNote` | `<descripNote>` | Core RNG `<define name="descripNote">`
+| `Tbx::TermNoteGrp` | `<termNoteGrp>` | Core RNG `<define name="termNoteGrp">`
+| `Tbx::TransacGrp` | `<transacGrp>` | Core RNG `<define name="transacGrp">`
+| `Tbx::TransacNote` | `<transacNote>` | Core RNG `<define name="transacNote">`
+| `Tbx::DateElement` | `<date>` | Core RNG `<define name="date">`
+|===
+
+=== TermComp elements (TermComp-namespace.rng)
+
+[cols="2,3,3",options="header"]
+|===
+| Ruby class | TBX element | Schema source
+
+| `Tbx::TermCompSec` | `<termCompSec>` | TermComp-namespace.rng `<define name="termCompSec">`
+| `Tbx::TermCompGrp` | `<termCompGrp>` | TermComp-namespace.rng `<define name="termCompGrp">`
+| `Tbx::TermComp` | `<termComp>` | TermComp-namespace.rng `<define name="termComp">`
+|===
+
+`Tbx::TermCompSec::TYPES` defines 5 decomposition types:
+`hyphenation`, `lemma`, `morphologicalElement`, `syllabification`, `termElement`.
+
+=== Reference object elements (TBXcoreStructV03.rng)
+
+[cols="2,3,3",options="header"]
+|===
+| Ruby class | TBX element | Schema source
+
+| `Tbx::RefObjectSec` | `<refObjectSec>` | Core RNG `<define name="refObjectSec">`
+| `Tbx::RefObject` | `<refObject>` | Core RNG `<define name="refObject">`
+| `Tbx::ItemSet` | `<itemSet>` | Core RNG `<define name="itemSet">`
+| `Tbx::ItemGrp` | `<itemGrp>` | Core RNG `<define name="itemGrp">`
+| `Tbx::Item` | `<item>` | Core RNG `<define name="item">`
+|===
+
+=== Inline and text elements (TBXcoreStructV03.rng)
+
+[cols="2,3,3",options="header"]
+|===
+| Ruby class | TBX element | Schema source
+
+| `Tbx::Hi` | `<hi>` | Core RNG `<define name="hi">`
+| `Tbx::Foreign` | `<foreign>` | Core RNG `<define name="foreign">`
+| `Tbx::Ec` | `<ec>` | Core RNG `<define name="ec">`
+| `Tbx::Sc` | `<sc>` | Core RNG `<define name="sc">`
+| `Tbx::Ph` | `<ph>` | Core RNG `<define name="ph">`
+| `Tbx::Note` | `<note>` | Core RNG `<define name="note">`
+| `Tbx::P` | `<p>` | Core RNG `<define name="p">`
+|===
+
+== Module architecture
+
+TBX modules define sets of data categories. Dialects compose modules to
+determine which `@type` values are permitted on each element.
+
+=== Modules and dialects
+
+[cols="1,4,3",options="header"]
+|===
+| Module | Dialects that include it | Source files
+
+| Min | TBX-Min, TBX-Basic, TBX-Core, TBX-Linguist | `Min.tbxmd`, `Min.rng`, `Min.sch`
+| Basic | TBX-Basic, TBX-Linguist | `Basic.tbxmd`, `Basic.rng`, `Basic.sch`
+| Linguist | TBX-Linguist | `Linguist.tbxmd`, `Linguist.rng`, `Linguist.sch`
+| TermComp | (add-on for any dialect) | `TermComp-namespace.rng`
+| Core | TBX-Core | `TBXcoreStructV03.rng`
+|===
+
+=== Ruby module constants
+
+[cols="2,3,5",options="header"]
+|===
+| Ruby module | Constants | Source schema
+
+| `Tbx::Modules::Min` | `ADMIN_TYPES`, `DESCRIP_TYPES`, `TERM_NOTE_TYPES`, `TERM_NOTE_VALUES`, `XREF_TYPES` | Min.tbxmd
+| `Tbx::Modules::Basic` | `ADMIN_TYPES`, `DESCRIP_TYPES`, `TERM_NOTE_TYPES`, `TERM_NOTE_VALUES`, `REF_TYPES`, `XREF_TYPES`, `TRANSAC_TYPES`, `TRANSAC_VALUES`, `TRANSAC_NOTE_TYPES` | Basic.tbxmd
+| `Tbx::Modules::Linguist` | `ADMIN_TYPES`, `ADMIN_NOTE_TYPES`, `TERM_NOTE_TYPES`, `TERM_NOTE_VALUES` | Linguist.tbxmd
+| `Tbx::Modules::CoreTypes` | `HI_TYPES` | TBXcoreStructV03.rng
+|===
+
+Element classes compose these via `merge`:
+
+[cols="2,3",options="header"]
+|===
+| Element class | TYPES composition
+
+| `Tbx::Admin` | Min::ADMIN_TYPES + Basic::ADMIN_TYPES + Linguist::ADMIN_TYPES
+| `Tbx::AdminNote` | Linguist::ADMIN_NOTE_TYPES
+| `Tbx::Descrip` | Min::DESCRIP_TYPES + Basic::DESCRIP_TYPES
+| `Tbx::TermNote` | Min::TERM_NOTE_TYPES + Basic::TERM_NOTE_TYPES + Linguist::TERM_NOTE_TYPES
+| `Tbx::Ref` | Basic::REF_TYPES
+| `Tbx::Xref` | Min::XREF_TYPES + Basic::XREF_TYPES
+| `Tbx::Transac` | Basic::TRANSAC_TYPES
+| `Tbx::TransacNote` | Basic::TRANSAC_NOTE_TYPES
+| `Tbx::Hi` | CoreTypes::HI_TYPES
+| `Tbx::TermCompSec` | (self-contained: hyphenation, lemma, morphologicalElement, syllabification, termElement)
+|===
+
+=== Shared concern
+
+`Tbx::DataElement` is a module that injects common attributes (id, lang,
+target, datatype, type, content) via `self.included(base)`.
+`Tbx::DataElement::InlineContent` adds inline child attributes (hi, ec,
+foreign, ph, sc) for elements with `entity.noteText` content.
+
+[cols="2,2",options="header"]
+|===
+| Element classes | Includes InlineContent?
+| `Admin`, `Descrip`, `TermNote` | Yes (entity.noteText content)
+| `AdminNote`, `DescripNote`, `TransacNote`, `Transac`, `Ref` | No (plain text only per RNG)
+|===
+
+== Schema source audit
+
+Every element class in `lib/tbx/` has YARD documentation tracing it to its
+schema source. The authoritative sources are:
+
+[cols="2,5",options="header"]
+|===
+| Source file | Defines
+
+| `TBXcoreStructV03.rng` | All structural elements, attributes, content models, and `hi` type values
+| `Min.tbxmd` | Min module data categories: customerSubset, subjectField, administrativeStatus, partOfSpeech, externalCrossReference
+| `Basic.tbxmd` | Basic module data categories: projectSubset, source, context, definition, geographicalUsage, grammaticalGender, termLocation, termType, crossReference, externalCrossReference, xGraphic, transactionType, responsibility
+| `Linguist.tbxmd` | Linguist module data categories: reading, readingNote, grammaticalNumber, register, transferComment
+| `TermComp-namespace.rng` | TermComp elements (termComp, termCompGrp, termCompSec) and type values
+| `TBX-Basic_DCA.sch` | TBX-Basic DCA Schematron: permitted `@type` values, picklist value constraints, level constraints
+| `TBX-Min_DCA.sch` | TBX-Min DCA Schematron
+| `TBX-Linguist_DCA.sch` | TBX-Linguist DCA Schematron
+| `TBX-Core.sch` | TBX-Core Schematron
+| `Basic.rng` / `Min.rng` / `Linguist.rng` | Module-level structural extensions
+| `Basic.sch` / `Min.sch` / `Linguist.sch` | Module-level Schematron rules
+|===
+
+== Reference documentation
+
+The `reference-docs/` directory contains official TBX schema, dialect, and
+module files from https://ltac-global.org[LTAC Global]. See
+link:reference-docs/README.adoc[reference-docs/README.adoc] for a complete
+inventory with source repository links.
+
+=== Official LTAC-Global repositories
+
+|===
+| Repository | Description
+
+| https://github.com/LTAC-Global/TBX_core_module[TBX_core_module]
+| Core structural schema (`TBXcoreStructV03.rng`)
+
+| https://github.com/LTAC-Global/TBX_min_module[TBX_min_module]
+| Min module data categories (RNG, Schematron, `.tbxmd`)
+
+| https://github.com/LTAC-Global/TBX_basic_module[TBX_basic_module]
+| Basic module data categories (RNG, Schematron, `.tbxmd`)
+
+| https://github.com/LTAC-Global/TBX_linguist_module[TBX_linguist_module]
+| Linguist module data categories (RNG, Schematron, `.tbxmd`)
+
+| https://github.com/LTAC-Global/TBX_termComp_module[TBX_termComp_module]
+| Term composition module (namespace RNG)
+
+| https://github.com/LTAC-Global/TBX_module_description_xml[TBX_module_description_xml]
+| `.tbxmd` format schema (`tbxmd.rng`)
+
+| https://github.com/LTAC-Global/TBX-Min_dialect[TBX-Min_dialect]
+| TBX-Min dialect (DCA + DCT Schematron, NVDL)
+
+| https://github.com/LTAC-Global/TBX-Basic_dialect[TBX-Basic_dialect]
+| TBX-Basic dialect (DCA + DCT Schematron, bundled modules)
+
+| https://github.com/LTAC-Global/TBX-Core_dialect[TBX-Core_dialect]
+| TBX-Core dialect (integrated RNG, Schematron)
+
+| https://github.com/LTAC-Global/TBX-Linguist_dialect[TBX-Linguist_dialect]
+| TBX-Linguist dialect (DCA + DCT Schematron, integrated RNG)
+
+| https://github.com/LTAC-Global/TBX-Basic_ImplementationGuide[TBX-Basic_ImplementationGuide]
+| TBX-Basic implementation guide
+
+| https://github.com/LTAC-Global/TBX_test_files[TBX_test_files]
+| Official TBX test fixture files
+|===
 
 == Test data
 
 Test fixtures are sourced from the
 https://github.com/LTAC-Global/TBX_test_files[TBX_test_files] repository
-maintained by https://ltac-global.org[LTAC Global], and from the TBX-Basic
-dialect schemas included in `reference-docs/`.
+maintained by https://ltac-global.org[LTAC Global], and from the dialect
+schemas and example files in `reference-docs/`.
 
 == Development
 
@@ -150,6 +492,10 @@ bundle exec rake
 This gem is developed, maintained and funded by
 https://www.ribose.com[Ribose Inc.]
 
+TBX schema, dialect, and module reference files are maintained by
+https://ltac-global.org[LTAC Global] and sourced from the
+https://github.com/LTAC-Global[LTAC-Global GitHub organization].
+
 == License
 
 The gem is available as open source under the terms of the

data/lib/tbx/admin.rb

@@ -1,18 +1,31 @@
 # frozen_string_literal: true
 
 module Tbx
+  # Administrative data category element `<admin>`.
+  #
+  # Carries administrative metadata about a terminological entry, such as
+  # customer subset classification, project association, source attribution,
+  # and pronunciation readings.
+  #
+  # Permitted `type` values (composed from all modules):
+  #
+  # * Min module: `customerSubset` — entry subset (DC-165)
+  # * Basic module: `projectSubset` — project-specific entry subset (DC-406),
+  #   `source` — origin of information (DC-471)
+  # * Linguist module: `reading` — pronunciation or reading of a term
+  #
+  # Content model: `entity.noteText` (mixed text + inline elements hi, ec,
+  # foreign, ph, sc).
+  #
+  # Schema source: TBXcoreStructV03.rng `<define name="admin">`;
+  # data categories: Min.tbxmd, Basic.tbxmd, Linguist.tbxmd.
   class Admin < Lutaml::Model::Serializable
-    attribute :id, :string
-    attribute :lang, Lutaml::Xml::W3c::XmlLangType
-    attribute :target, :string
-    attribute :datatype, :string
-    attribute :type, :string
-    attribute :content, :string, collection: true
-    attribute :hi, ::Tbx::Hi, collection: true
-    attribute :ec, ::Tbx::Ec, collection: true
-    attribute :foreign, ::Tbx::Foreign, collection: true
-    attribute :ph, ::Tbx::Ph, collection: true
-    attribute :sc, ::Tbx::Sc, collection: true
+    include Tbx::DataElement
+    include Tbx::DataElement::InlineContent
+
+    TYPES = Modules::Min::ADMIN_TYPES
+      .merge(Modules::Basic::ADMIN_TYPES)
+      .merge(Modules::Linguist::ADMIN_TYPES).freeze
 
     xml do
       root "admin"

data/lib/tbx/admin_grp.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 module Tbx
+  # Groups an `<admin>` element with its associated notes and references.
+  #
+  # Children: `admin` (required), then adminNote, note, ref, xref.
+  #
+  # Schema source: TBXcoreStructV03.rng `<define name="adminGrp">`
   class AdminGrp < Lutaml::Model::Serializable
     attribute :id, :string
     attribute :admin, ::Tbx::Admin

data/lib/tbx/admin_note.rb

@@ -1,13 +1,21 @@
 # frozen_string_literal: true
 
 module Tbx
+  # Administrative note element `<adminNote>`.
+  #
+  # Provides notes about administrative data. Content is plain text only
+  # (no inline elements per the core RNG).
+  #
+  # Permitted `type` values:
+  #
+  # * Linguist module: `readingNote` — note about a term's reading/pronunciation
+  #
+  # Schema source: TBXcoreStructV03.rng `<define name="adminNote">`;
+  # data category: Linguist.tbxmd.
   class AdminNote < Lutaml::Model::Serializable
-    attribute :id, :string
-    attribute :lang, Lutaml::Xml::W3c::XmlLangType
-    attribute :target, :string
-    attribute :datatype, :string
-    attribute :type, :string
-    attribute :content, :string, collection: true
+    include Tbx::DataElement
+
+    TYPES = Modules::Linguist::ADMIN_NOTE_TYPES.freeze
 
     xml do
       root "adminNote"

data/lib/tbx/back.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 module Tbx
+  # Back matter `<back>` containing reference object sections.
+  #
+  # Used for managing picklists and external references.
+  #
+  # Schema source: TBXcoreStructV03.rng `<define name="back">`
   class Back < Lutaml::Model::Serializable
     attribute :id, :string
     attribute :ref_object_sec, ::Tbx::RefObjectSec, collection: true

data/lib/tbx/body.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Tbx
+  # Body element `<body>` containing all concept entries.
+  #
+  # Schema source: TBXcoreStructV03.rng `<define name="body">`
   class Body < Lutaml::Model::Serializable
     attribute :id, :string
     attribute :concept_entry, ::Tbx::ConceptEntry, collection: true

data/lib/tbx/change.rb

@@ -1,6 +1,12 @@
 # frozen_string_literal: true
 
 module Tbx
+  # A single change record in the revision history `<change>`.
+  #
+  # Each change record contains one or more paragraph elements describing
+  # what changed and when.
+  #
+  # Schema source: TBXcoreStructV03.rng `<define name="change">`
   class Change < Lutaml::Model::Serializable
     attribute :id, :string
     attribute :lang, Lutaml::Xml::W3c::XmlLangType

data/lib/tbx/concept_entry.rb

@@ -1,6 +1,16 @@
 # frozen_string_literal: true
 
 module Tbx
+  # A single concept entry `<conceptEntry>`.
+  #
+  # Represents a concept in the terminology collection. The `id` attribute
+  # is required and must be unique within the document.
+  #
+  # Permitted children are defined by the `entity.auxInfo` pattern:
+  # admin, adminGrp, descrip, descripGrp, note, ref, transacGrp, xref,
+  # followed by one or more langSec elements.
+  #
+  # Schema source: TBXcoreStructV03.rng `<define name="conceptEntry">`
   class ConceptEntry < Lutaml::Model::Serializable
     attribute :id, :string
     attribute :admin, ::Tbx::Admin, collection: true