ruby-structured-data 0.1.1

data/lib/structured_data/validator/range_checker.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module StructuredData
+  class Validator
+    class RangeChecker
+      DATA_TYPES = %w[Text URL Date DateTime Time XPathType CssSelectorType PronounceableText DataType].freeze
+      NUMBER_TYPES = %w[Number Integer Float DataType].freeze
+      BOOLEAN_TYPES = %w[Boolean DataType].freeze
+      DATE_TIME_TYPES = %w[Date DateTime Time Text DataType].freeze
+      URL_TEXT_TYPES = %w[URL Text DataType].freeze
+      ENUM_FALLBACK_TYPES = %w[Text URL DataType Enumeration].freeze
+
+      attr_reader :vocabulary
+
+      def initialize(vocabulary)
+        @vocabulary = vocabulary
+      end
+
+      def matches?(val, ranges)
+        return true if ranges.empty?
+
+        case val
+        when Node
+          node_matches?(val, ranges)
+        when Reference
+          true
+        when Enum
+          enum_matches?(val, ranges)
+        when Values::Url, URI::Generic, Values::Text
+          ranges.intersect?(URL_TEXT_TYPES)
+        else
+          primitive_matches?(val, ranges)
+        end
+      end
+
+      private
+
+      def node_matches?(val, ranges)
+        return true if ranges.include?(val.type) || ranges.include?("Thing")
+
+        vocabulary.ancestors(val.type).intersect?(ranges)
+      end
+
+      def enum_matches?(val, ranges)
+        if val.type
+          return false unless enum_type_matches?(val, ranges)
+          return false if vocabulary.enum_type?(val.type) && !vocabulary.enum_member?(val.type, val.name)
+
+          return true
+        end
+
+        return true if ranges.intersect?(ENUM_FALLBACK_TYPES)
+
+        ranges.any? { |range| vocabulary.enum_member?(range, val.name) }
+      end
+
+      def enum_type_matches?(val, ranges)
+        ranges.include?(val.type) || vocabulary.ancestors(val.type).intersect?(ranges)
+      end
+
+      def primitive_matches?(val, ranges)
+        case val
+        when String
+          string_matches?(val, ranges)
+        when Integer, Float, Numeric
+          ranges.intersect?(NUMBER_TYPES)
+        when TrueClass, FalseClass
+          ranges.intersect?(BOOLEAN_TYPES)
+        when Date, Time
+          ranges.intersect?(DATE_TIME_TYPES)
+        else
+          false
+        end
+      end
+
+      def string_matches?(val, ranges)
+        return true if ranges.intersect?(DATA_TYPES)
+
+        ranges.any? { |range| vocabulary.enum_member?(range, val) }
+      end
+    end
+  end
+end

data/lib/structured_data/validator/result.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "diagnostic"
+
+module StructuredData
+  class Validator
+    class Result
+      attr_reader :diagnostics
+
+      def initialize(diagnostics = [])
+        @diagnostics = diagnostics.dup.freeze
+      end
+
+      def valid?
+        errors.empty?
+      end
+
+      def errors
+        diagnostics.select(&:error?)
+      end
+
+      def warnings
+        diagnostics.select(&:warning?)
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && diagnostics == other.diagnostics
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, diagnostics].hash
+      end
+    end
+  end
+  ValidationResult = Validator::Result
+end

