chemicalml 0.2.0 → 0.3.0

data/lib/chemicalml/cml.rb

@@ -8,142 +8,174 @@ module Chemicalml
   # and are included by both schema-versioned class hierarchies.
   module Cml
     # Structural modules (each in its own file, loaded independently).
-    autoload :Base,              "chemicalml/cml/base"
-    autoload :ChildMappings,    "chemicalml/cml/child_mappings"
-    autoload :Elements,          "chemicalml/cml/elements"
-    autoload :Namespace,         "chemicalml/cml/namespace"
-    autoload :Role,              "chemicalml/cml/role"
-    autoload :Schema3,           "chemicalml/cml/schema3"
-    autoload :Schema24,          "chemicalml/cml/schema24"
-    autoload :Translator,        "chemicalml/cml/translator"
-    autoload :Visitable,         "chemicalml/cml/visitable"
-    autoload :WireClassRegistry, "chemicalml/cml/wire_class_registry"
+    autoload :Base,                'chemicalml/cml/base'
+    autoload :CanonicalComparison, 'chemicalml/cml/canonical_comparison'
+    autoload :Elements,            'chemicalml/cml/elements'
+    autoload :Enums,             'chemicalml/cml/enums'
+    autoload :Namespace,         'chemicalml/cml/namespace'
+    autoload :Patterns,          'chemicalml/cml/patterns'
+    autoload :ReferenceResolver, 'chemicalml/cml/reference_resolver'
+    autoload :Role,              'chemicalml/cml/role'
+    autoload :Schema3,           'chemicalml/cml/schema3'
+    autoload :Schema24,          'chemicalml/cml/schema24'
+    autoload :Visitable,         'chemicalml/cml/visitable'
+    autoload :WireClassRegistry, 'chemicalml/cml/wire_class_registry'
 
-    # Backward-compatible aliases (Cml::Foo = Schema3::Foo). All 36
+    class << self
+      # Look up a wire class by XML element name.
+      #
+      # @param xml_name [String, Symbol] the XML element name, e.g. "atomArray".
+      # @param schema [Symbol] `:schema3` (default) or `:schema24`.
+      # @return [Class, nil] the matching wire class, or nil if not found.
+      def for_xml_name(xml_name, schema: :schema3)
+        class_name = Elements::XML_TO_CLASS[xml_name.to_s]
+        return nil unless class_name
+
+        parent = schema == :schema24 ? Schema24 : Schema3
+        parent.const_get(class_name)
+      rescue NameError
+        nil
+      end
+
+      # Enumerate every wire class for a schema version.
+      #
+      # @param schema [Symbol] `:schema3` or `:schema24`.
+      # @return [Array<Class>] the wire classes.
+      def wire_classes(schema: :schema3)
+        parent = schema == :schema24 ? Schema24 : Schema3
+        Elements::ALL.keys.map do |class_name|
+          parent.const_get(class_name)
+        rescue NameError
+          nil
+        end.compact
+      end
+    end
+
+    # Backward-compatible aliases (Cml::Foo = Schema3::Foo). All 121
     # aliases load from a single file via autoload — the file loads
     # lazily when the first alias is referenced, then defines all of
     # them via const_set (aliasing existing Schema3 classes, not
     # creating new ones).
