jsonstructure 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 75e811de4008546530bcdad74ce44cfbaebe56d15319c6c7673951ebff8dd798
-  data.tar.gz: 7be187b0e4e0cd1b8b205c3c09d99d556b16a3b28de74c8d00b8ea6b3a7012f3
+  metadata.gz: f870a1cfa2e4a2067e7fae0ad819f2a037a04156501413c9342c4fbd0be44624
+  data.tar.gz: 6db39ad31391b121bd41effec1dabeee9837e51887aec6511a33173e06e89764
 SHA512:
-  metadata.gz: 9b5d2f5c58b89f766fe8d6828d6dbcd37ce38eb6f86625693e5421e82f04204b711a2ae1affb2460bf56ff55e7757f2a58cfef96be977686b8db379b24704eef
-  data.tar.gz: 2265c5828667cab6b02078138d12f82314e22c1cf1e853d8a9757ab231546ad3d903da9ee6fcf8883de4c14c75c4ab0cf894ca6f75171526056a56910ab6e407
+  metadata.gz: 4d87870b6cc4d6f06ffe33aa347fdda0f8effa23e38f99563da008eda479f2509f55967e4b03116334bba8acf43bbb8ee0518dda2da78c8019d03dcada59473d
+  data.tar.gz: 3485c56c93501453c5eb1c7302d3349feb45ce7545c5b9eacc010d8fe1f71fa61fa358c51bb4cc45b916e1b73ae6e233086ee6cbcda7b47a538e5929a0b034cd

data/lib/jsonstructure/schema_validator.rb

@@ -1,11 +1,28 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module JsonStructure
   # Validates JSON Structure schema documents
   #
   # This class is thread-safe. Multiple threads can call validate concurrently.
   class SchemaValidator
-    # Validate a schema string
+    UCUM_NUMERIC_TYPES = %w[number integer float double decimal int32 uint32 int64 uint64 int128 uint128].freeze
+    ENUM_NUMERIC_TYPES = %w[integer int8 int16 int32 int64 uint8 uint16 uint32 uint64 float double decimal].freeze
+    RELATION_CONTAINER_TYPES = %w[object tuple].freeze
+    IDENTIFIER_PATTERN = /\A[A-Za-z_$][A-Za-z0-9_$]*\z/
+    URI_SCHEME_PATTERN = /\A[a-zA-Z][a-zA-Z0-9+\-.]*:/
+    VALIDATION_KEYWORDS = %w[
+      pattern format minLength maxLength minimum maximum exclusiveMinimum exclusiveMaximum multipleOf
+      minItems maxItems uniqueItems contains minContains maxContains
+      minProperties maxProperties propertyNames patternProperties dependentRequired
+      minEntries maxEntries patternKeys keyNames
+      contentEncoding contentMediaType has default
+    ].freeze
+    UNITS_KEYWORDS = %w[unit currency symbols].freeze
+
+    class << self
+      # Validate a schema string
     #
     # This method is thread-safe and can be called from multiple threads concurrently.
     #
@@ -20,39 +37,368 @@ module JsonStructure
     #   else
     #     result.errors.each { |e| puts e.message }
     #   end
-    def self.validate(schema_json)
-      raise ArgumentError, 'schema_json must be a String' unless schema_json.is_a?(String)
+      def validate(schema_json)
+        raise ArgumentError, 'schema_json must be a String' unless schema_json.is_a?(String)
 
-      JsonStructure.validation_started
-      begin
-        result_ptr = ::FFI::MemoryPointer.new(FFI::JSResult.size)
-        FFI.js_result_init(result_ptr)
+        JsonStructure.validation_started
+        begin
+          result_ptr = ::FFI::MemoryPointer.new(FFI::JSResult.size)
+          FFI.js_result_init(result_ptr)
 
-        FFI.js_validate_schema(schema_json, result_ptr)
-        ValidationResult.from_ffi(result_ptr)
-      ensure
-        JsonStructure.validation_completed
+          FFI.js_validate_schema(schema_json, result_ptr)
+          base_result = ValidationResult.from_ffi(result_ptr)
+          augment_extension_validation(base_result, schema_json)
+        ensure
+          JsonStructure.validation_completed
+        end
       end
-    end
 