data/lib/structured_data/validator.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative "validator/diagnostic"
+require_relative "validator/result"
+require_relative "validator/context"
+require_relative "validator/range_checker"
+require_relative "validator/node_validator"
+
+module StructuredData
+  class Validator
+    VALID_MODES = %i[schema_org strict none].freeze
+
+    class << self
+      def validate(target, mode: :schema_org, vocabulary: StructuredData::Vocabulary.default)
+        new(vocabulary: vocabulary).validate(target, mode: mode)
+      end
+
+      def validate!(target, mode: :schema_org, vocabulary: StructuredData::Vocabulary.default)
+        new(vocabulary: vocabulary).validate!(target, mode: mode)
+      end
+    end
+
+    attr_reader :vocabulary, :node_validator
+
+    def initialize(vocabulary: StructuredData::Vocabulary.default)
+      @vocabulary = vocabulary
+      range_checker = RangeChecker.new(vocabulary)
+      @node_validator = NodeValidator.new(vocabulary, range_checker)
+    end
+
+    def validate(target, mode: :schema_org)
+      validate_mode!(mode)
+      return Result.new if mode == :none
+
+      diagnostics = []
+      validate_target(target, Context.new(mode, diagnostics))
+      Result.new(diagnostics)
+    end
+
+    def validate!(target, mode: :schema_org)
+      result = validate(target, mode: mode)
+      raise ValidationError, result unless result.valid?
+
+      result
+    end
+
+    private
+
+    def validate_mode!(mode)
+      return if VALID_MODES.include?(mode)
+
+      raise ArgumentError, "Invalid validation mode: #{mode.inspect}"
+    end
+
+    def validate_target(target, context)
+      case target
+      when Document
+        validate_document(target, context)
+      when Node
+        node_validator.validate(target, "$", context)
+      else
+        raise ArgumentError, "Target must be a StructuredData::Node or StructuredData::Document"
+      end
+    end
+
+    def validate_document(document, context)
+      if document.nodes.size == 1 && !document.graph?
+        node_validator.validate(document.nodes.first, "$", context)
+      else
+        document.nodes.each_with_index do |node, idx|
+          node_validator.validate(node, "$.@graph[#{idx}]", context)
+        end
+      end
+    end
+  end
+end

data/lib/structured_data/values.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require "uri"
+require "json"
+require_relative "reference"
+require_relative "list"
+require_relative "enum"
+
+module StructuredData
+  module Values
+    class Url
+      attr_reader :value
+
+      def initialize(value)
+        validate_url!(value)
+        @value = value.to_s
+      end
+
+      def to_s
+        value
+      end
+      alias to_str to_s
+
+      def to_h
+        value
+      end
+
+      def as_json(*)
+        value
+      end
+
+      def to_json(*)
+        value.to_json(*)
+      end
+
+      def ==(other)
+        if other.is_a?(self.class)
+          value == other.value
+        elsif other.is_a?(String)
+          value == other
+        else
+          false
+        end
+      end
+
+      def eql?(other)
+        other.is_a?(self.class) && value == other.value
+      end
+
+      def hash
+        [self.class, value].hash
+      end
+
+      private
+
+      def validate_url!(val)
+        raise ArgumentError, "URL cannot be blank" if val.nil? || val.to_s.strip.empty?
+
+        check_parsed_uri!(parse_uri(val), val)
+      end
+
+      def parse_uri(val)
+        val.is_a?(URI::Generic) ? val : URI.parse(val.to_s)
+      rescue URI::InvalidURIError => e
+        raise ArgumentError, "Invalid URL format: #{val} (#{e.message})"
+      end
+
+      def check_parsed_uri!(uri, raw)
+        raise ArgumentError, "Invalid URL format: #{raw}" if uri.scheme.nil? || uri.scheme.empty?
+        raise ArgumentError, "Invalid URL format: #{raw}" if empty_location?(uri)
+      end
+
+      def empty_location?(uri)
+        (uri.host.nil? || uri.host.empty?) && (uri.path.nil? || uri.path.empty?)
+      end
+    end
+
+    class Text
+      attr_reader :value
+
+      def initialize(value)
+        raise ArgumentError, "Text cannot be nil" if value.nil?
+
+        @value = value.to_s
+      end
+
+      def to_s
+        value
+      end
+      alias to_str to_s
+
+      def to_h
+        value
+      end
+
+      def as_json(*)
+        value
+      end
+
+      def to_json(*)
+        value.to_json(*)
+      end
+
+      def ==(other)
+        if other.is_a?(self.class)
+          value == other.value
+        elsif other.is_a?(String)
+          value == other
+        else
+          false
+        end
+      end
+
+      def eql?(other)
+        other.is_a?(self.class) && value == other.value
+      end
+
+      def hash
+        [self.class, value].hash
+      end
+    end
+
+    module_function
+
+    def url(val)
+      val.is_a?(Url) ? val : Url.new(val)
+    end
+
+    def text(val)
+      val.is_a?(Text) ? val : Text.new(val)
+    end
+
+    def ref(id)
+      StructuredData::Reference.new(id)
+    end
+
+    def list(*items)
+      StructuredData::List.new(items.flatten)
+    end
+
+    def enum(name, type = nil)
+      StructuredData::Enum.new(name, type)
+    end
+  end
+
+  Url = Values::Url
+  Text = Values::Text
+end

data/lib/structured_data/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module StructuredData
+  VERSION = "0.1.1"
+end

data/lib/structured_data/vocabulary/data_loader.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+
+module StructuredData
+  class Vocabulary
+    module DataLoader
+      DEFAULT_DATA_PATH = File.expand_path("../../../data/schema_org_v30.json", __dir__)
+
+      def self.load(source)
+        case source
+        when nil
+          JSON.parse(File.read(DEFAULT_DATA_PATH))
+        when Hash
+          source
+        when String, Pathname
+          JSON.parse(File.read(source.to_s))
+        else
+          raise ArgumentError, "Invalid vocabulary source: #{source.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/structured_data/vocabulary/hierarchy.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module StructuredData
+  class Vocabulary
+    module Hierarchy
+      def self.ancestors(type_name, vocabulary)
+        normalized = vocabulary.normalize_term(type_name)
+        return [] if normalized.empty?
+
+        result = []
+        visited = Set.new([normalized])
+        queue = direct_parents(normalized, vocabulary)
+
+        until queue.empty?
+          current = queue.shift
+          next if visited.include?(current)
+
+          visited.add(current)
+          result << current
+          queue.concat(direct_parents(current, vocabulary))
+        end
+
+        result
+      end
+
+      def self.direct_parents(type_name, vocabulary)
+        info = vocabulary.type_info(type_name)
+        Array(info && (info["parents"] || info[:parents])).map { |p| vocabulary.normalize_term(p) }
+      end
+    end
+  end
+end

data/lib/structured_data/vocabulary/registry.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module StructuredData
+  class Vocabulary
+    class Registry
+      def initialize
+        @vocabularies = {}
+      end
+
+      def register(name, data)
+        raise ArgumentError, "Vocabulary data must be a Hash" unless data.is_a?(Hash)
+
+        @vocabularies[name.to_s] = normalize_vocab_data(data)
+      end
+
+      def find(category, key)
+        if key.include?(":")
+          prefix, local = key.split(":", 2)
+          val = @vocabularies[prefix]&.dig(category, local)
+          return val if val
+        end
+
+        @vocabularies.each_value do |vocab|
+          val = vocab.dig(category, key)
+          return val if val
+        end
+        nil
+      end
+
+      def enum_defined?(name)
+        @vocabularies.each_value.any? { |vocab| vocab.dig("enums", name) }
+      end
+
+      def all_types
+        @vocabularies.each_value.flat_map { |vocab| vocab["types"].keys }
+      end
+
+      def all_properties
+        @vocabularies.each_value.flat_map { |vocab| vocab["properties"].keys }
+      end
+
+      private
+
+      def normalize_vocab_data(data)
+        {
+          "types" => normalize_subhash(data["types"] || data[:types]),
+          "properties" => normalize_subhash(data["properties"] || data[:properties]),
+          "enums" => normalize_enums(data["enums"] || data[:enums]),
+          "superseded" => normalize_string_map(data["superseded"] || data[:superseded])
+        }
+      end
+
+      def normalize_subhash(hash)
+        return {} unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) do |(key, value), result|
+          norm_key = normalize_term(key)
+          result[norm_key] = value.is_a?(Hash) ? value.transform_keys(&:to_s) : value
+        end
+      end
+
+      def normalize_enums(hash)
+        return {} unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) do |(key, members), result|
+          result[normalize_term(key)] = normalize_term_list(members)
+        end
+      end
+
+      def normalize_term_list(list)
+        Array(list).map { |term| normalize_term(term) }
+      end
+
+      def normalize_string_map(hash)
+        return {} unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) do |(key, value), result|
+          result[normalize_term(key)] = normalize_term(value)
+        end
+      end
+
+      def normalize_term(term)
+        return "" if term.nil?
+
+        str = term.respond_to?(:name) && !term.is_a?(Class) ? term.name.to_s : term.to_s
+        str.strip.sub(%r{\Ahttps?://schema\.org/}, "")
+      end
+    end
+  end
+end

data/lib/structured_data/vocabulary.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require_relative "vocabulary/registry"
+require_relative "vocabulary/data_loader"
+require_relative "vocabulary/hierarchy"
+
+module StructuredData
+  class Vocabulary
+    class << self
+      extend Forwardable
+
+      def default
+        @default ||= new
+      end
+
+      def reset!
+        @default = nil
+      end
+
+      def_delegators :default,
+                     :type_defined?, :type_info, :ancestors, :property_defined?, :property_info,
+                     :property_allowed_for?, :expected_ranges, :enum_type?, :enum_member?,
+                     :superseded_by, :register_vocabulary, :all_types, :all_properties
+    end
+
+    def initialize(source = nil)
+      @registry = Registry.new
+      @data = DataLoader.load(source)
+    end
+
+    def type_defined?(type_name)
+      !type_info(type_name).nil?
+    end
+
+    def type_info(type_name)
+      lookup_category("types", type_name)
+    end
+
+    def ancestors(type_name)
+      Hierarchy.ancestors(type_name, self)
+    end
+
+    def property_defined?(property_name)
+      !property_info(property_name).nil?
+    end
+
+    def property_info(property_name)
+      lookup_category("properties", property_name)
+    end
+
+    def property_allowed_for?(type_name, property_name)
+      info = property_info(property_name)
+      return false unless info
+
+      domains = Array(info["domains"] || info[:domains]).map { |d| normalize_term(d) }
+      norm_type = normalize_term(type_name)
+      return true if domains.include?(norm_type)
+
+      ancestors(norm_type).any? { |ancestor| domains.include?(ancestor) }
+    end
+
+    def expected_ranges(property_name)
+      info = property_info(property_name)
+      return [] unless info
+
+      Array(info["ranges"] || info[:ranges]).map { |r| normalize_term(r) }
+    end
+
+    def enum_type?(type_name)
+      norm = normalize_term(type_name)
+      return false if norm.empty?
+
+      !@data.dig("enums", norm).nil? || @registry.enum_defined?(norm) ||
+        norm == "Enumeration" || ancestors(norm).include?("Enumeration")
+    end
+
+    def enum_member?(enum_type_name, member_name)
+      norm_enum = normalize_term(enum_type_name)
+      norm_member = normalize_term(member_name)
+      return false if norm_enum.empty? || norm_member.empty?
+
+      return true if enum_members(norm_enum).include?(norm_member)
+
+      ancestors(norm_enum).any? do |ancestor|
+        enum_members(ancestor).include?(norm_member)
+      end
+    end
+
+    def superseded_by(term)
+      norm = normalize_term(term)
+      return nil if norm.empty?
+
+      @registry.find("superseded", norm) || @data.dig("superseded", norm)
+    end
+
+    def register_vocabulary(name, data)
+      @registry.register(name, data)
+      self
+    end
+
+    def all_types
+      category_keys("types")
+    end
+
+    def all_properties
+      category_keys("properties")
+    end
+
+    def normalize_term(term)
+      return "" if term.nil?
+
+      str = term.respond_to?(:name) && !term.is_a?(Class) ? term.name.to_s : term.to_s
+      str.strip.sub(%r{\Ahttps?://schema\.org/}, "")
+    end
+
+    private
+
+    def lookup_category(category, term)
+      norm = normalize_term(term)
+      return nil if norm.empty?
+
+      @registry.find(category, norm) || @data.dig(category, norm)
+    end
+
+    def category_keys(category)
+      keys = @data[category] ? @data[category].keys : []
+      (keys + @registry.public_send("all_#{category}")).uniq.sort
+    end
+
+    def enum_members(norm_enum)
+      members = @registry.find("enums", norm_enum) || @data.dig("enums", norm_enum) || []
+      Array(members).map { |m| normalize_term(m) }
+    end
+  end
+end