openehr 1.3.0 → 2.0.0

data/lib/openehr/am/archetype/constraint_model.rb

@@ -37,6 +37,19 @@ module OpenEHR
           def parent_path
             parent ? parent.path : ''
           end
+
+          # Nil-safe interval subset check shared by the
+          # occurrences/existence/cardinality conformance rules: an
+          # unconstrained parent (nil) accepts anything, an
+          # unconstrained child (nil) only conforms to an
+          # unconstrained parent, and otherwise the child interval
+          # must be a genuine subset of the parent's.
+          def interval_conforms_to?(mine, other)
+            return true if other.nil?
+            return false if mine.nil?
+
+            mine.subset_of?(other)
+          end
         end
 
         class Cardinality
@@ -118,8 +131,30 @@ module OpenEHR
             @rm ||= OpenEHR::RM::Factory.create(rm_type_name, params)
           end
 
+          # Whether this (potentially specialised) node is a legal
+          # redefinition of +other+, the corresponding node in the
+          # flat parent archetype: same node_id lineage (at0001.1
+          # specialises at0001), same rm_type_name (subtype checking
+          # is deferred until the RM type-name helper lands), and
+          # occurrences no wider than the parent's.
+          def node_conforms_to?(other)
+            return false if other.nil?
+
+            node_id_conforms_to?(other.node_id) &&
+              rm_type_name == other.rm_type_name &&
+              interval_conforms_to?(occurrences, other.occurrences)
+          end
+
           private
 
+          def node_id_conforms_to?(other_node_id)
+            return true if node_id == other_node_id
+            return false if node_id.nil? || other_node_id.nil?
+
+            node_id.start_with?(other_node_id + '.') &&
+              node_id[(other_node_id.length + 1)..-1] =~ /\A\d+(\.\d+)*\z/
+          end
+
           def calculate_path
             path_left_part = parent_path
             path_left_part = '/' if path_left_part == ''
@@ -177,6 +212,16 @@ module OpenEHR
             @path || calculate_path
           end
 
+          # Whether this (potentially specialised) attribute node is
+          # a legal redefinition of +other+: same rm_attribute_name
+          # and an existence no wider than the parent's.
+          def node_conforms_to?(other)
+            return false if other.nil?
+
+            rm_attribute_name == other.rm_attribute_name &&
+              interval_conforms_to?(existence, other.existence)
+          end
+
           private
 
           def calculate_path
@@ -224,9 +269,9 @@ module OpenEHR
             return item.nil?
           end
 
-          %w(assumed_value assumed_value= has_assumed_value? default_value 
-            any_allowed?, valid_value?).each do |m| 
-            define_method(m) do |*args| 
+          %w(assumed_value assumed_value= has_assumed_value? default_value
+            valid_value?).each do |m|
+            define_method(m) do |*args|
               self.item.send(m, *args) if !self.item.nil?
             end
           end
@@ -263,6 +308,175 @@ module OpenEHR
           def any_allowed?
             return (@attributes.nil? or @attributes.empty?)
           end
