Small (mostly) backwards compatible quality of life changes (#65)

* Small (mostly) backwards compatible quality of life changes

 - Fixes an issue where multiple versions or views could map to the same identifier, which would result in them overwriting each other.
 - You now have to explicitly mark a version of a validation as an empty object. This solves an issue where you could succesfully validate constructables with a nil version by passing in an empty object.
 - view and version can now directly be called on the validator instead of having to call to_constructable.
 - Validating a media type which doesn't have a validation now throws an error instead of accepting an empty object.
 - Added available_validations function on validator which returns a list of constructable it supports.
 - Added name DSL function to replace media_type. name allows using self.organisation instead of having to define self.base_format. name defaults to using an opinionated media type identifier format. Name now only allows setting a default suffix as having a default version caused subtle bugs during real world usage.
 - Added identfier_format function to override opinionated media type identifier format.
 - Added identifier function to get the media type identifier

Author: thexa4

CHANGELOG.md

@@ -1,3 +1,16 @@
+# 1.0.0
+ - Added the ability to do inline tests when defining validations using `assert_pass '<json>'` and `assert_fail '<json>'`.
+ - `media_type` has been replaced with `use_name`.
+ - It is no longer possible to set a default version. Please use `version <x> do` instead.
+ - You no longer need to specify a custom format string. If you set an organisation with `def self.organisation` or set a module wide organisation with `MediaTypes::set_organisation <module>, '<organisation>'` the library will generate identifiers for you.
+ - `self.base_format` has been replaced by `identifier_format do |type:, view:, version:, suffix:|`.
+ - Added the `empty` validation to mark an empty object as valid.
+ - Added the `identifier` function to get the [Media Type Identifier](https://en.wikipedia.org/wiki/Media_type) for the validator.
+ - Added `version(x)` and `view(x)` functions.
+ - Added an `available_validations` functions that returns all defined validations.
+ - Fixed an issue where validations could accidentally merge if defined with a bad `base_format`.
+ - Fixed an issue where undefined validations would accept an empty object.
+
 # 0.6.2
 
 - Fix handling empty collections

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    media_types (0.6.2)
+    media_types (1.0.0)
 
 GEM
   remote: https://rubygems.org/

README.md

@@ -6,6 +6,8 @@
 
 Media Types based on  scheme, with versioning, views, suffixes and validations. Integrations available for [Rails](https://github.com/rails/rails) / ActionPack and [http.rb](https://github.com/httprb/http).
 
+This library makes it easy to define schemas that can be used to validate JSON objects based on their Content-Type.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -24,38 +26,58 @@ Or install it yourself as:
 
 ## Usage
 
-By default there are no media types registered or defined, except for an abstract base type.
+Define a validation:
+
+```ruby
+require 'media_types'
+
+module Acme
+  MediaTypes::set_organisation Acme, 'acme'
+
+  class FooValidator
+    include MediaTypes::Dsl
+
+    use_name 'foo'
 
-## Definition
-You can define media types by inheriting from this base type, or create your own base type with a class method `.base_format` that is used to create the final media type string by injecting formatted parameters:
+    validations do
+      attribute :foo, String
+    end
+  end
+end
+```
 
-- `%<type>s`: the type `media_type` received
-- `%<version>s`: the version, defaults to `:current_version`
-- `%<view>s`: the view, defaults to <empty>
-- `%<suffix>s`: the suffix
+Validate an object:
+
+```ruby
+Acme::FooValidator.validate!({ foo: 'bar' })
+```
+
+## Full example
 
 ```Ruby
 require 'media_types'
 
 class Venue
   include MediaTypes::Dsl
 
-  def self.base_format
-    'application/vnd.mydomain.%<type>s.v%<version>s.%<view>s+%<suffix>s'
+  def self.organisation
+    'mydomain'
   end
 
-  media_type 'venue', defaults: { suffix: :json, version: 2 }
+  media_type 'venue', defaults: { suffix: :json }
 
   validations do
-    attribute :name, String
-    collection :location do
-      attribute :latitude, Numeric
-      attribute :longitude, Numeric
-      attribute :altitude, AllowNil(Numeric)
-    end
+    version 2 do
+      attribute :name, String
+      collection :location do
+        attribute :latitude, Numeric
+        attribute :longitude, Numeric
+        attribute :altitude, AllowNil(Numeric)
+      end
 
-    link :self
-    link :route, allow_nil: true
+      link :self
+      link :route, allow_nil: true
+    end
 
     version 1 do
       attribute :name, String
@@ -97,7 +119,7 @@ end
 
 ## Schema Definitions
 
-If you define a scheme using `current_scheme { }`, you may use any of the following dsl:
+If you include 'MediaTypes::Dsl' in your class you can use the following functions within a `validation do` block to define your schema:
 
 ### `attribute`
 
@@ -315,25 +337,25 @@ expected_object.valid?([{ foo: 'string' }])
 ```
 
 ## Formatting for headers
-Any media type object can be coerced in valid string to be used with `Content-Type` or `Accept`:
+Any media type object can be converted in valid string to be used with `Content-Type` or `Accept`:
 
 ```Ruby
-Venue.mime_type.to_s
+Venue.mime_type.identifier
 # => "application/vnd.mydomain.venue.v2+json"
 
-Venue.mime_type.version(1).to_s
+Venue.mime_type.version(1).identifier
 # => "application/vnd.mydomain.venue.v1+json"
 
-Venue.mime_type.version(1).suffix(:xml).to_s
+Venue.mime_type.version(1).suffix(:xml).identifier
 # => "application/vnd.mydomain.venue.v1+xml"
 
 Venue.mime_type.to_s(0.2)
 # => "application/vnd.mydomain.venue.v2+json; q=0.2"
 
-Venue.mime_type.collection.to_s
+Venue.mime_type.collection.identifier
 # => "application/vnd.mydomain.venue.v2.collection+json"
 
-Venue.mime_type.view('active').to_s
+Venue.mime_type.view('active').identifier
 # => "application/vnd.mydomain.venue.v2.active+json"
 ```
 
@@ -374,6 +396,64 @@ Load the `http` integration and call `.register` on all media types you want to
 
 Currently uses `oj` under the hood and this can not be changed.
 
+## API
+
+A defined schema has the following functions available:
+
+### `valid?`
+
+Example: `Venue.valid?({ foo: 'bar' })`
+
+Allows passing in validation options as a second parameter.
+
+### `validate!`
+
+Example: `Venue.validate!({ foo: 'bar' })`
+
+Allows passing in validation options as a second parameter.
+
+### `validatable?`
+
+Example: `Venue.version(42).validatable?`
+
+Tests wether the current configuration of the schema has a validation defined.
+
+### `register`
+
+Example: `Venue.register`
+
+Registers the media type to the registry.
+
+### `view`
+
+Example: `Venue.view('create')`
+
+Returns a schema validator configured with the specified view.
+
+### `version`
+
+Example: `Venue.version(42)`
+
+Returns a schema validator configured with the specified version.
+
+### `suffix`
+
+Example: `Venue.suffix(:json)`
+
+Returns a schema validator configured with the specified suffix.
+
+### `identifier`
+
+Example: `Venue.version(2).identifier` (returns `'application/vnd.application.venue.v2'`)
+
+Returns the IANA compatible [Media Type Identifier](https://en.wikipedia.org/wiki/Media_type) for the configured schema.
+
+### `available_validations`
+
+Example: `Venue.available_validations`
+
+Returns a list of all the schemas that are defined.
+
 ## Related
 
 - [`MediaTypes::Serialization`](https://github.com/XPBytes/media_types-serialization): :cyclone: Add media types supported serialization using your favourite serializer

lib/media_types.rb

@@ -12,6 +12,19 @@
 require 'media_types/integrations'
 
 module MediaTypes
+  def self.set_organisation(mod, organisation)
+    @organisation_prefixes ||= {}
+    @organisation_prefixes[mod.name] = organisation
+  end
+
+  def self.get_organisation(mod)
+    name = mod.name
+    prefixes = @organisation_prefixes.keys.select { |p| name.start_with? p }
+    return nil unless prefixes.any?
+    best = prefixes.max_by { |p| p.length }
+
+    @organisation_prefixes[best]
+  end
 end
 
 

lib/media_types/.dsl.rb.swp

@@ -73,40 +73,60 @@ def split(pattern = nil, *limit)
       to_str.split(pattern, *limit)
     end
 
+    def as_key
+      [type, view, version, suffix]
+    end
+
     def hash
-      to_str.hash
+      as_key.hash
     end
 
     def to_str(qualifier = nil)
-      # TODO: remove warning by slicing out these arguments if they don't appear in the format
       qualified(
         qualifier,
-        Formatter.call(opts)
+        __getobj__.media_type_name_for.call(
+          type: opts[:type],
+          view: opts[:view],
+          version: opts[:version],
+          suffix: opts[:suffix],
+        )
       )
     end
+    
+    def available_validations
+      return [] if !validatable?
+      [self]
+    end
 
     def valid?(output, **validation_opts)
-      __getobj__.valid?(
+      raise ArgumentError, "Unable to validate #{to_s} type without a corresponding validation. Please mark objects that should be empty with 'empty'." unless validatable?
+
+      __getobj__.valid_unsafe?(
         output,
         self,
         **validation_opts
       )
     end
 
     def validate!(output, **validation_opts)
-      __getobj__.validate!(
+      raise ArgumentError, "Unable to validate #{to_s} type without a corresponding validation. Please mark objects that should be empty with 'empty'." unless validatable?
+
+      __getobj__.validate_unsafe!(
         output,
         self,
         **validation_opts
       )
     end
 
     def validatable?
+      return false unless media_type_combinations.include? as_key
+      
       __getobj__.validatable?(self)
     end
 
     alias inspect to_str
     alias to_s to_str
+    alias identifier to_str
 
     private