-    autoload :Array,           "chemicalml/cml/aliases"
-    autoload :Atom,            "chemicalml/cml/aliases"
-    autoload :AtomArray,       "chemicalml/cml/aliases"
-    autoload :AtomParity,      "chemicalml/cml/aliases"
-    autoload :Bond,            "chemicalml/cml/aliases"
-    autoload :BondArray,       "chemicalml/cml/aliases"
-    autoload :BondStereo,      "chemicalml/cml/aliases"
-    autoload :Dictionary,      "chemicalml/cml/aliases"
-    autoload :DictionaryEntry, "chemicalml/cml/aliases"
-    autoload :Document,        "chemicalml/cml/aliases"
-    autoload :Formula,         "chemicalml/cml/aliases"
-    autoload :Identifier,      "chemicalml/cml/aliases"
-    autoload :Label,           "chemicalml/cml/aliases"
-    autoload :List,            "chemicalml/cml/aliases"
-    autoload :Matrix,          "chemicalml/cml/aliases"
-    autoload :Metadata,        "chemicalml/cml/aliases"
-    autoload :MetadataList,    "chemicalml/cml/aliases"
-    autoload :Module,          "chemicalml/cml/aliases"
-    autoload :Molecule,        "chemicalml/cml/aliases"
-    autoload :Name,            "chemicalml/cml/aliases"
-    autoload :Parameter,       "chemicalml/cml/aliases"
-    autoload :ParameterList,   "chemicalml/cml/aliases"
-    autoload :Product,         "chemicalml/cml/aliases"
-    autoload :ProductList,     "chemicalml/cml/aliases"
-    autoload :Property,        "chemicalml/cml/aliases"
-    autoload :PropertyList,    "chemicalml/cml/aliases"
-    autoload :Reaction,        "chemicalml/cml/aliases"
-    autoload :ReactionList,    "chemicalml/cml/aliases"
-    autoload :Reactant,        "chemicalml/cml/aliases"
-    autoload :ReactantList,    "chemicalml/cml/aliases"
-    autoload :Scalar,          "chemicalml/cml/aliases"
-    autoload :Substance,       "chemicalml/cml/aliases"
-    autoload :Unit,            "chemicalml/cml/aliases"
-    autoload :UnitList,        "chemicalml/cml/aliases"
-    autoload :UnitType,        "chemicalml/cml/aliases"
-    autoload :UnitTypeList,    "chemicalml/cml/aliases"
-    autoload :Abundance, "chemicalml/cml/aliases"
-    autoload :Action, "chemicalml/cml/aliases"
-    autoload :ActionList, "chemicalml/cml/aliases"
-    autoload :Amount, "chemicalml/cml/aliases"
-    autoload :Angle, "chemicalml/cml/aliases"
-    autoload :AnyCml, "chemicalml/cml/aliases"
-    autoload :ArrayList, "chemicalml/cml/aliases"
-    autoload :AtomSet, "chemicalml/cml/aliases"
-    autoload :AtomType, "chemicalml/cml/aliases"
-    autoload :AtomTypeList, "chemicalml/cml/aliases"
-    autoload :AtomicBasisFunction, "chemicalml/cml/aliases"
-    autoload :Band, "chemicalml/cml/aliases"
-    autoload :BandList, "chemicalml/cml/aliases"
-    autoload :BasisSet, "chemicalml/cml/aliases"
-    autoload :BondSet, "chemicalml/cml/aliases"
-    autoload :BondType, "chemicalml/cml/aliases"
-    autoload :BondTypeList, "chemicalml/cml/aliases"
-    autoload :CellParameter, "chemicalml/cml/aliases"
-    autoload :ConditionList, "chemicalml/cml/aliases"
-    autoload :Crystal, "chemicalml/cml/aliases"
-    autoload :Definition, "chemicalml/cml/aliases"
-    autoload :Description, "chemicalml/cml/aliases"
-    autoload :Dimension, "chemicalml/cml/aliases"
-    autoload :Documentation, "chemicalml/cml/aliases"
-    autoload :Eigen, "chemicalml/cml/aliases"
-    autoload :Electron, "chemicalml/cml/aliases"
-    autoload :Fragment, "chemicalml/cml/aliases"
-    autoload :FragmentList, "chemicalml/cml/aliases"
-    autoload :Gradient, "chemicalml/cml/aliases"
-    autoload :Isotope, "chemicalml/cml/aliases"
-    autoload :IsotopeList, "chemicalml/cml/aliases"
-    autoload :Join, "chemicalml/cml/aliases"
-    autoload :Kpoint, "chemicalml/cml/aliases"
-    autoload :KpointList, "chemicalml/cml/aliases"
-    autoload :Lattice, "chemicalml/cml/aliases"
-    autoload :LatticeVector, "chemicalml/cml/aliases"
-    autoload :Length, "chemicalml/cml/aliases"
-    autoload :Line3, "chemicalml/cml/aliases"
-    autoload :Link, "chemicalml/cml/aliases"
-    autoload :Map, "chemicalml/cml/aliases"
-    autoload :Mechanism, "chemicalml/cml/aliases"
-    autoload :MechanismComponent, "chemicalml/cml/aliases"
-    autoload :MoleculeList, "chemicalml/cml/aliases"
-    autoload :Object, "chemicalml/cml/aliases"
-    autoload :Observation, "chemicalml/cml/aliases"
-    autoload :Particle, "chemicalml/cml/aliases"
-    autoload :Peak, "chemicalml/cml/aliases"
-    autoload :PeakGroup, "chemicalml/cml/aliases"
-    autoload :PeakList, "chemicalml/cml/aliases"
-    autoload :PeakStructure, "chemicalml/cml/aliases"
-    autoload :Plane3, "chemicalml/cml/aliases"
-    autoload :Point3, "chemicalml/cml/aliases"
-    autoload :Potential, "chemicalml/cml/aliases"
-    autoload :PotentialForm, "chemicalml/cml/aliases"
-    autoload :PotentialList, "chemicalml/cml/aliases"
-    autoload :ReactionScheme, "chemicalml/cml/aliases"
-    autoload :ReactionStep, "chemicalml/cml/aliases"
-    autoload :ReactionStepList, "chemicalml/cml/aliases"
-    autoload :ReactiveCentre, "chemicalml/cml/aliases"
-    autoload :Region, "chemicalml/cml/aliases"
-    autoload :Sample, "chemicalml/cml/aliases"
-    autoload :Spectator, "chemicalml/cml/aliases"
-    autoload :SpectatorList, "chemicalml/cml/aliases"
-    autoload :Spectrum, "chemicalml/cml/aliases"
-    autoload :SpectrumData, "chemicalml/cml/aliases"
-    autoload :SpectrumList, "chemicalml/cml/aliases"
-    autoload :Sphere3, "chemicalml/cml/aliases"
-    autoload :Stmml, "chemicalml/cml/aliases"
-    autoload :SubstanceList, "chemicalml/cml/aliases"
-    autoload :Symmetry, "chemicalml/cml/aliases"
-    autoload :System, "chemicalml/cml/aliases"
-    autoload :Table, "chemicalml/cml/aliases"
-    autoload :TableCell, "chemicalml/cml/aliases"
-    autoload :TableContent, "chemicalml/cml/aliases"
-    autoload :TableHeader, "chemicalml/cml/aliases"
-    autoload :TableHeaderCell, "chemicalml/cml/aliases"
-    autoload :TableRow, "chemicalml/cml/aliases"
-    autoload :TableRowList, "chemicalml/cml/aliases"
-    autoload :Torsion, "chemicalml/cml/aliases"
-    autoload :Transform3, "chemicalml/cml/aliases"
-    autoload :TransitionState, "chemicalml/cml/aliases"
-    autoload :Vector3, "chemicalml/cml/aliases"
-    autoload :Xaxis, "chemicalml/cml/aliases"
-    autoload :Yaxis, "chemicalml/cml/aliases"
-    autoload :ZMatrix, "chemicalml/cml/aliases"
+    autoload :Array,           'chemicalml/cml/aliases'
+    autoload :Atom,            'chemicalml/cml/aliases'
+    autoload :AtomArray,       'chemicalml/cml/aliases'
+    autoload :AtomParity,      'chemicalml/cml/aliases'
+    autoload :Bond,            'chemicalml/cml/aliases'
+    autoload :BondArray,       'chemicalml/cml/aliases'
+    autoload :BondStereo,      'chemicalml/cml/aliases'
+    autoload :Dictionary,      'chemicalml/cml/aliases'
+    autoload :DictionaryEntry, 'chemicalml/cml/aliases'
+    autoload :Document,        'chemicalml/cml/aliases'
+    autoload :Formula,         'chemicalml/cml/aliases'
+    autoload :Identifier,      'chemicalml/cml/aliases'
+    autoload :Label,           'chemicalml/cml/aliases'
+    autoload :List,            'chemicalml/cml/aliases'
+    autoload :Matrix,          'chemicalml/cml/aliases'
+    autoload :Metadata,        'chemicalml/cml/aliases'
+    autoload :MetadataList,    'chemicalml/cml/aliases'
+    autoload :Module,          'chemicalml/cml/aliases'
+    autoload :Molecule,        'chemicalml/cml/aliases'
+    autoload :Name,            'chemicalml/cml/aliases'
+    autoload :Parameter,       'chemicalml/cml/aliases'
+    autoload :ParameterList,   'chemicalml/cml/aliases'
+    autoload :Product,         'chemicalml/cml/aliases'
+    autoload :ProductList,     'chemicalml/cml/aliases'
+    autoload :Property,        'chemicalml/cml/aliases'
+    autoload :PropertyList,    'chemicalml/cml/aliases'
+    autoload :Reaction,        'chemicalml/cml/aliases'
+    autoload :ReactionList,    'chemicalml/cml/aliases'
+    autoload :Reactant,        'chemicalml/cml/aliases'
+    autoload :ReactantList,    'chemicalml/cml/aliases'
+    autoload :Scalar,          'chemicalml/cml/aliases'
+    autoload :Substance,       'chemicalml/cml/aliases'
+    autoload :Unit,            'chemicalml/cml/aliases'
+    autoload :UnitList,        'chemicalml/cml/aliases'
+    autoload :UnitType,        'chemicalml/cml/aliases'
+    autoload :UnitTypeList,    'chemicalml/cml/aliases'
+    autoload :Abundance, 'chemicalml/cml/aliases'
+    autoload :Action, 'chemicalml/cml/aliases'
+    autoload :ActionList, 'chemicalml/cml/aliases'
+    autoload :Amount, 'chemicalml/cml/aliases'
+    autoload :Angle, 'chemicalml/cml/aliases'
+    autoload :AnyCml, 'chemicalml/cml/aliases'
+    autoload :ArrayList, 'chemicalml/cml/aliases'
+    autoload :AtomSet, 'chemicalml/cml/aliases'
+    autoload :AtomType, 'chemicalml/cml/aliases'
+    autoload :AtomTypeList, 'chemicalml/cml/aliases'
+    autoload :AtomicBasisFunction, 'chemicalml/cml/aliases'
+    autoload :Band, 'chemicalml/cml/aliases'
+    autoload :BandList, 'chemicalml/cml/aliases'
+    autoload :BasisSet, 'chemicalml/cml/aliases'
+    autoload :BondSet, 'chemicalml/cml/aliases'
+    autoload :BondType, 'chemicalml/cml/aliases'
+    autoload :BondTypeList, 'chemicalml/cml/aliases'
+    autoload :CellParameter, 'chemicalml/cml/aliases'
+    autoload :ConditionList, 'chemicalml/cml/aliases'
+    autoload :Crystal, 'chemicalml/cml/aliases'
+    autoload :Definition, 'chemicalml/cml/aliases'
+    autoload :Description, 'chemicalml/cml/aliases'
+    autoload :Dimension, 'chemicalml/cml/aliases'
+    autoload :Documentation, 'chemicalml/cml/aliases'
+    autoload :Eigen, 'chemicalml/cml/aliases'
+    autoload :Electron, 'chemicalml/cml/aliases'
+    autoload :Fragment, 'chemicalml/cml/aliases'
+    autoload :FragmentList, 'chemicalml/cml/aliases'
+    autoload :Gradient, 'chemicalml/cml/aliases'
+    autoload :Isotope, 'chemicalml/cml/aliases'
+    autoload :IsotopeList, 'chemicalml/cml/aliases'
+    autoload :Join, 'chemicalml/cml/aliases'
+    autoload :Kpoint, 'chemicalml/cml/aliases'
+    autoload :KpointList, 'chemicalml/cml/aliases'
+    autoload :Lattice, 'chemicalml/cml/aliases'
+    autoload :LatticeVector, 'chemicalml/cml/aliases'
+    autoload :Length, 'chemicalml/cml/aliases'
+    autoload :Line3, 'chemicalml/cml/aliases'
+    autoload :Link, 'chemicalml/cml/aliases'
+    autoload :Map, 'chemicalml/cml/aliases'
+    autoload :Mechanism, 'chemicalml/cml/aliases'
+    autoload :MechanismComponent, 'chemicalml/cml/aliases'
+    autoload :MoleculeList, 'chemicalml/cml/aliases'
+    autoload :Object, 'chemicalml/cml/aliases'
+    autoload :Observation, 'chemicalml/cml/aliases'
+    autoload :Particle, 'chemicalml/cml/aliases'
+    autoload :Peak, 'chemicalml/cml/aliases'
+    autoload :PeakGroup, 'chemicalml/cml/aliases'
+    autoload :PeakList, 'chemicalml/cml/aliases'
+    autoload :PeakStructure, 'chemicalml/cml/aliases'
+    autoload :Plane3, 'chemicalml/cml/aliases'
+    autoload :Point3, 'chemicalml/cml/aliases'
+    autoload :Potential, 'chemicalml/cml/aliases'
+    autoload :PotentialForm, 'chemicalml/cml/aliases'
+    autoload :PotentialList, 'chemicalml/cml/aliases'
+    autoload :ReactionScheme, 'chemicalml/cml/aliases'
+    autoload :ReactionStep, 'chemicalml/cml/aliases'
+    autoload :ReactionStepList, 'chemicalml/cml/aliases'
+    autoload :ReactiveCentre, 'chemicalml/cml/aliases'
+    autoload :Region, 'chemicalml/cml/aliases'
+    autoload :Sample, 'chemicalml/cml/aliases'
+    autoload :Spectator, 'chemicalml/cml/aliases'
+    autoload :SpectatorList, 'chemicalml/cml/aliases'
+    autoload :Spectrum, 'chemicalml/cml/aliases'
+    autoload :SpectrumData, 'chemicalml/cml/aliases'
+    autoload :SpectrumList, 'chemicalml/cml/aliases'
+    autoload :Sphere3, 'chemicalml/cml/aliases'
+    autoload :Stmml, 'chemicalml/cml/aliases'
+    autoload :SubstanceList, 'chemicalml/cml/aliases'
+    autoload :Symmetry, 'chemicalml/cml/aliases'
+    autoload :System, 'chemicalml/cml/aliases'
+    autoload :Table, 'chemicalml/cml/aliases'
+    autoload :TableCell, 'chemicalml/cml/aliases'
+    autoload :TableContent, 'chemicalml/cml/aliases'
+    autoload :TableHeader, 'chemicalml/cml/aliases'
+    autoload :TableHeaderCell, 'chemicalml/cml/aliases'
+    autoload :TableRow, 'chemicalml/cml/aliases'
+    autoload :TableRowList, 'chemicalml/cml/aliases'
+    autoload :Torsion, 'chemicalml/cml/aliases'
+    autoload :Transform3, 'chemicalml/cml/aliases'
+    autoload :TransitionState, 'chemicalml/cml/aliases'
+    autoload :Vector3, 'chemicalml/cml/aliases'
+    autoload :Xaxis, 'chemicalml/cml/aliases'
+    autoload :Yaxis, 'chemicalml/cml/aliases'
+    autoload :ZMatrix, 'chemicalml/cml/aliases'
   end
 end