-    # Validate a schema string, raising an exception on failure
-    #
-    # @param schema_json [String] JSON string containing the schema
-    # @return [ValidationResult] validation result (only if valid)
-    # @raise [SchemaValidationError] if validation fails
-    #
-    # @example
-    #   begin
-    #     JsonStructure::SchemaValidator.validate!(schema)
-    #     puts "Schema is valid!"
-    #   rescue JsonStructure::SchemaValidationError => e
-    #     puts "Validation failed: #{e.message}"
-    #   end
-    def self.validate!(schema_json)
-      result = validate(schema_json)
-      raise SchemaValidationError.new(result) unless result.valid?
+      # Validate a schema string, raising an exception on failure
+      #
+      # @param schema_json [String] JSON string containing the schema
+      # @return [ValidationResult] validation result (only if valid)
+      # @raise [SchemaValidationError] if validation fails
+      #
+      # @example
+      #   begin
+      #     JsonStructure::SchemaValidator.validate!(schema)
+      #     puts "Schema is valid!"
+      #   rescue JsonStructure::SchemaValidationError => e
+      #     puts "Validation failed: #{e.message}"
+      #   end
+      def validate!(schema_json)
+        result = validate(schema_json)
+        raise SchemaValidationError.new(result) unless result.valid?
+
+        result
+      end
+
+      private
+
+      def augment_extension_validation(base_result, schema_json)
+        schema = JSON.parse(schema_json)
+        additional_errors = []
+        validate_extension_keywords(schema, schema, '#', additional_errors)
+
+        return base_result if additional_errors.empty?
+
+        errors = base_result.errors + additional_errors
+        ValidationResult.new(errors.none?(&:error?), errors)
+      rescue JSON::ParserError
+        base_result
+      end
+
+      def validate_extension_keywords(root_schema, node, path, errors)
+        return unless node.is_a?(Hash)
+
+        type = node['type']
+        validate_root_schema_keywords(node, path, errors) if path == '#'
+        validate_validation_extension_gating(root_schema, node, path, errors)
+        validate_ucum_unit_keyword(root_schema, node, type, path, errors)
+        validate_units_keywords(root_schema, node, type, path, errors)
+        validate_relations_keywords(root_schema, node, type, path, errors)
+        validate_extends_keyword(root_schema, node, path, errors)
+        validate_tuple_ref_entries(root_schema, node, type, path, errors)
+        validate_enum_values(type, node, path, errors)
+
+        node.each do |key, value|
+          child_path = path == '#' ? "#/#{escape_json_pointer(key)}" : "#{path}/#{escape_json_pointer(key)}"
+
+          if value.is_a?(Hash)
+            validate_extension_keywords(root_schema, value, child_path, errors)
+          elsif value.is_a?(Array)
+            value.each_with_index do |item, index|
+              validate_extension_keywords(root_schema, item, "#{child_path}[#{index}]", errors)
+            end
+          end
+        end
+      end
+
+      def validate_root_schema_keywords(node, path, errors)
+        validate_root_id_keyword(node, path, errors)
+        validate_root_name_keyword(node, path, errors)
+      end
+
+      def validate_root_id_keyword(node, path, errors)
+        return unless node.key?('$id')
+        return unless node['$id'].is_a?(String)
+
+        if node['$id'].strip.empty?
+          add_manual_error(errors, '$id must not be empty', "#{path}/$id", 'SCHEMA_KEYWORD_EMPTY')
+        elsif node['$id'] !~ URI_SCHEME_PATTERN
+          add_manual_error(errors, '$id must be a URI with a scheme', "#{path}/$id", 'SCHEMA_CONSTRAINT_VALUE_INVALID')
+        end
+      end
+
+      def validate_root_name_keyword(node, path, errors)
+        return unless node.key?('name')
+        return unless node['name'].is_a?(String)
+        return if node['name'].match?(IDENTIFIER_PATTERN)
+
+        add_manual_error(errors, 'name must be a valid identifier', "#{path}/name", 'SCHEMA_NAME_INVALID')
+      end
+
+      def validate_validation_extension_gating(root_schema, node, path, errors)
+        return if extension_enabled?(root_schema, 'JSONStructureValidation')
+
+        VALIDATION_KEYWORDS.each do |keyword|
+          next unless node.key?(keyword)
+
+          add_manual_warning(errors, "'#{keyword}' requires JSONStructureValidation extension.", "#{path}/#{escape_json_pointer(keyword)}")
+        end
+      end
+
+      def validate_ucum_unit_keyword(root_schema, node, type, path, errors)
+        return unless node.key?('ucumUnit')
+
+        add_manual_error(errors, "'ucumUnit' requires JSONStructureUnits extension.", "#{path}/ucumUnit") unless extension_enabled?(root_schema, 'JSONStructureUnits')
+
+        add_manual_error(errors, "'ucumUnit' must be a string.", "#{path}/ucumUnit") unless node['ucumUnit'].is_a?(String)
+
+        return if type.is_a?(String) && UCUM_NUMERIC_TYPES.include?(type)
+
+        add_manual_error(errors, "'ucumUnit' can only appear in numeric schemas.", "#{path}/ucumUnit")
+      end
+
+      def validate_units_keywords(root_schema, node, type, path, errors)
+        UNITS_KEYWORDS.each do |keyword|
+          next unless node.key?(keyword)
+
+          add_manual_error(errors, "'#{keyword}' requires JSONStructureUnits extension.", "#{path}/#{escape_json_pointer(keyword)}") unless extension_enabled?(root_schema, 'JSONStructureUnits')
+        end
+
+        return unless node.key?('unit')
+
+        add_manual_error(errors, "'unit' must be a string.", "#{path}/unit") unless node['unit'].is_a?(String)
+
+        return if type.is_a?(String) && UCUM_NUMERIC_TYPES.include?(type)
+
+        add_manual_error(errors, "'unit' can only appear in numeric schemas.", "#{path}/unit")
+      end
+
+      def validate_relations_keywords(root_schema, node, type, path, errors)
+        has_identity = node.key?('identity')
+        has_relations = node.key?('relations')
+        return unless has_identity || has_relations
+
+        unless extension_enabled?(root_schema, 'JSONStructureRelations')
+          add_manual_error(errors, "'identity' requires JSONStructureRelations extension.", "#{path}/identity") if has_identity
+          add_manual_error(errors, "'relations' requires JSONStructureRelations extension.", "#{path}/relations") if has_relations
+        end
+
+        supports_relations = type.is_a?(String) && RELATION_CONTAINER_TYPES.include?(type)
+
+        if has_identity
+          validate_identity_keyword(node, path, supports_relations, errors)
+        end
+
+        validate_relations_object(root_schema, node, path, supports_relations, errors) if has_relations
+      end
 