+
+          # Recursively checks +value+ (an RM instance) against this
+          # node's constraints: rm_type_name conformance (RM subtypes
+          # allowed), archetype_node_id (when this node specifies
+          # one), then each attribute's existence/cardinality and its
+          # children constraints. ArchetypeSlot/ArchetypeInternalRef/
+          # ConstraintRef children are accepted permissively (v1 does
+          # not resolve slot-fillers or internal references).
+          def valid_value?(value)
+            return false if value.nil?
+            return false unless node_id_matches?(value)
+            return false unless OpenEHR::RM.subtype_of?(value, rm_type_name)
+            return true if any_allowed?
+
+            attributes.all? { |attribute| attribute_conforms?(attribute, attribute_values(attribute, value)) }
+          end
+
+          # Diagnostic counterpart to valid_value?, for building
+          # path-annotated instance-validation reports: walks the same
+          # rules but returns the first [failing_constraint_node,
+          # failing_rm_value] pair found (depth-first) instead of a
+          # bare boolean, or nil when +value+ fully conforms.
+          def find_violation(value)
+            if value.nil? || !node_id_matches?(value) || !OpenEHR::RM.subtype_of?(value, rm_type_name)
+              return [self, value]
+            end
+            return nil if any_allowed?
+
+            attributes.each do |attribute|
+              violation = attribute_violation(attribute, value)
+              return violation if violation
+            end
+            nil
+          end
+
+          private
+
+          def attribute_violation(attribute, value)
+            rm_values = attribute_values(attribute, value)
+            return [self, value] unless interval_satisfied?(attribute.existence, rm_values.empty? ? 0 : 1)
+
+            if attribute.is_a?(CMultipleAttribute)
+              return [self, value] unless interval_satisfied?(attribute.cardinality&.interval, rm_values.size)
+              return [self, value] unless children_occurrences_satisfied?(attribute.children, rm_values)
+            end
+
+            children = attribute.children || []
+            rm_values.each do |v|
+              matched = children.find { |child| child_matches?(child, v) }
+              return [self, v] if matched.nil?
+              next unless matched.respond_to?(:find_violation)
+
+              violation = matched.find_violation(v)
+              return violation if violation
+            end
+            nil
+          end
+
+          def node_id_matches?(value)
+            return true if node_id.nil?
+            return true unless value.respond_to?(:archetype_node_id)
+
+            value.archetype_node_id == node_id
+          end
+
+          def attribute_values(attribute, value)
+            name = attribute.rm_attribute_name
+            Array(value.respond_to?(name) ? value.send(name) : nil)
+          end
+
+          def attribute_conforms?(attribute, rm_values)
+            present = rm_values.empty? ? 0 : 1
+            return false unless interval_satisfied?(attribute.existence, present)
+
+            if attribute.is_a?(CMultipleAttribute)
+              return false unless interval_satisfied?(attribute.cardinality&.interval, rm_values.size)
+              return false unless children_occurrences_satisfied?(attribute.children, rm_values)
+            end
+
+            children = attribute.children || []
+            rm_values.all? { |v| children.any? { |child| child_matches?(child, v) } }
+          end
+
+          def interval_satisfied?(interval, count)
+            interval.nil? || interval.has?(count)
+          end
+
+          def children_occurrences_satisfied?(children, rm_values)
+            (children || []).all? do |child|
+              next true if child.occurrences.nil?
+
+              child.occurrences.has?(rm_values.count { |v| child_matches?(child, v) })
+            end
+          end
+
+          def child_matches?(child, rm_value)
+            return true if child.is_a?(ArchetypeSlot) ||
+                           child.is_a?(ArchetypeInternalRef) ||
+                           child.is_a?(ConstraintRef)
+
+            child.valid_value?(rm_value)
+          end
+
+          public
+
+          # Builds the minimal RM instance satisfying this node's
+          # mandatory constraints: only attributes with existence
+          # lower >= 1 are populated, each from its first child
+          # alternative's own default_value (recursively), and
+          # CMultipleAttribute gets exactly cardinality.interval.lower
+          # (or 1) copies of it. Returns nil - rather than raising -
+          # whenever a mandatory field has no derivable default, since
+          # that means no minimal instance can be built at all.
+          def default_value
+            return nil if any_allowed?
+
+            klass = OpenEHR::RM.class_for(rm_type_name)
+            return nil if klass.nil?
+
+            params = mandatory_attribute_params
+            return nil if params.nil?
+
+            klass.new(node_id.nil? ? params : params.merge(:archetype_node_id => node_id))
+          rescue ArgumentError, NotImplementedError
+            nil
+          end
+
+          private
+
+          def mandatory_attribute_params
+            attributes.each_with_object({}) do |attribute, params|
+              next unless mandatory_attribute?(attribute)
+
+              value = attribute_default(attribute)
+              return nil if value.nil?
+
+              params[attribute.rm_attribute_name.to_sym] = value
+            end
+          end
+
+          def mandatory_attribute?(attribute)
+            attribute.existence.nil? || attribute.existence.lower.to_i >= 1
+          end
+
+          def attribute_default(attribute)
+            children = attribute.children || []
+            return nil if children.empty?
+
+            child = children.first
+            return nil if child.is_a?(ArchetypeSlot) ||
+                          child.is_a?(ArchetypeInternalRef) ||
+                          child.is_a?(ConstraintRef)
+
+            if attribute.is_a?(CMultipleAttribute)
+              multiple_default(child, attribute.cardinality)
+            else
+              child.default_value
+            end
+          end
+
+          def multiple_default(child, cardinality)
+            value = child.default_value
+            return nil if value.nil?
+
+            count = cardinality&.interval&.lower
+            count = 1 if count.nil? || count < 1
+
+            Array.new(count) { value }
+          end
         end
 
         class CDomainType < CDefinedObject