data/lib/chemicalml/context_configuration.rb

@@ -40,10 +40,16 @@ module Chemicalml
     # each class on the parent (schema) module, and register it. Pass
     # `except:` to skip specific elements (used by Schema 2.4 which
     # lacks `<module>`).
-    def register_elements!(except: [])
+    def register_elements!(except: [], only: nil)
       parent = version_parent_module
       skip = except.to_set
-      Chemicalml::Cml::Elements::ALL.each do |class_name, element_id|
+      source =
+        if only
+          Chemicalml::Cml::Elements::SCHEMA24_ONLY
+        else
+          Chemicalml::Cml::Elements::ALL
+        end
+      source.each do |class_name, element_id|
         next if skip.include?(class_name)
         next unless parent.const_defined?(class_name)
 
@@ -68,7 +74,9 @@ module Chemicalml
     def create_context(id:, registry: nil, fallback_to: [context_id])
       normalized_id = id.to_sym
       ensure_version_registered
-      Lutaml::Model::GlobalContext.unregister_context(normalized_id) if Lutaml::Model::GlobalContext.context(normalized_id)
+      if Lutaml::Model::GlobalContext.context(normalized_id)
+        Lutaml::Model::GlobalContext.unregister_context(normalized_id)
+      end
       Lutaml::Model::GlobalContext.create_context(
         id: normalized_id,
         registry: registry || Lutaml::Model::TypeRegistry.new,
@@ -116,7 +124,7 @@ module Chemicalml
     def version_parent_module
       return nil unless name
 
-      parent_const_name = name.split("::")[0..-2].join("::")
+      parent_const_name = name.split('::')[0..-2].join('::')
       return nil if parent_const_name.empty?
 
       Object.const_get(parent_const_name)

data/lib/chemicalml/convention/base.rb

@@ -27,13 +27,20 @@ module Chemicalml
 
       def register(constraint_class)
         constraints << constraint_class unless constraints.include?(constraint_class)
+        @coordinator = nil # invalidate cached coordinator
         self
       end
 
+      # Single-pass validation via Convention::Coordinator. The
+      # coordinator builds a role-dispatch table from the declared
+      # `applies_to` on each constraint, walks the tree once, and
+      # dispatches each node only to applicable constraints.
       def validate(document)
-        constraints.flat_map do |klass|
-          klass.new.check(document)
-        end
+        coordinator.validate(document)
+      end
+
+      def validate_report(document)
+        ValidationReport.new(validate(document))
       end
 
       def constraint_count
@@ -42,6 +49,13 @@ module Chemicalml
 
       def reset_constraints!
         @constraints = []
+        @coordinator = nil
+      end
+
+      private
+
+      def coordinator
+        @coordinator ||= Coordinator.new(constraints)
       end
     end
   end

data/lib/chemicalml/convention/cascade/constraints/reaction_scheme_must_have_content.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Cascade
+      module Constraints
+        # A `<reactionScheme>` MUST contain at least one
+        # `<reactionStepList>` or `<reaction>` child. An empty scheme
+        # carries no cascade information.
+        class ReactionSchemeMustHaveContent < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'A `<reactionScheme>` MUST contain at least one `<reactionStepList>` or `<reaction>` child. An empty scheme carries no cascade information.'
+          applies_to Chemicalml::Cml::Role::ReactionScheme
+
+          def check_node(node, _path)
+            return [] unless (node.reaction_step_lists || []).empty? &&
+                             (node.reactions || []).empty?
+
+            [violation(path: yield_path(node),
+                       message: "reactionScheme #{node.id.inspect} must contain at least one " \
+                                'reactionStepList or reaction')]
+          end
+
+          private
+
+          def yield_path(node)
+            id = node.node_id
+            id ? "reactionScheme[#{id}]" : 'reactionScheme'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/cascade/constraints/reaction_step_list_must_contain_steps.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Cascade
+      module Constraints
+        # A `<reactionStepList>` MUST contain at least one
+        # `<reactionStep>` child. An empty step list breaks the
+        # cascade chain.
+        class ReactionStepListMustContainSteps < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'A `<reactionStepList>` MUST contain at least one `<reactionStep>` child. An empty step list breaks the cascade chain.'
+          applies_to Chemicalml::Cml::Role::ReactionStepList
+
+          def check_node(node, _path)
+            return [] unless (node.reaction_steps || []).empty?
+
+            [violation(path: yield_path(node),
+                       message: 'reactionStepList must contain at least one reactionStep')]
+          end
+
+          private
+
+          def yield_path(node)
+            id = node.node_id
+            id ? "reactionStepList[#{id}]" : 'reactionStepList'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/cascade/constraints/reaction_step_must_have_reaction_or_lists.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Cascade
+      module Constraints
+        # A `<reactionStep>` MUST contain either a `<reaction>` child
+        # or explicit `<reactantList>` + `<productList>` children. An
+        # empty step is a dead-end in the cascade.
+        class ReactionStepMustHaveReactionOrLists < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'A `<reactionStep>` MUST contain either a `<reaction>` child or explicit `<reactantList>` + `<productList>` children. An empty step is a dead-end in the cascade.'
+          applies_to Chemicalml::Cml::Role::ReactionStep
+
+          def check_node(node, _path)
+            return [] if node.reaction
+            return [] if node.reactant_list && node.product_list
+
+            [violation(path: yield_path(node),
+                       message: "reactionStep #{node.id.inspect} must contain a reaction " \
+                                'or both reactantList and productList')]
+          end
+
+          private
+
+          def yield_path(node)
+            id = node.node_id
+            id ? "reactionStep[#{id}]" : 'reactionStep'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/cascade/constraints/reactive_centre_atom_refs_should_be_present.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Cascade
+      module Constraints
+        # A `<reactiveCentre>` SHOULD declare its `atomRefs` attribute.
+        # Without atom references the reactive centre is
+        # indistinguishable from a placeholder. Warning severity —
+        # consumers may use `ref` or external context instead.
+        class ReactiveCentreAtomRefsShouldBePresent < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'A `<reactiveCentre>` SHOULD declare its `atomRefs` attribute. Without atom references the reactive centre is indistinguishable from a placeholder. Warning severity —'
+          applies_to Chemicalml::Cml::Role::ReactiveCentre
+
+          def check_node(node, _path)
+            return [] unless node.atomRefs.to_s.empty?
+
+            [violation(path: yield_path(node),
+                       message: "reactiveCentre #{node.id.inspect} should declare atomRefs " \
+                                'to identify the reacting atoms',
+                       severity: :warning)]
+          end
+
+          private
+
+          def yield_path(node)
+            id = node.node_id
+            id ? "reactiveCentre[#{id}]" : 'reactiveCentre'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/cascade/constraints.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Cascade
+      module Constraints
+        autoload :ReactionSchemeMustHaveContent,
+                 'chemicalml/convention/cascade/constraints/reaction_scheme_must_have_content'
+        autoload :ReactionStepListMustContainSteps,
+                 'chemicalml/convention/cascade/constraints/reaction_step_list_must_contain_steps'
+        autoload :ReactionStepMustHaveReactionOrLists,
+                 'chemicalml/convention/cascade/constraints/reaction_step_must_have_reaction_or_lists'
+        autoload :ReactiveCentreAtomRefsShouldBePresent,
+                 'chemicalml/convention/cascade/constraints/reactive_centre_atom_refs_should_be_present'
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/cascade.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    # The Cascade convention. A chemicalml-specific convention for CML
+    # reaction cascades — multi-step reaction networks encoded via
+    # `<reactionScheme>`, `<reactionStepList>`, `<reactionStep>`,
+    # `<reaction>`, and `<reactiveCentre>`.
+    #
+    # Upstream CML does not publish a dedicated cascade convention; the
+    # wire elements exist in the XSD but no constraints guard their
+    # well-formedness. This convention covers the gaps:
+    #
+    # - reactionScheme MUST contain at least one reactionStepList or
+    #   reaction (an empty scheme carries no cascade)
+    # - reactionStepList MUST contain at least one reactionStep
+    # - reactionStep MUST contain a reaction or explicit reactant/product
+    #   lists (an empty step is a dead-end in the cascade)
+    # - reactiveCentre atomRefs SHOULD be parseable atom references
+    #   (warning — gracefully degrades when context is missing)
+    module Cascade
+      extend Base
+
+      autoload :Constraints, 'chemicalml/convention/cascade/constraints'
+
+      QNAME = 'convention:cascade'
+      NAMESPACE_URI = "#{Chemicalml::Convention::CONVENTION_NAMESPACE}cascade".freeze
+
+      def self.qname
+        QNAME
+      end
+
+      def self.namespace_uri
+        NAMESPACE_URI
+      end
+
+      register Constraints::ReactionSchemeMustHaveContent
+      register Constraints::ReactionStepListMustContainSteps
+      register Constraints::ReactionStepMustHaveReactionOrLists
+      register Constraints::ReactiveCentreAtomRefsShouldBePresent
+    end
+  end
+end

data/lib/chemicalml/convention/compchem/constraints/array_rules.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Compchem
+      module Constraints
+        # CompChem `array` value-container rules: MUST have `size`
+        # attribute (≥ 1); `dataType` MUST be integer or double;
+        # MUST have `units`.
+        class ArrayRules < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'CompChem `array` value-container rules: MUST have `size` attribute (≥ 1); `dataType` MUST be integer or double; MUST have `units`.'
+          applies_to Chemicalml::Cml::Role::Array
+          include ModulePredicates
+
+          ALLOWED_TYPES = %w[xsd:integer xsd:double].freeze
+
+          def check_node(node, path)
+            violations = []
+            if node.size.to_s.empty? || node.size.to_i < 1
+              violations << violation(path: path.join('/'),
+                                      message: 'array must have a size attribute (minimum 1)')
+            end
+            unless ALLOWED_TYPES.include?(node.data_type.to_s)
+              violations << violation(path: path.join('/'),
+                                      message: 'array dataType must be xsd:integer or xsd:double ' \
+                                               "(got #{node.data_type.inspect})")
+            end
+            if node.units.to_s.empty?
+              violations << violation(path: path.join('/'),
+                                      message: 'array must have units (even if dimensionless)')
+            end
+            violations
+          end
+
+          private
+
+          def array?(node)
+            node.is_a?(Chemicalml::Cml::Role::Array)
+          end
+        end
+      end
+    end
+  end
+end