-      result
+      def validate_identity_keyword(node, path, supports_relations, errors)
+        identity = node['identity']
+        add_manual_error(errors, "'identity' can only appear in object or tuple schemas.", "#{path}/identity") unless supports_relations
+
+        unless identity.is_a?(Array)
+          add_manual_error(errors, "'identity' must be an array of strings.", "#{path}/identity")
+          return
+        end
+
+        properties = node['properties'].is_a?(Hash) ? node['properties'] : {}
+        identity.each_with_index do |item, index|
+          item_path = "#{path}/identity[#{index}]"
+          unless item.is_a?(String)
+            add_manual_error(errors, "'identity[#{index}]' must be a string.", item_path)
+            next
+          end
+
+          unless properties.key?(item)
+            add_manual_error(errors, "'identity' references property '#{item}' that is not in 'properties'.", item_path)
+          end
+        end
+      end
+
+      def validate_relations_object(root_schema, node, path, supports_relations, errors)
+        relations = node['relations']
+        add_manual_error(errors, "'relations' can only appear in object or tuple schemas.", "#{path}/relations") unless supports_relations
+
+        unless relations.is_a?(Hash)
+          add_manual_error(errors, "'relations' must be an object.", "#{path}/relations")
+          return
+        end
+
+        relations.each do |relation_name, relation|
+          relation_path = "#{path}/relations/#{escape_json_pointer(relation_name.to_s)}"
+
+          unless relation.is_a?(Hash)
+            add_manual_error(errors, 'Relation declaration must be an object.', relation_path)
+            next
+          end
+
+          if relation.key?('targettype')
+            validate_relation_ref_object(root_schema, relation['targettype'], relation_path, 'targettype', errors)
+          else
+            add_manual_error(errors, "Relation declaration must have 'targettype'.", "#{relation_path}/targettype")
+          end
+
+          if relation.key?('cardinality')
+            cardinality = relation['cardinality']
+            unless cardinality.is_a?(String) && %w[single multiple].include?(cardinality)
+              add_manual_error(errors, "'cardinality' must be 'single' or 'multiple'.", "#{relation_path}/cardinality")
+            end
+          else
+            add_manual_error(errors, "Relation declaration must have 'cardinality'.", "#{relation_path}/cardinality")
+          end
+
+          validate_relation_scope(relation['scope'], relation_path, errors) if relation.key?('scope')
+          validate_relation_ref_object(root_schema, relation['qualifiertype'], relation_path, 'qualifiertype', errors) if relation.key?('qualifiertype')
+        end
+      end
+
+      def validate_relation_scope(scope, relation_path, errors)
+        return if scope.is_a?(String)
+
+        if scope.is_a?(Array)
+          scope.each_with_index do |item, index|
+            next if item.is_a?(String)
+
+            add_manual_error(errors, "'scope' array items must be strings.", "#{relation_path}/scope[#{index}]")
+          end
+          return
+        end
+
+        add_manual_error(errors, "'scope' must be a string or an array of strings.", "#{relation_path}/scope")
+      end
+
+      def validate_extends_keyword(root_schema, node, path, errors)
+        return unless node.key?('$extends')
+
+        refs = normalized_extends_refs(node['$extends'], path)
+        refs.each do |ref, ref_path|
+          next unless ref.start_with?('#/')
+
+          resolved = resolve_ref(root_schema, ref)
+          next unless resolved
+          next if resolved.is_a?(Hash) && (!resolved.key?('type') || %w[object tuple map array set choice].include?(resolved['type']))
+
+          add_manual_error(errors,
+                           "$extends target '#{ref}' must not resolve to a primitive type",
+                           ref_path,
+                           'SCHEMA_CONSTRAINT_TYPE_MISMATCH')
+        end
+      end
+
+      def normalized_extends_refs(extends_value, path)
+        case extends_value
+        when String
+          [[extends_value, "#{path}/$extends"]]
+        when Array
+          extends_value.each_with_index.filter_map do |item, index|
+            [item, "#{path}/$extends[#{index}]"] if item.is_a?(String)
+          end
+        else
+          []
+        end
+      end
+
+      def validate_tuple_ref_entries(root_schema, node, type, path, errors)
+        return unless type == 'tuple'
+        return unless node['tuple'].is_a?(Array)
+
+        node['tuple'].each_with_index do |entry, index|
+          next unless entry.is_a?(Hash) && entry['$ref'].is_a?(String)
+
+          ref = entry['$ref']
+          next unless ref.start_with?('#/')
+          next if resolve_ref(root_schema, ref)
+
+          add_manual_error(errors, "$ref '#{ref}' not found", "#{path}/tuple[#{index}]/$ref", 'SCHEMA_REF_NOT_FOUND')
+        end
+      end
+
+      def validate_enum_values(type, node, path, errors)
+        return unless node['enum'].is_a?(Array)
+        return unless type.is_a?(String)
+
+        node['enum'].each_with_index do |value, index|
+          next if enum_value_valid_for_type?(type, value)
+
+          add_manual_error(errors,
+                           "enum value is not valid for type '#{type}'",
+                           "#{path}/enum[#{index}]",
+                           'SCHEMA_CONSTRAINT_TYPE_MISMATCH')
+        end
+      end
+
+      def enum_value_valid_for_type?(type, value)
+        case type
+        when 'string'
+          value.is_a?(String)
+        when *ENUM_NUMERIC_TYPES
+          value.is_a?(Numeric)
+        when 'boolean'
+          value == true || value == false
+        when 'null'
+          value.nil?
+        else
+          true
+        end
+      end
+
+      def validate_relation_ref_object(root_schema, value, relation_path, keyword, errors)
+        keyword_path = "#{relation_path}/#{keyword}"
+
+        unless value.is_a?(Hash) && value['$ref'].is_a?(String)
+          add_manual_error(errors, "'#{keyword}' must be an object with '$ref'.", keyword_path)
+          return
+        end
+
+        ref = value['$ref']
+        return unless ref.start_with?('#/')
+        return if resolve_ref(root_schema, ref)
+
+        add_manual_error(errors, "$ref '#{ref}' not found", "#{keyword_path}/$ref")
+      end
+
+      def extension_enabled?(root_schema, extension)
+        uses = root_schema['$uses']
+        uses.is_a?(Array) && uses.include?(extension)
+      end
+
+      def resolve_ref(root_schema, ref)
+        return nil unless ref.start_with?('#/')
+
+        ref.delete_prefix('#/').split('/').reduce(root_schema) do |current, segment|
+          segment = segment.gsub('~1', '/').gsub('~0', '~')
+          break nil unless current.is_a?(Hash) && current.key?(segment)
+
+          current[segment]
+        end
+      end
+
+      def escape_json_pointer(segment)
+        segment.to_s.gsub('~', '~0').gsub('/', '~1')
+      end
+
+      def add_manual_error(errors, message, path, code = 0)
+        errors << ValidationError.new(
+          code: code,
+          severity: FFI::JS_SEVERITY_ERROR,
+          path: path,
+          message: message,
+          location: { line: 0, column: 0, offset: 0 }
+        )
+      end
+
+      def add_manual_warning(errors, message, path, code = 0)
+        errors << ValidationError.new(
+          code: code,
+          severity: FFI::JS_SEVERITY_WARNING,
+          path: path,
+          message: message,
+          location: { line: 0, column: 0, offset: 0 }
+        )
+      end
     end
   end
 

