chemicalml 0.2.1 → 0.4.0

data/lib/chemicalml/convention/dictionary/constraints/entry_must_contain_definition.rb

@@ -8,9 +8,11 @@ module Chemicalml
         # element. The schema allows it as a string; this constraint
         # enforces presence.
         class EntryMustContainDefinition < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'An `<entry>` MUST contain a single `definition` child element. '
           applies_to Chemicalml::Cml::Role::DictionaryEntry
           def check_node(node, path)
-            return [] unless node.definition.to_s.strip.empty?
+            definition = node.definition
+            return [] if definition_contained?(definition)
 
             [violation(path: path.join('/'),
                        message: "entry #{node.id.inspect} must contain a single definition child")]
@@ -18,6 +20,18 @@ module Chemicalml
 
           private
 
+          # CML allows the definition content as plain text or as
+          # rich text (<xhtml:p> paragraphs); the wire class types it
+          # structured, but a plain string remains valid at
+          # construction.
+          def definition_contained?(definition)
+            return false if definition.nil?
+            return !definition.to_s.strip.empty? if definition.is_a?(String)
+
+            !(definition.content.to_s.strip.empty? &&
+              Array(definition.paragraphs).empty?)
+          end
+
           def entry?(node)
             node.is_a?(Chemicalml::Cml::Role::DictionaryEntry)
           end

data/lib/chemicalml/convention/dictionary/constraints/entry_must_have_id_and_term.rb

@@ -7,9 +7,9 @@ module Chemicalml
         # Every entry MUST have an `id` and a `term` attribute per the
         # dictionary convention.
         class EntryMustHaveIdAndTerm < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'Every entry MUST have an `id` and a `term` attribute per the dictionary convention.'
           applies_to Chemicalml::Cml::Role::DictionaryEntry
           def check_node(node, path)
-
             violations = []
             if node.id.to_s.empty?
               violations << violation(path: path.join('/'),

data/lib/chemicalml/convention/dictionary/constraints/entry_must_have_unit_type.rb

@@ -9,6 +9,7 @@ module Chemicalml
         # of a program) should reference `none` in the standard CML
         # unitType dictionary.
         class EntryMustHaveUnitType < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'An `<entry>` MUST have a `unitType` attribute. Entries describing concepts that should not have units (e.g. name of a program) should reference `none` in the standard CML'
           applies_to Chemicalml::Cml::Role::DictionaryEntry
           def check_node(node, path)
             return [] unless node.unit_type.to_s.empty?

data/lib/chemicalml/convention/dictionary/constraints/entry_units_co_constraints.rb

@@ -10,11 +10,11 @@ module Chemicalml
         # - If `unitType` is `none`, `units` MUST be present and point
         #   to `http://www.xml-cml.org/unit/si#none`.
         class EntryUnitsCoConstraints < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'Co-constraint between `unitType` and `units`: - If `unitType` is `unknown`, `units` MUST NOT be present. - If `unitType` is `none`, `units` MUST be present and point'
           applies_to Chemicalml::Cml::Role::DictionaryEntry
           NONE_UNITS = 'http://www.xml-cml.org/unit/si#none'
 
           def check_node(node, path)
-
             unit_type = node.unit_type.to_s
             units = node.units.to_s
             violations = []

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

@@ -5,21 +5,21 @@ module Chemicalml
     module Dictionary
       module Constraints
         autoload :EntryMustHaveIdAndTerm,
-                 "chemicalml/convention/dictionary/constraints/entry_must_have_id_and_term"
+                 'chemicalml/convention/dictionary/constraints/entry_must_have_id_and_term'
         autoload :EntryIdsUniqueWithinDictionary,
-                 "chemicalml/convention/dictionary/constraints/entry_ids_unique_within_dictionary"
+                 'chemicalml/convention/dictionary/constraints/entry_ids_unique_within_dictionary'
         autoload :DictionaryMustHaveNamespace,
-                 "chemicalml/convention/dictionary/constraints/dictionary_must_have_namespace"
+                 'chemicalml/convention/dictionary/constraints/dictionary_must_have_namespace'
         autoload :DictionaryNamespaceShouldEndWithSlashOrHash,
-                 "chemicalml/convention/dictionary/constraints/dictionary_namespace_should_end_with_slash_or_hash"
+                 'chemicalml/convention/dictionary/constraints/dictionary_namespace_should_end_with_slash_or_hash'
         autoload :EntryMustContainDefinition,
-                 "chemicalml/convention/dictionary/constraints/entry_must_contain_definition"
+                 'chemicalml/convention/dictionary/constraints/entry_must_contain_definition'
         autoload :EntryIdMustMatchPattern,
-                 "chemicalml/convention/dictionary/constraints/entry_id_must_match_pattern"
+                 'chemicalml/convention/dictionary/constraints/entry_id_must_match_pattern'
         autoload :EntryMustHaveUnitType,
-                 "chemicalml/convention/dictionary/constraints/entry_must_have_unit_type"
+                 'chemicalml/convention/dictionary/constraints/entry_must_have_unit_type'
         autoload :EntryUnitsCoConstraints,
-                 "chemicalml/convention/dictionary/constraints/entry_units_co_constraints"
+                 'chemicalml/convention/dictionary/constraints/entry_units_co_constraints'
       end
     end
   end

data/lib/chemicalml/convention/dictionary.rb

@@ -8,9 +8,9 @@ module Chemicalml
     module Dictionary
       extend Base
 
-      autoload :Constraints, "chemicalml/convention/dictionary/constraints"
+      autoload :Constraints, 'chemicalml/convention/dictionary/constraints'
 
-      QNAME = "convention:dictionary".freeze
+      QNAME = 'convention:dictionary'
       NAMESPACE_URI = "#{Chemicalml::Convention::CONVENTION_NAMESPACE}dictionary".freeze
 
       def self.qname

data/lib/chemicalml/convention/molecular/constraints/atom_array_must_be_child_of_molecule_or_formula.rb

@@ -10,6 +10,7 @@ module Chemicalml
         # when visiting a non-molecule/non-formula node, look for
         # misplaced atomArray children.
         class AtomArrayMustBeChildOfMoleculeOrFormula < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = "Molecular convention: `<atomArray>` MUST be a child of `<molecule>` or `<formula>`. Any other parent is invalid. Checked from the parent's perspective during the walk —"
           def check_node(node, path)
             return [] if allowed_parent?(node)
 

data/lib/chemicalml/convention/molecular/constraints/atom_array_must_contain_atoms.rb

@@ -4,15 +4,17 @@ module Chemicalml
   module Convention
     module Molecular
       module Constraints
-        # `atomArray` MUST contain at least one `atom` child per the
-        # molecular convention.
+        # `atomArray` MUST contain at least one atom. The atoms can
+        # be in the child form (`<atom>` elements) or the parallel-array
+        # form (`atomID` attribute with whitespace-separated ids).
         class AtomArrayMustContainAtoms < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = '`atomArray` MUST contain at least one atom. The atoms can be in the child form (`<atom>` elements) or the parallel-array form (`atomID` attribute with whitespace-separated ids).'
           applies_to Chemicalml::Cml::Role::Molecule
           def check_node(node, path)
             return [] unless node.atom_array
 
-            atoms = node.atom_array.atoms || []
-            return [] unless atoms.empty?
+            aa = node.atom_array
+            return [] if has_child_atoms?(aa) || has_parallel_array_atoms?(aa)
 
             [violation(path: path.empty? ? 'molecule' : path.join('/'),
                        message: 'atomArray must contain at least one atom')]
@@ -20,8 +22,15 @@ module Chemicalml
 
           private
 
-          def molecule?(node)
-            node.is_a?(Chemicalml::Cml::Role::Molecule)
+          def has_child_atoms?(atom_array)
+            !(atom_array.atoms || []).empty?
+          end
+
+          # Parallel-array form is identified by a non-empty atomIDArray
+          # attribute — the XSD marks it as mandatory when atoms are
+          # encoded as parallel arrays.
+          def has_parallel_array_atoms?(atom_array)
+            !atom_array.atom_id_array.to_s.strip.empty?
           end
         end
       end

data/lib/chemicalml/convention/molecular/constraints/atom_coordinates_must_be_paired.rb

@@ -5,9 +5,9 @@ module Chemicalml
     module Molecular
       module Constraints
         class AtomCoordinatesMustBePaired < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = '<atom> 2D coordinates (x2, y2) must appear together; 3D coordinates (x3, y3, z3) must appear together.'
           applies_to Chemicalml::Cml::Role::Atom
           def check_node(node, path)
-
             violations = []
             has_x2 = !node.x2.to_s.empty?
             has_y2 = !node.y2.to_s.empty?

data/lib/chemicalml/convention/molecular/constraints/atom_element_type_should_be_in_periodic_table.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # An `<atom>`'s `elementType` attribute SHOULD be one of the
+        # XSD elementTypeType enum values (the periodic table plus
+        # the special "Du" dummy and "R" group placeholder). Warns
+        # on typos like "Carb" or "X".
+        class AtomElementTypeShouldBeInPeriodicTable < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = "An `<atom>`'s `elementType` attribute SHOULD be one of the XSD elementTypeType enum values (the periodic table plus the special \"Du\" dummy and \"R\" group placeholder). Warns"
+          include Chemicalml::Cml::Enums
+
+          applies_to Chemicalml::Cml::Role::Atom
+
+          def check_node(node, _path)
+            et = node.element_type.to_s.strip
+            return [] if et.empty?
+            return [] if ELEMENT_TYPE_VALUES.include?(et)
+
+            [violation(path: yield_path(node),
+                       message: "atom #{node.id.inspect} elementType #{et.inspect} should be one of " \
+                                "the periodic table symbols (e.g. C, H, O, Fe) — got #{et.inspect}",
+                       severity: :warning,
+                       value: et)]
+          end
+
+          private
+
+          def yield_path(node)
+            id = node.node_id
+            id ? "atom[#{id}]" : 'atom'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/molecular/constraints/atom_id_must_match_pattern.rb

@@ -5,11 +5,11 @@ module Chemicalml
     module Molecular
       module Constraints
         class AtomIdMustMatchPattern < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = "An <atom>'s id attribute SHOULD start with a letter and contain only letters, digits, dot, hyphen, or underscore."
           applies_to Chemicalml::Cml::Role::Atom
           ID_PATTERN = /\A[A-Za-z][A-Za-z0-9._-]*\z/
 
           def check_node(node, path)
-
             id = node.id.to_s
             return [] if id.empty?
             return [] if id.match?(ID_PATTERN)
@@ -17,7 +17,8 @@ module Chemicalml
             [violation(path: path.empty? ? 'atom' : path.join('/'),
                        message: "atom id #{id.inspect} must start with a letter and " \
                                 'contain only letters, digits, dot, hyphen, or underscore',
-                       severity: :warning)]
+                       severity: :warning,
+                       value: id)]
           end
         end
       end