@@ -370,12 +584,22 @@ module OpenEHR
 
         class CMultipleAttribute < CAttribute
           attr_accessor :members, :cardinality
-          
+
           def initialize(args = { })
             super
             self.members = args[:members]
             self.cardinality = args[:cardinality]
           end
+
+          # Adds cardinality⊆ on top of CAttribute's rm_attribute_name
+          # and existence conformance rules.
+          def node_conforms_to?(other)
+            return false unless super
+
+            mine = cardinality ? cardinality.interval : nil
+            others = other.cardinality ? other.cardinality.interval : nil
+            interval_conforms_to?(mine, others)
+          end
         end
       end # of ConstraintModel
     end # of Archetype

data/lib/openehr/am/archetype/ontology.rb

@@ -77,8 +77,8 @@ module OpenEHR
 
           protected
           def code_set(definitions)
-            codes = definitions.values.inject([]) do |codes, item|
-              item.keys
+            codes = definitions.values.inject([]) do |accumulated, item|
+              accumulated + item.keys.to_a
             end
             codes.uniq
           end

data/lib/openehr/am/archetype.rb

@@ -65,33 +65,132 @@ module OpenEHR
           return @ontology.term_definition(:lang => a_lang, :code => @concept).items['text']
         end
 
+        NODE_ID_PATTERN = /\A(?:at|ac|id)\d+(\.\d+)*\z/
+
+        # A reference to a constraint definition (ADL "matches {use_node ac0001}")
+        # is valid when it names a code actually present in the ontology's
+        # constraint_definitions. True when there are no such references at
+        # all; false (rather than vacuously true) when there are references
+        # but the ontology has no constraint_definitions section.
         def constraint_references_valid?
+          refs = collect(ConstraintModel::ConstraintRef) { |node| node.reference }
+          return true if refs.empty?
+
+          codes = ontology.constraint_codes
+          return false if codes.nil?
+
+          refs.all? { |ref| codes.include?(ref) }
         end
 
+        # An ARCHETYPE_INTERNAL_REF's target_path must resolve to a node
+        # physically present in this same definition tree.
         def internal_references_valid?
+          refs = collect(ConstraintModel::ArchetypeInternalRef) { |node| node.target_path }
+          paths = physical_paths
+          refs.all? { |ref| paths.include?(ref) }
         end
 
+        # True when a specialise header was present (i.e. this archetype
+        # names a parent archetype to specialise).
         def is_specialised?
+          !parent_archetype_id.nil?
         end
 
+        # Composition of the three granular structural checks above.
         def is_valid?
+          node_ids_valid? && constraint_references_valid? && internal_references_valid?
         end
 
-        def logical_paths(a_lang) 
+        # physical_paths with each at/ac/id-code predicate replaced by its
+        # ontology term text for +a_lang+ (falling back to the bare code
+        # when no term text is found for it).
+        def logical_paths(a_lang)
+          physical_paths.map { |path| localize_path(path, a_lang) }
+        end
+
+        # Every node_id used in the definition, syntactically valid
+        # (at/ac/id-code, optionally dotted for specialisation) and present
+        # in the ontology's term codes.
+        def node_ids_valid?
+          node_ids = collect_node_ids
+          codes = ontology.term_codes
+          node_ids.all? { |id| id =~ NODE_ID_PATTERN && codes.include?(id) }
         end
 
         def node_ids_vaild?
+          warn '[DEPRECATED] node_ids_vaild? is deprecated (typo); use node_ids_valid? instead'
+          node_ids_valid?
         end
 
+        # The archetype path of every node physically present in the
+        # definition, in depth-first order, without duplicates (a node
+        # without its own node_id shares its parent attribute's path).
         def physical_paths
+          paths = []
+          each_constraint_node(definition) { |node| paths << node.path if node.respond_to?(:path) }
+          paths.uniq
         end
 
+        # This gem does not parse ADL revision history, so a previous
+        # version can never be determined from a parsed archetype.
         def previous_version
+          nil
         end
 
+        # Prefers the ontology's own (parser-derived) specialisation_depth
+        # when available; otherwise falls back to what the archetype_id's
+        # domain_concept specialisation suffix can tell us. ArchetypeID
+        # currently only represents a single specialisation level, so this
+        # fallback can only ever return 0 or 1.
         def specialisation_depth
+          return ontology.specialisation_depth if ontology.specialisation_depth
+
+          archetype_id.specialisation.nil? ? 0 : 1
+        end
+
+        private
+
+        def each_constraint_node(node, &block)
+          return if node.nil?
+
+          yield node
+          if node.respond_to?(:attributes) && node.attributes
+            node.attributes.each { |attribute| each_constraint_node(attribute, &block) }
+          end
+          return unless node.respond_to?(:children) && node.children
+
+          node.children.each { |child| each_constraint_node(child, &block) }
         end
-        
+
+        def collect(klass)
+          found = []
+          each_constraint_node(definition) { |node| found << yield(node) if node.is_a?(klass) }
+          found
+        end
+
+        def collect_node_ids
+          ids = []
+          each_constraint_node(definition) { |node| ids << node.node_id if node.respond_to?(:node_id) && node.node_id }
+          ids
+        end
+
+        def localize_path(path, a_lang)
+          path.gsub(/\[((?:at|ac|id)\d+(?:\.\d+)*)\]/) do
+            code = Regexp.last_match(1)
+            text = term_text(code, a_lang)
+            text ? "[#{text}]" : "[#{code}]"
+          end
+        end
+
+        def term_text(code, a_lang)
+          term = ontology.term_definition(:lang => a_lang, :code => code)
+          term && term.items['text']
+        rescue StandardError
+          nil
+        end
+
+        public
+
         def self.create(args ={}, &block)
           archetype = new(args)
           if block_given?

data/lib/openehr/am/openehr_profile/data_types/basic.rb

@@ -18,6 +18,34 @@ module OpenEHR
               raise ArgumentError, 'value is mandatory' if value.nil?
               @value = value
             end
+
+            def valid_value?(rm_value)
+              return false if rm_value.nil?
+
+              state = matching_state(rm_value)
+              return false if state.nil?
+              return true unless rm_value.respond_to?(:is_terminal?)
+
+              rm_value.is_terminal? == state.is_a?(TerminalState)
+            end
+
+            private
+
+            def matching_state(rm_value)
+              return nil unless rm_value.respond_to?(:value)
+
+              code = state_code(rm_value.value)
+              return nil if code.nil?
+
+              value.states.find { |s| s.name == code }
+            end
+
+            def state_code(raw)
+              return raw if raw.is_a?(String)
+              return raw.code_string if raw.respond_to?(:code_string)
+
+              nil
+            end
           end
 
           class StateMachine

data/lib/openehr/am/openehr_profile/data_types/quantity.rb

@@ -21,6 +21,13 @@ module OpenEHR
                 return false
               end
             end
+
+            def valid_value?(value)
+              return true if any_allowed?
+              return false if list.nil? || value.nil?
+
+              list.any? { |item| item.matches?(value) }
+            end
           end
           
           class CDvOrdinal < OpenEHR::AM::Archetype::ConstraintModel::CDomainType
@@ -33,6 +40,63 @@ module OpenEHR
             def any_allowed?
               @list.nil?
             end
+
+            def valid_value?(value)
+              return true if any_allowed?
+              return false unless value.respond_to?(:value) && value.respond_to?(:symbol)
+
+              list.any? do |item|
+                item.value == value.value && symbol_code(item.symbol) == symbol_code(value.symbol)
+              end
+            end
+
+            private
+
+            # DV_ORDINAL.symbol is spec'd as DV_CODED_TEXT, which only
+            # exposes a code via defining_code.code_string (DvCodedText
+            # itself has no code_string of its own) - but also accept a
+            # bare CODE_PHRASE-like symbol (direct code_string) since
+            # that's simpler and sufficient for many callers.
+            def symbol_code(symbol)
+              return symbol.code_string if symbol.respond_to?(:code_string)
+              return symbol.defining_code.code_string if symbol.respond_to?(:defining_code)
+
+              nil
+            end
+          end
+
+          # RM 1.1.0: the AOM constraint for DV_SCALE, mirroring
+          # CDvOrdinal (an enumeration of allowed value/symbol pairs)
+          # except DV_SCALE.value is Real rather than Integer.
+          class CDvScale < OpenEHR::AM::Archetype::ConstraintModel::CDomainType
+            attr_accessor :list
+
+            def initialize(args = { })
+              super
+              self.list = args[:list]
+            end
+
+            def any_allowed?
+              @list.nil?
+            end
+
+            def valid_value?(value)
+              return true if any_allowed?
+              return false unless value.respond_to?(:value) && value.respond_to?(:symbol)
+
+              list.any? do |item|
+                item.value == value.value && symbol_code(item.symbol) == symbol_code(value.symbol)
+              end
+            end
+
+            private
+
+            def symbol_code(symbol)
+              return symbol.code_string if symbol.respond_to?(:code_string)
+              return symbol.defining_code.code_string if symbol.respond_to?(:defining_code)
+
+              nil
+            end
           end
 
           class CQuantityItem