data/lib/jsonstructure/version.rb

@@ -2,5 +2,5 @@
 
 module JsonStructure
   # Version of the JSON Structure Ruby SDK
-  VERSION = '0.6.2'
+  VERSION = '0.7.0'
 end

data/spec/schema_validator_spec.rb

@@ -87,4 +87,336 @@ RSpec.describe JsonStructure::SchemaValidator do
       end
     end
   end
+
+  describe '.validate with ucumUnit keyword' do
+    it 'accepts a numeric type with ucumUnit' do
+      schema = <<~JSON
+        {
+          "$schema": "https://json-structure.org/meta/extended/v0/#",
+          "$id": "urn:example:ucum-number",
+          "name": "Length",
+          "$uses": ["JSONStructureUnits"],
+          "type": "number",
+          "ucumUnit": "m"
+        }
+      JSON
+
+      result = described_class.validate(schema)
+
+      expect(result).to be_valid
+      expect(result.error_messages).to be_empty
+    end
+
+    it 'accepts a numeric type with unit and ucumUnit' do
+      schema = <<~JSON
+        {
+          "$schema": "https://json-structure.org/meta/extended/v0/#",
+          "$id": "urn:example:ucum-both",
+          "name": "Length",
+          "$uses": ["JSONStructureUnits"],
+          "type": "number",
+          "unit": "meter",
+          "ucumUnit": "m"
+        }
+      JSON
+
+      result = described_class.validate(schema)
+
+      expect(result).to be_valid
+      expect(result.error_messages).to be_empty
+    end
+
+    it 'accepts extended numeric types with ucumUnit' do
+      %w[int32 float double decimal].each do |type|
+        schema = <<~JSON
+          {
+            "$schema": "https://json-structure.org/meta/extended/v0/#",
+            "$id": "urn:example:ucum-#{type}",
+            "name": "#{type}WithUcumUnit",
+            "$uses": ["JSONStructureUnits"],
+            "type": "#{type}",
+            "ucumUnit": "m"
+          }
+        JSON
+
+        result = described_class.validate(schema)
+
+        expect(result).to be_valid
+        expect(result.error_messages).to be_empty
+      end
+    end
+
+    it 'rejects ucumUnit on non-numeric types' do
+      schema = <<~JSON
+        {
+          "$schema": "https://json-structure.org/meta/extended/v0/#",
+          "$id": "urn:example:ucum-string",
+          "name": "BadUcumType",
+          "$uses": ["JSONStructureUnits"],
+          "type": "string",
+          "ucumUnit": "m"
+        }
+      JSON
+
+      result = described_class.validate(schema)
+
+      expect(result).to be_invalid
+      expect(result.error_messages).to include("'ucumUnit' can only appear in numeric schemas.")
+    end
+
+    it 'rejects non-string ucumUnit values' do
+      schema = <<~JSON
+        {
+          "$schema": "https://json-structure.org/meta/extended/v0/#",
+          "$id": "urn:example:ucum-non-string",
+          "name": "BadUcumValue",
+          "$uses": ["JSONStructureUnits"],
+          "type": "number",
+          "ucumUnit": 5
+        }
+      JSON
+
+      result = described_class.validate(schema)
+
+      expect(result).to be_invalid
+      expect(result.error_messages).to include("'ucumUnit' must be a string.")
+    end
+  end
+
+  describe '.validate with root keyword checks' do
+    it 'rejects empty $id values' do
+      schema = <<~JSON
+        {
+          "$schema": "https://json-structure.org/meta/core/v0/#",
+          "$id": "   ",
+          "name": "BadId",
+          "type": "object"
+        }
+      JSON
+
+      result = described_class.validate(schema)
+
+      expect(result).to be_invalid
+      expect(result.errors).to include(have_attributes(code: 'SCHEMA_KEYWORD_EMPTY', message: '$id must not be empty'))
+    end
+
+    it 'rejects $id values without a URI scheme' do
+      schema = <<~JSON
+        {
+          "$schema": "https://json-structure.org/meta/core/v0/#",
+          "$id": "example.com/no-scheme",
+          "name": "BadId",
+          "type": "object"
+        }
+      JSON
+
+      result = described_class.validate(schema)
+
+      expect(result).to be_invalid
+      expect(result.errors).to include(have_attributes(code: 'SCHEMA_CONSTRAINT_VALUE_INVALID', message: '$id must be a URI with a scheme'))
+    end
+
+    it 'rejects invalid root names' do
+      schema = <<~JSON
+        {
+          "$schema": "https://json-structure.org/meta/core/v0/#",
+          "$id": "https://example.com/bad-name-id",
+          "name": "123invalid",
+          "type": "object"
+        }
+      JSON
+
+      result = described_class.validate(schema)
+
+      expect(result).to be_invalid
+      expect(result.errors).to include(have_attributes(code: 'SCHEMA_NAME_INVALID', message: 'name must be a valid identifier'))
+    end
+  end
+
+  describe '.validate with enum type checks' do
+    it 'rejects enum values that do not match the declared type' do
+      schema = <<~JSON
+        {
+          "$schema": "https://json-structure.org/meta/core/v0/#",
+          "$id": "https://example.com/enum-type-mismatch",
+          "name": "EnumTypeMismatch",
+          "type": "boolean",
+          "enum": [true, "false"]
+        }
+      JSON
+
+      result = described_class.validate(schema)
+
+      expect(result).to be_invalid
+      expect(result.errors).to include(have_attributes(code: 'SCHEMA_CONSTRAINT_TYPE_MISMATCH', message: "enum value is not valid for type 'boolean'"))
+    end
+  end
+
+  describe '.validate with $extends checks' do
+    it 'rejects $extends targets that are not object or tuple schemas' do
+      schema = <<~JSON
+        {
+          "$schema": "https://json-structure.org/meta/core/v0/#",
+          "$id": "https://example.com/bad-extends-target",
+          "name": "Derived",
+          "type": "object",
+          "$extends": "#/definitions/Base",
+          "definitions": {
+            "Base": {
+              "name": "Base",
+              "type": "string"
+            }
+          }
+        }
+      JSON
+
+      result = described_class.validate(schema)
+
+      expect(result).to be_invalid
+      expect(result.errors).to include(
+        have_attributes(
+          code: 'SCHEMA_CONSTRAINT_TYPE_MISMATCH',
+          message: "$extends target '#/definitions/Base' must not resolve to a primitive type"
+        )
+      )
+    end
+  end
+
+  describe '.validate with tuple ref checks' do
+    it 'rejects tuple refs that cannot be resolved' do
+      schema = <<~JSON
+        {
+          "$schema": "https://json-structure.org/meta/core/v0/#",
+          "$id": "https://example.com/tuple-ref",
+          "name": "TupleRef",
+          "type": "tuple",
+          "properties": {
+            "name": { "type": "string" }
+          },
+          "tuple": [{ "$ref": "#/definitions/Missing" }]
+        }
+      JSON
+
+      result = described_class.validate(schema)
+
+      expect(result).to be_invalid
+      expect(result.errors).to include(
+        have_attributes(
+          code: 'SCHEMA_REF_NOT_FOUND',
+          message: "$ref '#/definitions/Missing' not found"
+        )
+      )
+    end
+  end
+
+  describe '.validate with Relations extension' do
+    it 'accepts object identity arrays' do
+      schema = <<~JSON
+        {
+          "$schema": "https://json-structure.org/meta/extended/v0/#",
+          "$id": "urn:example:relations-identity",
+          "name": "OrderIdentity",
+          "$uses": ["JSONStructureRelations"],
+          "type": "object",
+          "properties": {
+            "id": { "type": "string" },
+            "tenantId": { "type": "string" }
+          },
+          "identity": ["id", "tenantId"]
+        }
+      JSON
+
+      result = described_class.validate(schema)
+
+      expect(result).to be_valid
+      expect(result.error_messages).to be_empty
+    end
+
+    it 'accepts valid relation declarations' do
+      schema = <<~JSON
+        {
+          "$schema": "https://json-structure.org/meta/extended/v0/#",
+          "$id": "urn:example:relations-valid",
+          "name": "OrderRelations",
+          "$uses": ["JSONStructureRelations"],
+          "type": "object",
+          "properties": {
+            "id": { "type": "string" },
+            "customerId": { "type": "string" },
+            "itemIds": { "type": "array", "items": { "type": "string" } },
+            "qualifier": { "type": "string" }
+          },
+          "relations": {
+            "customer": {
+              "cardinality": "single",
+              "targettype": { "$ref": "#/definitions/Customer" }
+            },
+            "items": {
+              "cardinality": "multiple",
+              "targettype": { "$ref": "#/definitions/Item" },
+              "scope": "line-items"
+            },
+            "qualifiedCustomer": {
+              "cardinality": "single",
+              "targettype": { "$ref": "#/definitions/Customer" },
+              "qualifiertype": { "$ref": "#/definitions/RelationQualifier" }
+            }
+          },
+          "definitions": {
+            "Customer": {
+              "name": "Customer",
+              "type": "object",
+              "properties": { "id": { "type": "string" } }
+            },
+            "Item": {
+              "name": "Item",
+              "type": "object",
+              "properties": { "id": { "type": "string" } }
+            },
+            "RelationQualifier": {
+              "name": "RelationQualifier",
+              "type": "string"
+            }
+          }
+        }
+      JSON
+
+      result = described_class.validate(schema)
+
+      expect(result).to be_valid
+      expect(result.error_messages).to be_empty
+    end
+
+    it 'rejects invalid Relations schemas' do
+      schema = <<~JSON
+        {
+          "$schema": "https://json-structure.org/meta/extended/v0/#",
+          "$id": "urn:example:relations-invalid",
+          "name": "BadRelations",
+          "$uses": ["JSONStructureRelations"],
+          "type": "string",
+          "identity": ["id"],
+          "relations": {
+            "customer": {
+              "cardinality": "many",
+              "targettype": { "type": "object" },
+              "scope": ["ok", 3],
+              "qualifiertype": { "type": "string" }
+            }
+          }
+        }
+      JSON
+
+      result = described_class.validate(schema)
+
+      expect(result).to be_invalid
+      expect(result.error_messages).to include("'identity' can only appear in object or tuple schemas.")
+      expect(result.error_messages).to include("'identity' references property 'id' that is not in 'properties'.")
+      expect(result.error_messages).to include("'relations' can only appear in object or tuple schemas.")
+      expect(result.error_messages).to include("'targettype' must be an object with '$ref'.")
+      expect(result.error_messages).to include("'cardinality' must be 'single' or 'multiple'.")
+      expect(result.error_messages).to include("'scope' array items must be strings.")
+      expect(result.error_messages).to include("'qualifiertype' must be an object with '$ref'.")
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsonstructure
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - JSON Structure Contributors
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-04 00:00:00.000000000 Z
+date: 2026-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi