json_skooma 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eb2d7d35ec23d77daeda2fbc2e13a04a22265ecb549c2450b7f3e01fc0351a2a
-  data.tar.gz: f9c354da7ac5cd8354a968bc728313af943189f9b06279d3812e91dd88086139
+  metadata.gz: bc94f3d758977e845fe5b92b683c57da06d23af3144cee65cd573679b0992b56
+  data.tar.gz: 1b9209442642b9bbe4170a400d164eae8ab4f58c4857ebd15c9a79a4532837f2
 SHA512:
-  metadata.gz: 5352834d1a61ad40c9416bfad5fb8543da5d872151a4e6925194c42b87639dc125fd1268343b6fc6b8b7bb0b047144dd21e95049cddfec065bc5e3990b54768a
-  data.tar.gz: 1095a00a437945ab384154da3f0f75a401636c39c21b9a7a2fd2b8de88140c909393c49f900c3295c289d6bb9795e238f3ccc2f7263348367076938ebf88bc8f
+  metadata.gz: 162215474dabeade31c53db14198eadb391f076b8305565c7f504ddbfe8cc3ea56654f7fdc0bbd4dca488f1adb814914b21e7d5780804d5d54efc4f11b66c8d3
+  data.tar.gz: f9158392915e5ea3985ad19f2df4e94ce3988b627f44b57cdbc3eb8b6a2dc01e475c40275e648baf6c64bb27168b292415ef663632f0becd6389f6c37e917863

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [0.2.7] - 2026-06-10
+
+### Fixed
+
+- Include the JSON Schema metaschema data files in the packaged gem. 0.2.6 was built without the `data/draft-*` submodules checked out, so `create_registry` crashed with `Sources::Error` on the released gem. ([@skryukov])
+
+## [0.2.6] - 2026-06-10 [YANKED]
+
+### Added
+
+- New `:annotated` output format interleaves the instance data with annotations collected during evaluation (`title`/`description` by default, configurable via `keywords:`). Each node becomes `{"title" => ..., "value" => ...}`, mirroring the shape of the data — handy for rendering values alongside their schema-defined labels. ([@skryukov], [#13](https://github.com/skryukov/json_skooma/issues/13))
+- `JSONSkooma::UnexpectedSchemaClassError < RegistryError` is now raised by `Registry#schema` when the resolved fragment does not match the expected class. Extensions can rescue this specific error instead of matching on message text. ([@skryukov])
+- `Registry#load_json(uri)` is now public so extensions can load a raw document via registered sources. ([@skryukov])
+- `Keywords::ValueSchemas.default_schema_class=` lets extensions set the fallback class used to wrap sub-schemas when a keyword does not specify its own `schema_value_class`. ([@skryukov])
+
 ## [0.2.5] - 2024-12-25
 
 ### Added
@@ -63,7 +78,9 @@ and this project adheres to [Semantic Versioning].
 [@killondark]: https://github.com/killondark
 [@skryukov]: https://github.com/skryukov
 
-[Unreleased]: https://github.com/skryukov/json_skooma/compare/v0.2.5...HEAD
+[Unreleased]: https://github.com/skryukov/json_skooma/compare/v0.2.7...HEAD
+[0.2.7]: https://github.com/skryukov/json_skooma/compare/v0.2.6...v0.2.7
+[0.2.6]: https://github.com/skryukov/json_skooma/compare/v0.2.5...v0.2.6
 [0.2.5]: https://github.com/skryukov/json_skooma/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/skryukov/json_skooma/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/skryukov/json_skooma/compare/v0.2.2...v0.2.3

data/README.md

@@ -156,6 +156,44 @@ schema_registry.add_source(
 # - http://remote.example/product_definition.yaml -> http://example.com/schemas/product_definition.yaml
 ```
 
+### Extracting annotations
+
+The `:annotated` output format re-shapes collected annotations into a hash that mirrors your data: every node becomes a hash of its annotations plus a `"value"` key holding the original value. Useful for rendering data alongside the `title`/`description` texts defined in the schema.
+
+```ruby
+schema = JSONSkooma::JSONSchema.new({
+  "$schema" => "https://json-schema.org/draft/2020-12/schema",
+  "type" => "object",
+  "properties" => {
+    "user_id" => {
+      "type" => "integer",
+      "title" => "User Identifier",
+      "description" => "A unique numeric ID for the user."
+    }
+  }
+})
+
+result = schema.evaluate({"user_id" => 123})
+
+result.output(:annotated)
+# {"user_id"=>
+#   {"title"=>"User Identifier",
+#    "description"=>"A unique numeric ID for the user.",
+#    "value"=>123}}
+
+# Pick which annotation keywords to include (default: title and description):
+result.output(:annotated, keywords: %w[title description default deprecated])
+
+# Rename the wrapper key:
+result.output(:annotated, value_key: "data")
+```
+
+Notes:
+
+- Annotations contributed through `$ref`/`allOf` are merged into the same location; if several subschemas annotate the same keyword at the same location, the last one wins.
+- Annotations from failed subschemas (e.g. a non-matching `anyOf` branch) are dropped, as the spec prescribes.
+- The root node is returned unwrapped to keep the output data-shaped, so annotations on the root schema itself are not included.
+
 ## Alternatives
 
 - [json_schemer](https://github.com/davishmcclurg/json_schemer) – Draft 4, 6, 7, 2019-09 and 2020-12 compliant

data/lib/json_skooma/formatters.rb

@@ -133,5 +133,61 @@ module JSONSkooma
       end
     end
     register :verbose, Verbose
+
+    # Re-shapes collected annotations into a hash that mirrors the instance
+    # data: every node (except the root) becomes a hash of its annotations
+    # plus a "value" key holding the original value (with nested nodes wrapped
+    # the same way). Annotations contributed through $ref/allOf land on the
+    # same instance location, so they merge naturally; annotations from failed
+    # subschemas are dropped, per the JSON Schema spec.
+    #
+    #   result.output(:annotated)
+    #   # => {"user_id" => {"title" => "User Identifier", "value" => 123}, ...}
+    #
+    # Options:
+    #   keywords: list of annotation keywords to include (default: title, description)
+    #   value_key: key under which the original value is placed (default: "value")
+    module Annotated
+      DEFAULT_KEYWORDS = %w[title description].freeze
+
+      class << self
+        def call(result, keywords: DEFAULT_KEYWORDS, value_key: "value", **_options)
+          annotations = {}
+          collect(result, keywords.map(&:to_s), annotations)
+          represent(result.instance, annotations, value_key, root: true)
+        end
+
+        private
+
+        def collect(node, keywords, annotations)
+          return unless node.valid?
+
+          if node.annotation && keywords.include?(node.key)
+            annotation = node.annotation
+            annotation = annotation.value if annotation.is_a?(JSONNode)
+            (annotations[node.instance.path.to_s] ||= {})[node.key] = annotation
+          end
+
+          node.each_children { |child| collect(child, keywords, annotations) }
+        end
+
+        def represent(instance, annotations, value_key, root: false)
+          value =
+            case instance.type
+            when "object"
+              instance.transform_values { |child| represent(child, annotations, value_key) }
+            when "array"
+              instance.map { |child| represent(child, annotations, value_key) }
+            else
+              instance.value
+            end
+
+          return value if root
+
+          (annotations[instance.path.to_s] || {}).merge(value_key => value)
+        end
+      end
+    end
+    register :annotated, Annotated
   end
 end

data/lib/json_skooma/keywords/value_schemas.rb

@@ -4,6 +4,8 @@ module JSONSkooma
   module Keywords
     module ValueSchemas
       class << self
+        attr_writer :default_schema_class
+
         def [](key)
           value_schemas&.[](key) or raise "Unknown value schema: #{key}, known schemas: #{value_schemas.keys.inspect}"
         end
@@ -12,6 +14,14 @@ module JSONSkooma
           (self.value_schemas ||= {})[key] = klass
         end
 
+        # Class used to wrap schema values when a keyword does not set its own
+        # `schema_value_class`. Extensions (e.g. Skooma) override this to plug
+        # their own JSONSchema subclass into every sub-schema created by the
+        # built-in applicator keywords.
+        def default_schema_class
+          @default_schema_class || JSONSchema
+        end
+
         private
 
         attr_accessor :value_schemas
@@ -21,7 +31,7 @@ module JSONSkooma
         def wrap_value(value)
           return super unless value.is_a?(Hash) || value.is_a?(TrueClass) || value.is_a?(FalseClass)
 
-          (self.class.schema_value_class || JSONSchema).new(
+          (self.class.schema_value_class || ValueSchemas.default_schema_class).new(
             value,
             parent: parent_schema,
             key: key,
@@ -46,7 +56,7 @@ module JSONSkooma
             value,
             parent: parent_schema,
             key: key,
-            item_class: self.class.schema_value_class || JSONSchema,
+            item_class: self.class.schema_value_class || ValueSchemas.default_schema_class,
             registry: parent_schema.registry,
             cache_id: parent_schema.cache_id
           )
@@ -69,7 +79,7 @@ module JSONSkooma
             value,
             parent: parent_schema,
             key: key,
-            item_class: self.class.schema_value_class || JSONSchema,
+            item_class: self.class.schema_value_class || ValueSchemas.default_schema_class,
             registry: parent_schema.registry,
             cache_id: parent_schema.cache_id
           )

data/lib/json_skooma/registry.rb

@@ -3,6 +3,19 @@
 module JSONSkooma
   class RegistryError < Error; end
 
+  # Raised when a ref resolves to an object that is not the class the caller expected.
+  # Extension points (e.g. typed OpenAPI refs) can rescue this and load the subtree
+  # as the right class without matching on error message text.
+  class UnexpectedSchemaClassError < RegistryError
+    attr_reader :uri, :expected_class
+
+    def initialize(uri, expected_class)
+      @uri = uri
+      @expected_class = expected_class
+      super("The object referenced by #{uri} is not #{expected_class}")
+    end
+  end
+
   class Registry
     class << self
       attr_accessor :registries
@@ -79,7 +92,7 @@ module JSONSkooma
       schema = JSONPointer.new(uri.fragment).eval(schema) if uri.fragment
       return schema if schema.is_a?(expected_class)
 
-      raise RegistryError, "The object referenced by #{uri} is not #{expected_class}"
+      raise UnexpectedSchemaClassError.new(uri, expected_class)
     end
 
     def add_metaschema(uri, default_core_vocabulary_uri = nil, *default_vocabulary_uris)
@@ -113,8 +126,6 @@ module JSONSkooma
       @uri_sources[uri] = source
     end
 
-    private
-
     def load_json(uri)
       candidates = @uri_sources
         .select { |source_uri| uri.to_s.start_with?(source_uri) }

data/lib/json_skooma/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JSONSkooma
-  VERSION = "0.2.5"
+  VERSION = "0.2.7"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: json_skooma
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.7
 platform: ruby
 authors:
 - Svyatoslav Kryukov
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-25 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -236,7 +235,6 @@ metadata:
   homepage_uri: https://github.com/skryukov/json_skooma
   source_code_uri: https://github.com/skryukov/json_skooma
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -251,8 +249,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
-signing_key:
+rubygems_version: 4.0.6
 specification_version: 4
 summary: I bring some sugar for your JSONs.
 test_files: []