chemicalml 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5aff6a0c43deeff73ff9684286df7c1a7ef97d61fa919415a381e70de217995c
-  data.tar.gz: 52237d4db8715d8244b88c124cf3bdc1ad43102b4468d8217099ebdec6b89f1b
+  metadata.gz: 6d2ca704dfe6cadaad8792ffcb198b64ad410dc5445e487181271e9f76d30c0d
+  data.tar.gz: 86dcd34b748cf321c5cabd049d34f0359a4251c11c56fbdf01757ef53001fd5d
 SHA512:
-  metadata.gz: b9f636c62b495c14f5ab10df0c8fd30e49aa23587731587f2fc9f4d87837376da38db8814df48482e1725751090518722ff3e6ca43ea5197fefb53ab5055183a
-  data.tar.gz: c7b42562ce98060bd3ca135d137be215f25a2ae71e2fc2693b70ab7e1030f8c6868744dea7aa9d60d078ba6adc11fc28a7c8d63de4f5f69c0a9b16ff8fe6f65f
+  metadata.gz: 3dfc7a086ff3df8156ab1bb10a692b75b6dea04789cc19d2bb8919fad40cbcf2f1d40cc92f871a501512ea8a0647c39218d6e7f133b5b95fc88289231386de9a
+  data.tar.gz: 20098a7fe4dee32546f270bfe6d2fa294ef5617b3ede17d0a3125cc1230c430053bb9e6502f4ae81c81ea068fbb984d94fb4d184ccc0b4e120fd212a137d4749

data/.github/workflows/release.yml

@@ -2,33 +2,40 @@
 # See https://github.com/metanorma/cimas
 name: release
 
-permissions:
-  contents: write
-  packages: write
-  id-token: write
-
 on:
   workflow_dispatch:
     inputs:
       next_version:
         description: |
-          Next release version. Possible values: x.y.z, major, minor, patch (or pre|rc|etc).
-          Also, you can pass 'skip' to skip 'git tag' and do 'gem push' for the current version
+          Next release version. Possible values: x.y.z, major, minor, patch or pre|rc|etc
         required: true
         default: 'skip'
-      acknowledge_breaking_in_patch:
-        description: 'Override the patch-release breaking-change guard when the trip is a known false-positive'
-        required: false
-        type: boolean
-        default: false
   repository_dispatch:
     types: [ do-release ]
 
+# Least-privilege ceiling for the called rubygems-release.yml: its release job
+# needs contents:write (git tag push) and id-token:write (OIDC Trusted Publishing).
+# packages:write is not required for RubyGems Trusted Publishing.
+permissions:
+  contents: write
+  id-token: write
+
+# One release at a time: concurrent bumps race the version commit
+# and half-published gems are worse than a queued release.
+concurrency:
+  group: release
+  cancel-in-progress: false
+
 jobs:
   release:
     uses: metanorma/ci/.github/workflows/rubygems-release.yml@main
     with:
       next_version: ${{ github.event.inputs.next_version }}
-      acknowledge_breaking_in_patch: ${{ inputs.acknowledge_breaking_in_patch }}
     secrets:
-      rubygems-api-key: ${{ secrets.LUTAML_CI_RUBYGEMS_API_KEY }}
+      # OMIT rubygems-api-key: metanorma/ci switches to OIDC Trusted Publishing
+      # when the secret is empty (USE_OIDC = rubygems-api-key == ''). Trusted
+      # Publishing is already configured for lutaml gems on rubygems.org —
+      # do not re-introduce LUTAML_CI_RUBYGEMS_API_KEY here.
+      # pat_token is optional (private-gem checkout + GH Packages). Keep if
+      # the org still uses private deps; drop once pure public.
+      pat_token: ${{ secrets.LUTAML_CI_PAT_TOKEN }}

data/.rubocop.yml

@@ -10,11 +10,34 @@ AllCops:
     - "coverage/**/*"
     - "reference-docs/**/*"
     - "spec/fixtures/**/*"
+    - "data/**/*"
 
 Metrics/BlockLength:
   Exclude:
     - "spec/**/*"
     - "*.gemspec"
+    - "lib/chemicalml/cml/base/**/*.rb"
+
+# Base::* modules are structurally long: each declares every attribute
+# and both xml + key_value mapping blocks for one CML element in a
+# single `self.included` hook. This is the correct structure — the
+# alternative (splitting into smaller methods) would scatter one
+# element's declarations across multiple files.
+Metrics/MethodLength:
+  Exclude:
+    - "lib/chemicalml/cml/base/**/*.rb"
+
+Metrics/AbcSize:
+  Exclude:
+    - "lib/chemicalml/cml/base/**/*.rb"
+
+Metrics/ModuleLength:
+  Exclude:
+    - "lib/chemicalml/cml/base/**/*.rb"
+
+Layout/LineLength:
+  Exclude:
+    - "lib/chemicalml/cml/base/**/*.rb"
 
 Style/Documentation:
   Enabled: false

data/CHANGELOG.md

@@ -3,6 +3,38 @@
 All notable changes to Chemicalml are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+### Added
+- Rich-text dictionary content: `<definition>` and `<description>`
+  now carry their `<xhtml:p>` paragraphs instead of flattening them
+  into strings. `Xhtml::P` is a wire class owning the XHTML
+  namespace (lutaml-model assigns one namespace per model class);
+  `DictionaryEntry`/`Dictionary` type definition/description to the
+  structured classes, the entry-must-contain-definition constraint
+  reads both shapes (plain string or structured), and the two
+  dictionary fixtures graduate from PENDING_SEMANTIC to full
+  semantic round-trip comparison (closes #19).
+
+### Fixed
+- Container child declarations that round-tripping silently dropped:
+  `<cml>`/`<module>` now carry `reactionScheme` and `spectrum`
+  children, `<dictionary>` carries dictionary-level `<definition>`,
+  `<unitType>` carries `<dimension>`, `<molecule>` carries the
+  `concise` formula attribute, `<peak>` carries the `<atomRefs>`
+  child-element form (the attribute form was already mapped), and
+  `<xaxis>`/`<yaxis>` carry CML's `multipler` attribute. Every
+  schema3 fixture now round-trips semantically except the two
+  dictionary fixtures whose xhtml-namespaced mixed content needs a
+  rich-content model (lutaml/chemicalml#19, marked PENDING_SEMANTIC
+  with the structural re-parse check still running).
+
+### Changed
+- `lutaml-model` pin aligned to the pessimistic house convention
+  (`~> 0.8`). The full suite passes against the current stack
+  (lutaml-model 0.8.114, moxml 0.5.146, leptris 1.9.372, canon
+  with processing-instruction tree-diff support - lutaml/canon#271).
+
 ## [0.2.0] - 2026-07-14
 
 ### Added

data/CLAUDE.md

@@ -26,6 +26,9 @@ bundle exec rspec -e "round-trips"                       # by name match
 bundle exec rake              # alias for rspec
 bundle exec rubocop           # lint
 bundle exec rubocop -A        # autocorrect
+bundle exec chemicalml validate <file.cml>  # CLI validation
+bundle exec chemicalml conventions          # list registered conventions
+bundle exec chemicalml dictionaries         # list built-in dictionaries
 ```
 
 `spec/examples.txt` and `Gemfile.lock` are gitignored — `spec/examples.txt`
@@ -126,17 +129,35 @@ Schema 3's unified `scalar`/`array`/`table` machinery.
 The framework handles (de)serialization; **never** add `def to_xml` /
 `def from_xml` / `def to_h` to these classes.
 
+### JSON / YAML wire names
+
+Every `Base::*` module declares a `key_value do ... end` block
+alongside its `xml do ... end` block, mirroring the XML wire names
+explicitly. JSON and YAML output carry CML wire names
+(`elementType`, `atomArray`) rather than Ruby snake_case names.
+The blocks are written out by hand per Base module — no runtime
+introspection.
+
 ### Schema versions
 
 `Chemicalml::Schema::Registry` is the registry for schema versions
 (`schema24`, `schema3`). The schema XSDs are **archival source** —
 they must never be deleted, edited, or regenerated from code.
 
+**Type-name collision**: Schema24's legacy `<string>`, `<integer>`,
+`<float>` elements share their XML names with lutaml-model primitives
+(`:string`, `:integer`, `:float`). They are NOT registered as types
+in the Schema24 context (would shadow the primitive, breaking every
+`:string` attribute cast). They remain defined as wire classes and
+parseable as document roots. See
+`Cml::Elements::SCHEMA24_TYPE_COLLISIONS`.
+
 ### Conventions
 
 `Chemicalml::Convention` is a registry of named constraint sets
 (`molecular`, `compchem`, `dictionary`, `unit-dictionary`,
-`unitType-dictionary`). Each convention owns:
+`unitType-dictionary`, `spectroscopy`, `cascade`, `simpleUnit`).
+Each convention owns:
 
 - a namespace URI (e.g. `http://www.xml-cml.org/convention/molecular`)
 - a set of constraint classes registered against it
@@ -148,6 +169,33 @@ renderer code (Open/Closed Principle).
 The constraint walker uses `Cml::Visitable#wire_children` to traverse
 the tree — no `respond_to?` duck typing.
 
+The shared `Cml::Base::CommonChildren` mixin provides `metadataList`,
+`label`, `name`, and `description` children that the XSD grants to
+most container elements. Including it in a `Base::*` module is the
+DRY way to declare the universal child set.
+
+`Cml::Enums` is the canonical Ruby source of truth for every XSD
+enum simpleType. Three constraints validate against it
+(`BondOrderShouldBeInEnum`, `BondStereoShouldBeInEnum`,
+`MoleculeChiralityShouldBeInEnum`) at warning severity — extension
+values are permitted but flagged.
+
+`Cml::ReferenceResolver` walks a document and resolves
+id-references (`atomRefs2`, `atomRefs4`, `bondRefs`, `ref`) to
+target wire instances. `unresolved_refs` lists missing targets;
+useful for callers that need to follow CML references.
+
+### Parallel-array serialisation
+
+`<atomArray>` and `<bondArray>` support two equivalent XML forms: the
+child form (`<atomArray><atom.../><atom.../></atomArray>`) and the
+parallel-array form (`<atomArray atomID="a1 a2" elementType="C O"/>`).
+The wire attribute names in the parallel-array form match the
+singular `<atom>` / `<bond>` attribute names (e.g. `elementType`,
+`atomRef1`) — the XSD attribute *group* is named `elementTypeArray`
+etc., but the wire attribute is `elementType`. Ruby attribute names
+carry an `_array` suffix for clarity at the call site.
+
 ### Dictionaries
 
 `Chemicalml::Dictionary` is the model; entries have `id`, `term`,

data/README.adoc

@@ -4,13 +4,19 @@ ChemML provides a https://www.xml-cml.org/[Chemical Markup Language (CML)]
 object model for Ruby, built on
 {lutaml-model}[https://github.com/lutaml/lutaml-model].
 
-== Purpose
-
-CML is the established XML standard for chemistry. Existing Ruby
-libraries either don't exist or use hand-rolled XML manipulation that
-drifts from the CML schema. ChemML gives CML a proper model layer
-with declarative attribute/mapping definitions and framework-backed
-serialization.
+== Features
+
+* Full Schema 3 and Schema 2.4 coverage — every CML element, attribute,
+  and XSD enum/pattern modelled as Ruby classes.
+* Format-agnostic serialization — XML, JSON, YAML, and TOML round-trip
+  via lutaml-model adapters.
+* Eight built-in conventions with 88+ registered constraints:
+  `molecular`, `compchem`, `dictionary`, `unit-dictionary`,
+  `unitType-dictionary`, `spectroscopy`, `cascade`, `simpleUnit`.
+* Built-in dictionaries (cml, compchem, cif, unit_si, unit_non_si,
+  unit_type, cml_name, cml_formula) loaded from YAML.
+* CLI for command-line validation and inspection.
+* Ruby-native query API (`doc.find_atom(id)`, `doc.each_molecule`).
 
 == Install
 
@@ -30,45 +36,167 @@ $ gem install chemicalml
 
 == Usage
 
-Parse a CML document:
+=== Parse a CML document
 
 [source,ruby]
 ----
 require "chemicalml"
 
-doc = Chemicalml::Cml::Document.from_xml(File.read("ethanol.cml"))
-doc.molecules.first.atoms.first.element_type # => "C"
+doc = Chemicalml.parse_file("ethanol.cml")
+doc.molecules.first.atom_array.atoms.first.element_type # => "C"
+----
+
+=== Validate against a convention
+
+[source,ruby]
+----
+report = Chemicalml.validate(doc)
+puts report.summary
+puts report.errors.map(&:message)
 ----
 
-Build a document programmatically:
+=== Build a document programmatically
 
 [source,ruby]
 ----
 atom = Chemicalml::Cml::Atom.new(id: "a1", element_type: "C")
-mol  = Chemicalml::Cml::Molecule.new(id: "m1", atoms: [atom])
+mol  = Chemicalml::Cml::Molecule.new(
+  id: "m1",
+  atom_array: Chemicalml::Cml::AtomArray.new(atoms: [atom])
+)
 doc  = Chemicalml::Cml::Document.new(molecules: [mol])
 
 doc.to_xml # => well-formed CML XML
 ----
 
-== Design
+=== Query the tree
 
-Each CML element is a `Lutaml::Model::Serializable` subclass with
-declared attributes and an XML mapping block. Serialization goes
-through lutaml-model — no hand-rolled XML.
+[source,ruby]
+----
+doc.each_atom { |a| puts "#{a.id}: #{a.element_type}" }
+doc.find_atom("a1")     # => Atom instance
+doc.atom_count          # => recursive count
+doc.find_molecule("m1") # => Molecule instance
+----
+
+=== Cross-format serialisation
+
+[source,ruby]
+----
+doc.to_xml   # CML XML
+doc.to_json  # JSON with CML wire names (elementType, atomArray, ...)
+doc.to_yaml  # YAML
+----
+
+=== Resolve references
+
+[source,ruby]
+----
+resolver = Chemicalml::Cml::ReferenceResolver.new(doc)
+resolver.unresolved_refs  # => [{ node: <Bond>, attr: :atom_refs2, missing: ["a99"] }]
+----
+
+== CLI
+
+[source,sh]
+----
+$ chemicalml validate file.cml    # auto-detect convention, print violations
+$ chemicalml inspect file.cml     # tree-style summary
+$ chemicalml conventions          # list 8 registered conventions
+$ chemicalml dictionaries         # list built-in YAML dictionaries
+$ chemicalml elements             # list all CML wire classes
+----
+
+== Conventions
+
+Eight conventions register 88+ constraints:
+
+[cols="1,1,1"]
+|===
+| Convention | Constraints | Description
+
+| molecular | 35 | Atom/bond/molecule well-formedness, id patterns,
+  element type validation, dictRef resolution, AtomParity parent
+  check, references-resolve check.
+| compchem | 20 | JobList/Job/Initialization/Calculation/Finalization
+  module structure, scalar/array/matrix value rules.
+| dictionary | 8 | Dictionary namespace, prefix, entry id/term/definition,
+  unitType/units co-constraints.
+| unit-dictionary | 8 | UnitList namespace, unit id/title/symbol/parentSI/
+  multiplierToSI, definition child.
+| unitType-dictionary | 5 | UnitTypeList namespace, unitType id/name/definition.
+| spectroscopy | 5 | Spectrum convention/format/content, peakList, peak values.
+| cascade | 4 | ReactionScheme content, reactionStepList, reactiveCentre atomRefs.
+| simpleUnit | 3 | simpleUnit root, unit power, unit symbol.
+|===
+
+Add a custom convention at runtime:
+
+[source,ruby]
+----
+module MyConvention
+  extend Chemicalml::Convention::Base
+
+  def self.qname; "convention:my"; end
+  def self.namespace_uri; "http://example.com/my"; end
+
+  register MyConstraintClass
+end
 
-The library is designed as a sibling model layer to other chemistry
-tooling. AsciiChem (https://www.asciichem.org) uses ChemML for CML
-round-trip support via a translator adapter.
+Chemicalml::Convention::Registry.register_custom(MyConvention)
+----
+
+== Dictionaries
+
+Eight built-in YAML dictionaries ship under `data/dictionaries/`:
+
+[cols="1,1"]
+|===
+| Dictionary | Prefix
+
+| cml | cml
+| cml_name | cmlName
+| cml_formula | cmlFormula
+| cif | cif
+| compchem | compchem
+| unit_si | si
+| unit_non_si | nonsi
+| unit_type | unitType
+|===
+
+Load via:
 
-Both Schema 2.4 and Schema 3 are supported via
-`Chemicalml::Cml::Schema3` and `Chemicalml::Cml::Schema24` namespaces
-(see `lib/chemicalml/schema.rb`).
+[source,ruby]
+----
+dict = Chemicalml::Dictionary.load(:cml)
+entry = Chemicalml::Dictionary::Registry.lookup("cml:bp")
+entry.term        # => "Boiling Point"
+entry.definition  # => "The temperature at which a substance boils..."
+----
 
-The CML conventions (molecular, compchem, dictionary, unit-dictionary,
-unitType-dictionary) are implemented as registered constraint sets in
-`Chemicalml::Convention`. Built-in dictionaries ship as YAML under
-`data/dictionaries/`.
+== Design
+
+Each CML element is a `Lutaml::Model::Serializable` subclass with
+declared attributes and parallel `xml do ... end` and
+`key_value do ... end` mapping blocks. Serialisation is fully
+framework-backed — no hand-rolled XML.
+
+* `Cml::Base::*` modules declare shared attributes (mixed into both
+  Schema3 and Schema24 wire classes).
+* `Cml::Role::*` modules are type-markers used by the convention
+  constraint walker for `is_a?` dispatch.
+* `Cml::Elements::ALL` is the single source of truth for the CML
+  element table.
+* `Cml::Enums` and `Cml::Patterns` mirror XSD simpleTypes.
+* `Cml::CommonChildren` provides the universal `metadataList`,
+  `label`, `name`, `description` child set as a DRY mixin.
+
+== Reference docs
+
+`reference-docs/` holds archival source material from xml-cml.org:
+the XSDs (`schemas/schema3/schema.xsd`, `schemas/schema24/schema.xsd`),
+the convention specifications, and the CMLLite paper. These are
+**source material, not derived output** — never delete or edit them.
 
 == Acknowledgements
 

data/TODO.align/61-parallel-array-attrs.md

@@ -0,0 +1,54 @@
+# 61 — Parallel-array attrs for atomArray/bondArray
+
+## Why
+
+CML supports two equivalent serialisations of atom/bond tables:
+
+```xml
+<!-- child form (we already model this) -->
+<atomArray><atom id="a1" elementType="C" x3="1.0" .../><atom .../></atomArray>
+
+<!-- parallel-array form (we do NOT model this) -->
+<atomArray atomID="a1 a2" elementType="C O" x3="1.0 2.0" .../>
+```
+
+The parallel-array form is heavily used in real CML documents and is
+the only form some legacy tools emit. Round-trip currently drops these
+attributes silently.
+
+## Source of truth
+
+`reference-docs/schemas/schema3/schema.xsd` — `atomArrayType` complexType
+declares these 14 parallel-array attributes:
+
+- `atomID` (idArrayType)
+- `count`, `countArrayType`
+- `elementType`, `elementTypeArrayType`
+- `formalCharge`, `formalChargeArrayType`
+- `hydrogenCount`, `hydrogenCountArrayType`
+- `occupancy`, `occupancyArrayType`
+- `x2`, `y2` (coordinateComponentArrayType)
+- `x3`, `y3`, `z3` (coordinateComponentArrayType)
+- `xFract`, `yFract`, `zFract` (coordinateComponentArrayType)
+
+`bondArrayType` declares 4:
+
+- `atomRef1`, `atomRef2` (atomRefArrayType)
+- `bondID` (idArrayType)
+- `order` (orderArrayType)
+
+## Work
+
+1. `lib/chemicalml/cml/base/atom_array.rb` — declare the 14 attributes
+   as `:string` (lutaml-model does not need to validate the inner
+   whitespace-separated format) with matching `map_attribute` entries.
+2. `lib/chemicalml/cml/base/bond_array.rb` — declare the 4 attributes.
+3. Add specs in `spec/chemicalml/cml/parallel_array_spec.rb` asserting
+   round-trip for both forms.
+
+## Acceptance
+
+- `Chemicalml.parse` of a parallel-array `<atomArray>` populates the
+  attributes; `Chemicalml.serialize` emits them back unchanged.
+- Both forms supported for Schema3 and Schema24.
+- Specs green.

data/TODO.align/62-per-element-attribute-gaps.md

@@ -0,0 +1,49 @@
+# 62 — Per-element attribute gaps
+
+## Why
+
+XSD vs Ruby Base comparison reveals 53 (schema3) / 58 (schema24)
+attribute declarations that are not yet modelled. They cluster across
+20 elements. Most are 1-3 missing attributes; the parallel-array
+attributes for atomArray/bondArray are split out into TODO 61.
+
+## Gaps (after TODO 61 closes)
+
+| Element | Missing |
+|---|---|
+| alternative | type |
+| band | kpoint (schema24 only) |
+| bond | atomRefs (singular, not atomRefs2) |
+| cellParameter | error, type |
+| cml (module) | fileId, version |
+| eigen | orientation |
+| entry | convention, title, columns, rows, length, minLength, maxLength, pattern, minExclusive, minInclusive, maxExclusive, maxInclusive, fractionDigits, totalDigits, whiteSpace (XSD facets) |
+| isotope | spin |
+| module | role, serial |
+| molecule | formula |
+| peakStructure | type |
+| potential | form |
+| reaction | format, role |
+| reactionScheme | format, role, type |
+| reactionStepList | format |
+| relatedEntry | type (schema24 only) |
+| spectrum | type |
+| substance | id |
+| substanceList | type |
+| unitList | type |
+
+## Work
+
+For each row above, add `attribute :foo, :string` + `map_attribute "foo", to: :foo`
+to the relevant `lib/chemicalml/cml/base/*.rb` module.
+
+The 15 XSD facets on `entry` (columns, fractionDigits, etc.) are
+genuine CML — they describe the data type the entry represents, and
+are emitted by the upstream dictionary files. They are not internal
+XSD noise.
+
+## Acceptance
+
+- XSD vs Ruby comparison reports 0 attribute gaps.
+- Round-trip of an example with `entry/@pattern` etc. is preserved.
+- Spec coverage for at least one new attribute on each touched element.

data/TODO.align/63-universal-children-mixin.md

@@ -0,0 +1,42 @@
+# 63 — Universal children mixin
+
+## Why
+
+The CML Schema 2.4 XSD declares `metadataList`, `label`, `name`, and
+`description` as children of nearly every element. Adding these four
+declarations to every `Base::*` module individually is a DRY
+violation: the same 16 lines of `attribute` + `map_element` would
+appear in ~50 files.
+
+## Solution
+
+Introduce a shared mixin `Chemicalml::Cml::Base::CommonChildren`
+that declares:
+
+```ruby
+attribute :metadata_lists, :metadataList, collection: true
+attribute :labels, :label, collection: true
+attribute :names, :name, collection: true
+attribute :descriptions, :description, collection: true
+```
+
+with matching `map_element` declarations. The mixin is included by
+the `Base::*` modules whose XSD declares these children.
+
+The mixin is **opt-in** — elements that the XSD does not grant these
+children to (e.g. `<atom>`, `<bond>` in schema24) do not include it.
+This keeps MECE discipline: one place owns the universal child set.
+
+## Work
+
+1. Create `lib/chemicalml/cml/base/common_children.rb`.
+2. For each Base module where the XSD declares metadataList/label/name/description as a child, add `include CommonChildren` and remove the now-redundant individual declarations.
+3. Add a spec `spec/chemicalml/cml/common_children_spec.rb` asserting
+   the children appear after `include CommonChildren` and round-trip
+   through XML.
+
+## Acceptance
+
+- `CommonChildren` exists and is included by at least 10 Base modules.
+- No Base module re-declares `metadata_lists` / `labels` / `names` / `descriptions` individually.
+- Specs green.

data/TODO.align/64-per-element-child-gaps.md

@@ -0,0 +1,81 @@
+# 64 — Per-element child element gaps (Schema 2.4)
+
+## Why
+
+XSD vs Ruby Base comparison reveals 235 missing child declarations
+across ~60 Schema 2.4 elements. These are real CML elements that
+real CML documents contain but our Ruby model drops silently.
+
+The Schema 3 XSD declares `<anyCml>` (a wildcard) as a child of every
+element — that is intentionally NOT modelled as a concrete child,
+because doing so would defeat the type system. The Schema 2.4 gaps
+below are *specific* named children, not wildcards.
+
+## Largest clusters
+
+| Element | Missing children |
+|---|---|
+| molecule | angle, arg, array, crystal, electron, join, length, list, matrix, metadataList, propertyList, scalar, symmetry, torsion, zMatrix |
+| reaction | conditionList, identifier, label, map, mechanism, metadataList, name, object, propertyList, reactiveCentre, spectatorList, substanceList, transitionState |
+| reactant, product | amount, electron, formula, identifier, label, metadataList, molecule, name, substanceList |
+| atom | array, atomType, electron, label, matrix, name, particle, scalar, vector3 |
+| atomType, bondType | array, atom/bond, label, matrix, molecule, property, scalar |
+| join | angle, arg, label, length, metadataList, molecule, torsion |
+| peak, peakGroup | atom, bond, metadataList, molecule, peakStructure/peakGroup |
+| spectrum | metadataList, parameterList, sample, spectrumData, substanceList |
+| reactiveCentre | atomSet, atomTypeList, bondSet, bondTypeList, description |
+| parameter | expression, gradient, property |
+| property | metadataList, name |
+| parameterList, productList, reactantList, reactionStepList | metadataList, name, *(selfRef)* |
+| moleculeList | list, metadataList, moleculeList |
+| sample | metadataList, molecule, substance, substanceList |
+| spectator | label, metadataList, molecule, object |
+| substance | amount, metadataList, property |
+| substanceList | amount, metadataList, propertyList |
+| lattice | matrix, scalar, symmetry |
+| gradient | array, matrix, property, scalar |
+| table | arrayList, tableRowList |
+| transitionState | molecule, propertyList |
+| unit | annotation, metadata, metadataList, unit, unitType |
+| unitType | annotation, dimension |
+| zMatrix | angle, length, torsion |
+| symmetry | matrix, transform3 |
+| eigen | array, matrix |
+| xaxis, yaxis | array |
+| metadataList | metadataList |
+| crystal | cellParameter |
+| formula | formula |
+| dictionary | annotation, unitList |
+| dictionary entry | alternative, annotation, enumeration, metadataList, relatedEntry |
+| map | link |
+| mechanism | description, label, name |
+| peakStructure | metadataList, peakStructure |
+| reactionList | metadataList, reactionScheme |
+| reactionScheme | identifier, label, metadataList, name, reactionScheme |
+| reactionStep | label, metadataList, name, reactionScheme |
+| potentialForm | arg, expression, parameter |
+| trow | tcell |
+| peakList | metadataList |
+| atomTypeList, bondTypeList, basisSet | metadataList, name |
+| conditionList | list, metadataList, name |
+| propertyList | metadataList, name, observation, propertyList |
+| spectrumList | list, metadataList, spectrumList |
+
+## Strategy
+
+After TODO 63 (CommonChildren mixin) closes, ~80% of the
+`metadataList`/`label`/`name`/`description` gaps are absorbed by
+adding one `include CommonChildren` line. The remaining ~150 gaps are
+element-specific and require individual declarations.
+
+## Work
+
+1. Apply CommonChildren where the XSD permits.
+2. For each remaining gap, add the specific `attribute` + `map_element` declarations.
+3. Add at least one spec per touched element covering a round-trip
+   with the new child.
+
+## Acceptance
+
+- XSD vs Ruby child comparison reports only `<anyCml>` Schema3 wildcard gaps (intentionally unmodelled).
+- Specs green.