data/lib/chemicalml/convention/molecular/constraints/atom_ids_unique_within_molecule.rb

@@ -7,6 +7,7 @@ module Chemicalml
         # Atom ids MUST be unique within the eldest containing molecule
         # per the molecular convention.
         class AtomIdsUniqueWithinMolecule < Chemicalml::Convention::Constraint::DocumentConstraint
+          self.description = 'Atom ids MUST be unique within the eldest containing molecule per the molecular convention.'
           def check(document)
             violations = []
             walk_nodes(document) do |node, path|

data/lib/chemicalml/convention/molecular/constraints/atom_must_have_element_type.rb

@@ -5,9 +5,9 @@ module Chemicalml
     module Molecular
       module Constraints
         class AtomMustHaveElementType < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'An <atom> inside an atomArray in a molecule MUST have an elementType attribute.'
           applies_to Chemicalml::Cml::Role::Atom
           def check_node(node, path)
-
             return [] unless node.element_type.to_s.empty?
 
             [violation(path: path.empty? ? 'atom' : path.join('/'),

data/lib/chemicalml/convention/molecular/constraints/atom_must_have_id.rb

@@ -6,8 +6,9 @@ module Chemicalml
       module Constraints
         class AtomMustHaveId < Chemicalml::Convention::Constraint::NodeConstraint
           applies_to Chemicalml::Cml::Role::Atom
-          def check_node(node, path)
+          self.description = 'An <atom> inside an atomArray in a molecule MUST have an id attribute.'
 
+          def check_node(node, path)
             return [] unless node.id.to_s.empty?
 
             [violation(path: path.empty? ? 'atom' : path.join('/'),

data/lib/chemicalml/convention/molecular/constraints/atom_parity_atom_refs4_should_be_distinct.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # An `<atomParity>` element's `atomRefs4` attribute SHOULD
+        # reference four distinct atom ids around a chiral center.
+        # Duplicate ids make the parity descriptor meaningless.
+        # Warning severity.
+        class AtomParityAtomRefs4ShouldBeDistinct < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = "An `<atomParity>` element's `atomRefs4` attribute SHOULD reference four distinct atom ids around a chiral center. Duplicate ids make the parity descriptor meaningless."
+          applies_to Chemicalml::Cml::Role::AtomParity
+
+          def check_node(node, _path)
+            ids = parse_refs(node.atom_refs4)
+            return [] if ids.size < 2
+            return [] if ids.uniq.size == ids.size
+
+            duplicates = ids.group_by { |i| i }.select { |_, v| v.size > 1 }.keys
+            [violation(path: yield_path(node),
+                       message: "atomParity #{node.id.inspect} atomRefs4 should reference four distinct atoms; " \
+                                "duplicate ids: #{duplicates.inspect}",
+                       severity: :warning,
+                       value: node.atom_refs4)]
+          end
+
+          private
+
+          def yield_path(node)
+            id = node.node_id
+            id ? "atomParity[#{id}]" : 'atomParity'
+          end
+
+          def parse_refs(value)
+            return [] if value.nil?
+
+            value.to_s.split(/\s+/).reject(&:empty?)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/molecular/constraints/atom_parity_should_include_parent_atom.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # Walks the document and warns on `<atomParity>` elements
+        # whose parent `<atom>`'s id does not appear in atomRefs4.
+        # The CML convention requires the parent atom to be one of
+        # the four references (otherwise the parity is meaningless).
+        #
+        # DocumentConstraint because it needs to walk the tree and
+        # track parent-child relationships.
+        class AtomParityShouldIncludeParentAtom < Chemicalml::Convention::Constraint::DocumentConstraint
+          self.description = "Walks the document and warns on `<atomParity>` elements whose parent `<atom>`'s id does not appear in atomRefs4. The CML convention requires the parent atom to be one of"
+          def check(document)
+            violations = []
+            visit_with_parent(document, nil) do |node, parent|
+              next unless atom_parity?(node)
+              next unless atom?(parent)
+
+              refs = parse_refs(node.atom_refs4)
+              next if refs.empty?
+              next if refs.include?(parent.id)
+
+              violations << violation(
+                path: "atom[#{parent.id}]/atomParity",
+                message: "atomParity atomRefs4 #{refs.inspect} should include the parent atom id " \
+                         "#{parent.id.inspect}",
+                severity: :warning,
+                value: node.atom_refs4
+              )
+            end
+            violations
+          end
+
+          private
+
+          def visit_with_parent(node, parent, &block)
+            return unless node.is_a?(Lutaml::Model::Serializable)
+
+            block.call(node, parent)
+            return unless node.is_a?(Chemicalml::Cml::Visitable)
+
+            node.wire_children.each { |c| visit_with_parent(c, node, &block) }
+          end
+
+          def atom_parity?(node)
+            node.is_a?(Chemicalml::Cml::Role::AtomParity)
+          end
+
+          def atom?(node)
+            node.is_a?(Chemicalml::Cml::Role::Atom)
+          end
+
+          def parse_refs(value)
+            return [] if value.nil?
+
+            value.to_s.split(/\s+/).reject(&:empty?)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/molecular/constraints/bond_array_must_be_child_of_molecule.rb

@@ -7,6 +7,7 @@ module Chemicalml
         # Molecular convention: `<bondArray>` MUST be a child of
         # `<molecule>`. Any other parent is invalid.
         class BondArrayMustBeChildOfMolecule < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'Molecular convention: `<bondArray>` MUST be a child of `<molecule>`. Any other parent is invalid.'
           def check_node(node, path)
             return [] if molecule?(node)
 

data/lib/chemicalml/convention/molecular/constraints/bond_atom_refs2_should_be_distinct.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # A `<bond>`'s `atomRefs2` SHOULD reference two distinct atom
+        # ids. A self-bond (`a1 a1`) is chemically meaningless.
+        # Warning severity — there are edge cases in non-classical
+        # chemistry (e.g. agostic interactions).
+        class BondAtomRefs2ShouldBeDistinct < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = "A `<bond>`'s `atomRefs2` SHOULD reference two distinct atom ids. A self-bond (`a1 a1`) is chemically meaningless. Warning severity — there are edge cases in non-classical"
+          applies_to Chemicalml::Cml::Role::Bond
+
+          def check_node(node, _path)
+            ids = parse_refs(node.atom_refs2)
+            return [] if ids.size < 2
+            return [] if ids.uniq.size == ids.size
+
+            duplicates = ids.group_by { |i| i }.select { |_, v| v.size > 1 }.keys
+            [violation(path: yield_path(node),
+                       message: "bond #{node.id.inspect} atomRefs2 should reference two distinct atoms; " \
+                                "duplicate ids: #{duplicates.inspect}",
+                       severity: :warning,
+                       value: node.atom_refs2)]
+          end
+
+          private
+
+          def yield_path(node)
+            id = node.node_id
+            id ? "bond[#{id}]" : 'bond'
+          end
+
+          def parse_refs(value)
+            return [] if value.nil?
+
+            value.to_s.split(/\s+/).reject(&:empty?)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/molecular/constraints/bond_id_should_match_pattern.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # A `<bond>`'s `id` attribute SHOULD match the XSD idType
+        # pattern (letter start, alphanumeric body with dots/dashes).
+        # Warning severity.
+        class BondIdShouldMatchPattern < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = "A `<bond>`'s `id` attribute SHOULD match the XSD idType pattern (letter start, alphanumeric body with dots/dashes). Warning severity."
+          include Chemicalml::Cml::Patterns
+
+          applies_to Chemicalml::Cml::Role::Bond
+
+          def check_node(node, _path)
+            id = node.id.to_s
+            return [] if id.empty?
+            return [] if id.match?(/\A#{ID_PATTERN.source}\z/)
+
+            [violation(path: yield_path(node),
+                       message: "bond id #{id.inspect} should match the idType pattern " \
+                                '(letter start, alphanumeric body with . and -)',
+                       severity: :warning,
+                       value: id)]
+          end
+
+          private
+
+          def yield_path(node)
+            id = node.node_id
+            id ? "bond[#{id}]" : 'bond'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/molecular/constraints/bond_ids_unique_within_molecule.rb

@@ -8,6 +8,7 @@ module Chemicalml
         # the eldest containing molecule. Mirrors the existing
         # `AtomIdsUniqueWithinMolecule` constraint for bonds.
         class BondIdsUniqueWithinMolecule < Chemicalml::Convention::Constraint::DocumentConstraint
+          self.description = 'Molecular convention: a `<bond>` `id` MUST be unique within the eldest containing molecule. Mirrors the existing `AtomIdsUniqueWithinMolecule` constraint for bonds.'
           def check(document)
             violations = []
             walk_nodes(document) do |node, path|

data/lib/chemicalml/convention/molecular/constraints/bond_must_have_atom_refs2.rb

@@ -5,9 +5,9 @@ module Chemicalml
     module Molecular
       module Constraints
         class BondMustHaveAtomRefs2 < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'A <bond> MUST have an atomRefs2 attribute referencing two distinct atoms in the same molecule.'
           applies_to Chemicalml::Cml::Role::Bond
           def check_node(node, path)
-
             return [] unless node.atom_refs2.to_s.strip.empty?
 
             [violation(path: path.empty? ? 'bond' : path.join('/'),

data/lib/chemicalml/convention/molecular/constraints/bond_must_have_order.rb

@@ -6,8 +6,9 @@ module Chemicalml
       module Constraints
         class BondMustHaveOrder < Chemicalml::Convention::Constraint::NodeConstraint
           applies_to Chemicalml::Cml::Role::Bond
-          def check_node(node, path)
+          self.description = 'A <bond> MUST have an order attribute (S/D/T/A recommended).'
 
+          def check_node(node, path)
             return [] unless node.order.to_s.strip.empty?
 
             [violation(path: path.empty? ? 'bond' : path.join('/'),

data/lib/chemicalml/convention/molecular/constraints/bond_must_reference_atoms_in_same_molecule.rb

@@ -7,6 +7,7 @@ module Chemicalml
         # Bonds MUST reference atoms within the same parent molecule
         # per the molecular convention.
         class BondMustReferenceAtomsInSameMolecule < Chemicalml::Convention::Constraint::DocumentConstraint
+          self.description = 'Bonds MUST reference atoms within the same parent molecule per the molecular convention.'
           def check(document)
             violations = []
             walk_nodes(document) do |node, path|

data/lib/chemicalml/convention/molecular/constraints/bond_order_other_must_have_dict_ref.rb

@@ -9,6 +9,7 @@ module Chemicalml
         # the order semantics. The warning-level "should not be
         # numeric" rule is separate; this is the hard error.
         class BondOrderOtherMustHaveDictRef < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'Molecular convention: `<bond>` with `order="other"` MUST have a `dictRef` pointing to the dictionary that defines the order semantics. The warning-level "should not be'
           applies_to Chemicalml::Cml::Role::Bond
           def check_node(node, path)
             return [] unless node.order.to_s.downcase == 'other'

data/lib/chemicalml/convention/molecular/constraints/bond_order_should_be_in_enum.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # A `<bond>`'s `order` attribute SHOULD be one of the XSD
+        # orderType enum values: S/1/D/2/T/3/A/unknown/other.
+        # Warning severity — CML permits extension values via
+        # convention-specific dicts.
+        class BondOrderShouldBeInEnum < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = "A `<bond>`'s `order` attribute SHOULD be one of the XSD orderType enum values: S/1/D/2/T/3/A/unknown/other. Warning severity — CML permits extension values via"
+          include Chemicalml::Cml::Enums
+
+          applies_to Chemicalml::Cml::Role::Bond
+
+          def check_node(node, _path)
+            order = node.order.to_s
+            return [] if order.empty?
+            return [] if ORDER_VALUES.include?(order)
+
+            [violation(path: yield_path(node),
+                       message: "bond #{node.id.inspect} order #{order.inspect} should be one of " \
+                                "#{ORDER_VALUES.to_a.sort.inspect}",
+                       severity: :warning,
+                       value: order)]
+          end
+
+          private
+
+          def yield_path(node)
+            id = node.node_id
+            id ? "bond[#{id}]" : 'bond'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/molecular/constraints/bond_order_should_not_be_numeric.rb

@@ -5,11 +5,11 @@ module Chemicalml
     module Molecular
       module Constraints
         class BondOrderShouldNotBeNumeric < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = "A <bond>'s order attribute SHOULD be one of S/D/T/Q/A or 'other' (numeric values are not recommended)."
           applies_to Chemicalml::Cml::Role::Bond
           VALID_ORDERS = %w[S D T Q A other].freeze
 
           def check_node(node, path)
-
             order = node.order.to_s
             return [] if order.empty?
 

data/lib/chemicalml/convention/molecular/constraints/bond_stereo_atom_refs4_should_be_distinct.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Chemicalml
+  module Convention
+    module Molecular
+      module Constraints
+        # A `<bondStereo>` with `atomRefs4` (used by C/T stereo)
+        # SHOULD reference four distinct atom ids. Duplicate ids make
+        # the stereo descriptor meaningless. Warning severity.
+        class BondStereoAtomRefs4ShouldBeDistinct < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'A `<bondStereo>` with `atomRefs4` (used by C/T stereo) SHOULD reference four distinct atom ids. Duplicate ids make the stereo descriptor meaningless. Warning severity.'
+          applies_to Chemicalml::Cml::Role::BondStereo
+
+          def check_node(node, _path)
+            ids = parse_refs(node.atom_refs4)
+            return [] if ids.size < 2
+            return [] if ids.uniq.size == ids.size
+
+            duplicates = ids.group_by { |i| i }.select { |_, v| v.size > 1 }.keys
+            [violation(path: yield_path(node),
+                       message: "bondStereo #{node.id.inspect} atomRefs4 should reference four distinct atoms; " \
+                                "duplicate ids: #{duplicates.inspect}",
+                       severity: :warning,
+                       value: node.atom_refs4)]
+          end
+
+          private
+
+          def yield_path(node)
+            id = node.node_id
+            id ? "bondStereo[#{id}]" : 'bondStereo'
+          end
+
+          def parse_refs(value)
+            return [] if value.nil?
+
+            value.to_s.split(/\s+/).reject(&:empty?)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chemicalml/convention/molecular/constraints/bond_stereo_cis_trans_must_have_atom_refs4.rb

@@ -7,11 +7,11 @@ module Chemicalml
         # Molecular convention: `<bondStereo>` value C (cis) or T
         # (trans) MUST have `atomRefs4` and MUST NOT have `atomRefs2`.
         class BondStereoCisTransMustHaveAtomRefs4 < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'Molecular convention: `<bondStereo>` value C (cis) or T (trans) MUST have `atomRefs4` and MUST NOT have `atomRefs2`.'
           applies_to Chemicalml::Cml::Role::BondStereo
           CIS_TRANS_VALUES = %w[C T].freeze
 
           def check_node(node, path)
-
             value = node.content.to_s.upcase
             return [] unless CIS_TRANS_VALUES.include?(value)
 

data/lib/chemicalml/convention/molecular/constraints/bond_stereo_other_must_have_dict_ref.rb

@@ -8,6 +8,7 @@ module Chemicalml
         # MUST have a `dictRef` pointing to the convention that
         # defines the stereo semantics.
         class BondStereoOtherMustHaveDictRef < Chemicalml::Convention::Constraint::NodeConstraint
+          self.description = 'Molecular convention: `<bondStereo>` with value `other` MUST have a `dictRef` pointing to the convention that defines the stereo semantics.'
           applies_to Chemicalml::Cml::Role::BondStereo
           def check_node(node, path)
             return [] unless node.content.to_s.downcase == 'other'