@@ -53,12 +117,36 @@ module OpenEHR
             end
 
             def precision_unconstrained?
+              return true if @precision.nil?
               if @precision.upper == -1 && @precision.lower == -1
                 return true
               else
                 return false
               end
             end
+
+            def matches?(value)
+              return false unless value.respond_to?(:units) && value.units == units
+
+              magnitude_matches?(value.magnitude) &&
+                precision_matches?(value.respond_to?(:precision) ? value.precision : nil)
+            end
+
+            private
+
+            def magnitude_matches?(value_magnitude)
+              return true if magnitude.nil?
+              return magnitude.has?(value_magnitude) if magnitude.respond_to?(:has?)
+
+              magnitude == value_magnitude
+            end
+
+            def precision_matches?(value_precision)
+              return true if precision_unconstrained?
+              return precision.has?(value_precision) if precision.respond_to?(:has?)
+
+              precision == value_precision
+            end
           end
         end
       end # of DataTypes

data/lib/openehr/am/openehr_profile/data_types/text.rb

@@ -18,6 +18,29 @@ module OpenEHR
             def any_allowed?
               @terminology_id.nil? && @code_list.nil?
             end
+
+            def valid_value?(value)
+              return true if any_allowed?
+              return false if value.nil?
+
+              code, term = code_and_terminology(value)
+              return false if code.nil?
+
+              (code_list.nil? || code_list.include?(code)) &&
+                (terminology_id.nil? || term.nil? || term == terminology_id.value)
+            end
+
+            private
+
+            def code_and_terminology(value)
+              if value.is_a?(String)
+                [value, nil]
+              elsif value.respond_to?(:code_string)
+                [value.code_string, value.respond_to?(:terminology_id) ? value.terminology_id&.value : nil]
+              else
+                [nil, nil]
+              end
+            end
           end
         end # of Text
       end # of Data_Types

data/lib/openehr/am/template.rb

@@ -11,13 +11,19 @@ module OpenEHR
         attr_reader :component_terminologies, :terminology_extracts, :template_id
 
         def initialize(args = {})
+          # template_id must be validated before delegating to Archetype#initialize:
+          # OPERATIONAL_TEMPLATE identifies itself by template_id, and archetype_id
+          # is derived from it below, so an absent template_id must fail with a
+          # template-specific message rather than falling through to Archetype's
+          # own (unrelated) mandatory-field checks.
+          self.template_id = args[:template_id]
+
           # Initialize parent archetype with template-specific archetype_id
           template_args = args.dup
           template_args[:archetype_id] = args[:template_id] if args[:template_id] && !args[:archetype_id]
-          
+
           super(template_args)
-          
-          self.template_id = args[:template_id]
+
           self.component_terminologies = args[:component_terminologies] || {}
           self.terminology_extracts = args[:terminology_extracts] || {}
         end
@@ -31,6 +37,22 @@ module OpenEHR
           @archetype_id = template_id if template_id
         end
 
+        # An operational template's concept is commonly derived from its
+        # archetype_id (see #concept below) rather than supplied explicitly,
+        # so unlike Archetype#concept= it must not require a value up front.
+        def concept=(concept)
+          @concept = concept
+        end
+
+        # AuthoredResource#description has no mandatory check, but an
+        # operational template always carries its own resource description.
+        def description=(description)
+          if description.nil?
+            raise ArgumentError, 'description is mandatory'
+          end
+          @description = description
+        end
+
         def component_terminologies=(component_terminologies)
           @component_terminologies = component_terminologies || {}
         end

data/lib/openehr/aql/engine/binding.rb

@@ -0,0 +1,13 @@
+module OpenEHR
+  module AQL
+    # A single row-candidate produced while walking the FROM clause's
+    # containment tree: the Dataset::EHRRecord it came from (for "e/..."
+    # root paths) plus the RM objects bound to each FROM variable so far
+    # (e.g. {"c" => a_composition, "o" => an_observation}).
+    Binding = Struct.new(:ehr_record, :variables, keyword_init: true) do
+      def [](name)
+        variables.fetch(name) { raise SemanticError, "unbound variable: #{name.inspect}" }
+      end
+    end
+  end
+end