media_types 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ccae096fd19259b025952edea85f433588fbce01
-  data.tar.gz: 64fed267722b36d17a324eb9ebb436be04bfc412
+  metadata.gz: 54061285d1504ab09d4fc7299bf242ad4e0a7529
+  data.tar.gz: d1cff5bf120ff2f5cd570887f3e351117466e54e
 SHA512:
-  metadata.gz: 118d4c8c2c67070cd0c5469a5330a95b954993db1773a9da633ff0e58370623732fb0236126d64eadc9869ab1ccd612ddfccef8c39dc4ddc4fa0a64c642903ba
-  data.tar.gz: 68cf8356ab79b25ba2edf5c20cb1dcae36bb2c9ccf278529643aee6a90aec7d7a4d1599e608a689a460962a062dce586a7649d8a0240cb1994cc7de0b3e7e034
+  metadata.gz: 283abdbba4639fbabb39223ed943c495289a2a2f607055e1c00d1b789d6612d604d3de5b7bf4d4e5d644acd9e4d46316e2e92319354f71278059f0c42697b5eb
+  data.tar.gz: 2a57915b68ebab50f5820ee472499aea29d9bbeaa17f5cab416419c8ab3acba7f094c1934c50e2458b9c3728f71c5c6f845de6ec6e6e55bac666143ff48030dd

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+# 0.5.0
+
+- Change internal representation of key to symbol
+- Change default type from `nil` to `Object`, removing special behaviour for nil
+- Add `Rules` class to handle normalization of keys and handling `rules` (`Scheme`, `Attribute`, etc)
+- Add guard classes to handle guard behaviour (`OutputEmptyGuard`, `OutputTypeGuard` and `RulesExhaustedGuard`)
+- Add `optional:` keywords to most dsl (`attribute`, `collection`, `any`, `link`)
+- Add `Formatter` class to handle formatting of the `Constructable#to_s`
+- Add behaviour to strip leading dot (`.`) or plus (`+`) from `+%<var>` if `var` is nil, fixing weird media types
+- Add behaviour to remove format variable values if format variable is not present, fixing warnings
+- Add `inspect` for most public classes
+- Add second argument for type or scheme to `any` dsl, mimicking `collection`
+- Add tests for most dsl, common permutations
+- Rename `force` to `expected_type`
+- Remove `format_view` behaviour where it adds a dot (`.`) if a view is present
+- Remove special iteration behaviour for `Links` (`link` dsl), allowing them to be optional, or non-exhaustive
+- Raise error if `self.base_format` is not available at time of `Dsl.media_type` call
+- Fix `expected_type` guard for arrays, nil, or arrays with nil.
+
 # 0.4.1
 
 - Use strings for `:_links`, matching the other validation keys

data/Gemfile.lock

@@ -1,44 +1,44 @@
-PATH
-  remote: .
-  specs:
-    media_types (0.4.1)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    ansi (1.5.0)
-    awesome_print (1.8.0)
-    builder (3.2.3)
-    docile (1.3.1)
-    json (2.1.0)
-    minitest (5.11.3)
-    minitest-ci (3.4.0)
-      minitest (>= 5.0.6)
-    minitest-reporters (1.3.4)
-      ansi
-      builder
-      minitest (>= 5.0)
-      ruby-progressbar
-    rake (10.5.0)
-    ruby-progressbar (1.10.0)
-    simplecov (0.16.1)
-      docile (~> 1.1)
-      json (>= 1.8, < 3)
-      simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.2)
-
-PLATFORMS
-  x64-mingw32
-
-DEPENDENCIES
-  awesome_print
-  bundler (~> 1.16)
-  media_types!
-  minitest (~> 5.0)
-  minitest-ci
-  minitest-reporters
-  rake (~> 10.0)
-  simplecov
-
-BUNDLED WITH
-   1.16.4
+PATH
+  remote: .
+  specs:
+    media_types (0.5.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ansi (1.5.0)
+    awesome_print (1.8.0)
+    builder (3.2.3)
+    docile (1.3.1)
+    json (2.1.0)
+    minitest (5.11.3)
+    minitest-ci (3.4.0)
+      minitest (>= 5.0.6)
+    minitest-reporters (1.3.4)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
+    rake (10.5.0)
+    ruby-progressbar (1.10.0)
+    simplecov (0.16.1)
+      docile (~> 1.1)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+
+PLATFORMS
+  x64-mingw32
+
+DEPENDENCIES
+  awesome_print
+  bundler (~> 1.16)
+  media_types!
+  minitest (~> 5.0)
+  minitest-ci
+  minitest-reporters
+  rake (~> 10.0)
+  simplecov
+
+BUNDLED WITH
+   1.16.4

data/README.md

@@ -1,347 +1,379 @@
-# MediaTypes
-[![Build Status](https://travis-ci.com/SleeplessByte/media-types-ruby.svg?branch=master)](https://travis-ci.com/SleeplessByte/media-types-ruby)
-[![Gem Version](https://badge.fury.io/rb/media_types.svg)](https://badge.fury.io/rb/media_types)
-[![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT) 
-[![Maintainability](https://api.codeclimate.com/v1/badges/6f2dc1fb37ecb98c4363/maintainability)](https://codeclimate.com/github/SleeplessByte/media-types-ruby/maintainability)
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'media_types'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install media_types
-
-## Usage
-
-By default there are no media types registered or defined, except for an abstract base type.
-
-## 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:
-
-- `%<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
-
-```Ruby
-require 'media_types'
-
-class Venue < MediaTypes::Base
-  media_type 'venue', defaults: { suffix: :json, version: 2 }
-
-  validations 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
-    
-    version 1 do
-      attribute :name, String
-      attribute :coords, String
-      attribute :updated_at, String
-    
-      link :self
-    end
-    
-    view 'create' do
-      collection :location do
-        attribute :latitude, Numeric
-        attribute :longitude, Numeric
-        attribute :altitude, AllowNil(Numeric)
-      end
-      
-      version 1 do
-        collection :location do
-          attribute :latitude, Numeric
-          attribute :longitude, Numeric
-          attribute :altitude, AllowNil(Numeric)
-        end
-      end
-    end
-  end
-
-  registrations :venue_json do
-    view 'create', :create_venue
-    view 'index', :venue_urls
-    view 'collection', :venue_collection
-    
-    versions [1,2]
-    
-    suffix :json
-    suffix :xml
-  end
-  
-  def self.base_format
-    'application/vnd.mydomain.%<type>s.v%<version>s%<view>s+%<suffix>s'
-  end
-end
-```
-
-## Schema Definitions
-
-If you define a scheme using `current_scheme { }`, you may use any of the following dsl:
-
-### `attribute`
-
-Adds an attribute to the schema, if a +block+ is given, uses that to test against instead of +type+
-
-| param | type | description |
-|-------|------|-------------|
-| key | `Symbol` | the attribute name |
-| opts | `Hash` | options to pass to `Scheme` or `Attribute` |
-| type | `Class`, `===`, Scheme | The type of the value, can be anything that responds to `===`,  or scheme to use if no `&block` is given. Defaults to `String` without a `&block` and to Hash with a `&block`. |
-| &block | `Block` | defines the scheme of the value of this attribute |
-
-#### Add an attribute named foo, expecting a string
-```Ruby
-require 'media_types'
-
-class MyMedia
-  include MediaTypes::Dsl
-
-  validations do
-    attribute :foo, String
-  end
-end
-
-MyMedia.valid?({ foo: 'my-string' })
-# => true
-```
-
-####  Add an attribute named foo, expecting nested scheme
-
-```Ruby
-class MyMedia
- include MediaTypes::Dsl
-
- validations do
-   attribute :foo do
-     attribute :bar, String
-   end
- end
-end
-
-MyMedia.valid?({ foo: { bar: 'my-string' }})
-# => true
-```
-
-### `any`
-Allow for any key. The `&block` defines the Schema for each value.
-
-| param | type | description |
-|-------|------|-------------|
-| scheme | `Scheme`, `NilClass` | scheme to use if no `&block` is given |
-| allow_empty: | `TrueClass`, `FalsClass` | if true, empty (no key/value present) is allowed |
-| force: | `Class`, | forces the validated value to have this type, defaults to `Hash` |
-| &block | `Block` | defines the scheme of the value of this attribute |
-
-#### Add a collection named foo, expecting any key with a defined value
-```Ruby
-class MyMedia
- include MediaTypes::Dsl
-
- validations do
-   collection :foo do
-     any do
-       attribute :bar, String
-     end
-   end
- end
-end
-
-MyMedia.valid?({ foo: [{ anything: { bar: 'my-string' }, other_thing: { bar: 'other-string' } }] })
-# => true
-```` 
-
-### `not_strict`
-Allow for extra keys in the schema/collection even when passing `strict: true` to `#validate!`
-
-#### Allow for extra keys in collection
-
-```Ruby
-class MyMedia
- include MediaTypes::Dsl
-
- validations do
-   collection :foo do
-     attribute :required, String
-     not_strict
-   end
- end
-end
-
-MyMedia.valid?({ foo: [{ required: 'test', bar: 42 }] })
-# => true
-``` 
-  
-### `collection`
-Expect a collection such as an array or hash. The `&block` defines the Schema for each item in that collection.
-
-| param | type | description |
-|-------|------|-------------|
-| key | `Symbol` | key of the collection (same as `#attribute`) |
-| scheme | `Scheme`, `NilClass`, `Class` | scheme to use if no `&block` is given or `Class` of each item in the  |
-| allow_empty: | `TrueClass`, `FalsClass` | if true, empty (no key/value present) is allowed |
-| force: | `Class`, | forces the validated value to have this type, defaults to `Array` |
-| &block | `Block` | defines the scheme of the value of this attribute |
-
-
-#### Collection with an array of string
-```Ruby
-class MyMedia
- include MediaTypes::Dsl
-
- validations do
-   collection :foo, String
- end
-end
-
-MyMedia.valid?({ collection: ['foo', 'bar'] })
-# => true
-```
-
-#### Collection with defined scheme
-
-```Ruby
-class MyMedia
- include MediaTypes::Dsl
-
- validations do
-   collection :foo do
-     attribute :required, String
-     attribute :number, Numeric
-   end
- end
-end
-
-MyMedia.valid?({ foo: [{ required: 'test', number: 42 }, { required: 'other', number: 0 }] })
-# => true
-```
-
-### `link`
-
-Expect a link
-
-#### Links as defined in HAL, JSON-Links and other specs
-```Ruby
-class MyMedia
-  include MediaTypes::Dsl
-
-  validations do
-    link :_self
-    link :image
-  end
-end
-
-MyMedia.valid?({ _links: { self: { href: 'https://example.org/s' }, image: { href: 'https://image.org/i' }} })
-# => true
-```
-
-
-#### Link with extra attributes
-```Ruby
-class MyMedia
-  include MediaTypes::Dsl
-
-  validations do
-    link :image do
-      attribute :templated, TrueClass
-    end
-  end
-end
-
-MyMedia.valid?({ _links: { self: { href: 'https://example.org/s' }, image: { href: 'https://image.org/i' }} })
-# => true
-```
-
-#### Link with extra attributes
-```Ruby
-class MyMedia
- include MediaTypes::Dsl
-
- validations do
-   link :image do
-     attribute :templated, TrueClass
-   end
- end
-end
-
-MyMedia.valid?({ _links: { image: { href: 'https://image.org/{md5}', templated: true }} })
-# => true
-```
-
-## Validation
-If your type has a validations, you can now use this media type for validation:
-
-```Ruby
-Venue.valid?({ ... })
-# => true if valid, false otherwise
-
-Venue.validate!({ ... })
-# => raises if it's not valid
-```
-
-## Formatting for headers
-Any media type object can be coerced in valid string to be used with `Content-Type` or `Accept`:
-
-```Ruby
-Venue.mime_type.to_s
-# => "application/vnd.mydomain.venue.v2+json"
-
-Venue.mime_type.version(1).to_s
-# => "application/vnd.mydomain.venue.v1+json"
-
-Venue.mime_type.version(1).suffix(:xml).to_s
-# => "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
-# => "application/vnd.mydomain.venue.v2.collection+json"
-
-Venue.mime_type.view('active').to_s
-# => "application/vnd.mydomain.venue.v2.active+json"
-```
-
-## Register in Rails or Rack
-Define a `registrations` block on your media type, indicating the symbol for the base type (`registrations :symbol do`)
-and inside use the registrations dsl to define which media types to register. `versions array_of_numbers` determines which versions, 
-`suffix name` adds a suffix, `type_alias name` adds an alias and `view name, symbol` adds a view.
-
-As long as `action_dispatch` is available, you can register the mime type with `action_dispatch/http/mime_type`:
-```Ruby
-Venue.register
-# => Mime type is now available using the symbol, or lookup the actual mimetype
-```
-
-You can do this in the `mime_types` initializer, or anywhere before your controllers are instantiated. Yes, the symbol
-(by default `<type>_v<version>_<suffix>`) can now be used in your `format` blocks, or as extension in the url.
-
-## Development
-
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can
-also run `bin/console` for an interactive prompt that will allow you to experiment.
-
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
-version number in `version.rb`, call `bundle exec rake release` to create a new git tag, push git commits and tags, and
-push the `.gem` file to rubygems.org.
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at [SleeplessByte/media-types-ruby](https://github.com/SleeplessByte/media-types-ruby)
+# MediaTypes
+[![Build Status](https://travis-ci.com/SleeplessByte/media-types-ruby.svg?branch=master)](https://travis-ci.com/SleeplessByte/media-types-ruby)
+[![Gem Version](https://badge.fury.io/rb/media_types.svg)](https://badge.fury.io/rb/media_types)
+[![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT) 
+[![Maintainability](https://api.codeclimate.com/v1/badges/6f2dc1fb37ecb98c4363/maintainability)](https://codeclimate.com/github/SleeplessByte/media-types-ruby/maintainability)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'media_types'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install media_types
+
+## Usage
+
+By default there are no media types registered or defined, except for an abstract base type.
+
+## 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:
+
+- `%<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
+
+```Ruby
+require 'media_types'
+
+class Venue < MediaTypes::Base
+  media_type 'venue', defaults: { suffix: :json, version: 2 }
+
+  validations 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
+    
+    version 1 do
+      attribute :name, String
+      attribute :coords, String
+      attribute :updated_at, String
+    
+      link :self
+    end
+    
+    view 'create' do
+      collection :location do
+        attribute :latitude, Numeric
+        attribute :longitude, Numeric
+        attribute :altitude, AllowNil(Numeric)
+      end
+      
+      version 1 do
+        collection :location do
+          attribute :latitude, Numeric
+          attribute :longitude, Numeric
+          attribute :altitude, AllowNil(Numeric)
+        end
+      end
+    end
+  end
+
+  registrations :venue_json do
+    view 'create', :create_venue
+    view 'index', :venue_urls
+    view 'collection', :venue_collection
+    
+    versions [1,2]
+    
+    suffix :json
+    suffix :xml
+  end
+  
+  def self.base_format
+    'application/vnd.mydomain.%<type>s.v%<version>.s%<view>s+%<suffix>s'
+  end
+end
+```
+
+## Schema Definitions
+
+If you define a scheme using `current_scheme { }`, you may use any of the following dsl:
+
+### `attribute`
+
+Adds an attribute to the schema, if a +block+ is given, uses that to test against instead of +type+
+
+| param | type | description |
+|-------|------|-------------|
+| key | `Symbol` | the attribute name |
+| opts | `Hash` | options to pass to `Scheme` or `Attribute` |
+| type | `Class`, `===`, Scheme | The type of the value, can be anything that responds to `===`,  or scheme to use if no `&block` is given. Defaults to `String` without a `&block` and to Hash with a `&block`. |
+| optional: | `TrueClass`, `FalseClass` | if true, key may be absent, defaults to `false` |
+| &block | `Block` | defines the scheme of the value of this attribute |
+
+#### Add an attribute named foo, expecting a string
+```Ruby
+require 'media_types'
+
+class MyMedia
+  include MediaTypes::Dsl
+
+  validations do
+    attribute :foo, String
+  end
+end
+
+MyMedia.valid?({ foo: 'my-string' })
+# => true
+```
+
+####  Add an attribute named foo, expecting nested scheme
+
+```Ruby
+class MyMedia
+ include MediaTypes::Dsl
+
+ validations do
+   attribute :foo do
+     attribute :bar, String
+   end
+ end
+end
+
+MyMedia.valid?({ foo: { bar: 'my-string' }})
+# => true
+```
+
+### `any`
+Allow for any key. The `&block` defines the Schema for each value.
+
+| param | type | description |
+|-------|------|-------------|
+| scheme | `Scheme`, `NilClass` | scheme to use if no `&block` is given |
+| allow_empty: | `TrueClass`, `FalsClass` | if true, empty (no key/value present) is allowed |
+| expected_type: | `Class`, | forces the validated value to have this type, defaults to `Hash`. Use `Object` if either `Hash` or `Array` is fine |
+| &block | `Block` | defines the scheme of the value of this attribute |
+
+#### Add a collection named foo, expecting any key with a defined value
+```Ruby
+class MyMedia
+ include MediaTypes::Dsl
+
+ validations do
+   collection :foo do
+     any do
+       attribute :bar, String
+     end
+   end
+ end
+end
+
+MyMedia.valid?({ foo: [{ anything: { bar: 'my-string' }, other_thing: { bar: 'other-string' } }] })
+# => true
+```` 
+
+### `not_strict`
+Allow for extra keys in the schema/collection even when passing `strict: true` to `#validate!`
+
+#### Allow for extra keys in collection
+
+```Ruby
+class MyMedia
+ include MediaTypes::Dsl
+
+ validations do
+   collection :foo do
+     attribute :required, String
+     not_strict
+   end
+ end
+end
+
+MyMedia.valid?({ foo: [{ required: 'test', bar: 42 }] })
+# => true
+``` 
+  
+### `collection`
+Expect a collection such as an array or hash. The `&block` defines the Schema for each item in that collection.
+
+| param | type | description |
+|-------|------|-------------|
+| key | `Symbol` | key of the collection (same as `#attribute`) |
+| scheme | `Scheme`, `NilClass`, `Class` | scheme to use if no `&block` is given or `Class` of each item in the  |
+| allow_empty: | `TrueClass`, `FalseClass` | if true, empty (no key/value present) is allowed |
+| expected_type: | `Class`, | forces the validated value to have this type, defaults to `Array`. Use `Object` if either `Array` or `Hash` is fine. |
+| optional: | `TrueClass`, `FalseClass` | if true, key may be absent, defaults to `false` |
+| &block | `Block` | defines the scheme of the value of this attribute |
+
+
+#### Collection with an array of string
+```Ruby
+class MyMedia
+ include MediaTypes::Dsl
+
+ validations do
+   collection :foo, String
+ end
+end
+
+MyMedia.valid?({ collection: ['foo', 'bar'] })
+# => true
+```
+
+#### Collection with defined scheme
+
+```Ruby
+class MyMedia
+ include MediaTypes::Dsl
+
+ validations do
+   collection :foo do
+     attribute :required, String
+     attribute :number, Numeric
+   end
+ end
+end
+
+MyMedia.valid?({ foo: [{ required: 'test', number: 42 }, { required: 'other', number: 0 }] })
+# => true
+```
+
+### `link`
+
+Expect a link with a required `href: String` attribute
+
+| param | type | description |
+|-------|------|-------------|
+| key | `Symbol` | key of the link (same as `#attribute`) |
+| allow_nil: | `TrueClass`, `FalseClass` | if true, value may be nil |
+| optional: | `TrueClass`, `FalseClass` | if true, key may be absent, defaults to `false` |
+| &block | `Block` | defines the scheme of the value of this attribute, in addition to the `href` attribute |
+
+#### Links as defined in HAL, JSON-Links and other specs
+```Ruby
+class MyMedia
+  include MediaTypes::Dsl
+
+  validations do
+    link :_self
+    link :image
+  end
+end
+
+MyMedia.valid?({ _links: { self: { href: 'https://example.org/s' }, image: { href: 'https://image.org/i' }} })
+# => true
+```
+
+
+#### Link with extra attributes
+```Ruby
+class MyMedia
+  include MediaTypes::Dsl
+
+  validations do
+    link :image do
+      attribute :templated, TrueClass
+    end
+  end
+end
+
+MyMedia.valid?({ _links: { self: { href: 'https://example.org/s' }, image: { href: 'https://image.org/i' }} })
+# => true
+```
+
+#### Link with extra attributes
+```Ruby
+class MyMedia
+ include MediaTypes::Dsl
+
+ validations do
+   link :image do
+     attribute :templated, TrueClass
+   end
+ end
+end
+
+MyMedia.valid?({ _links: { image: { href: 'https://image.org/{md5}', templated: true }} })
+# => true
+```
+
+## Validation
+If your type has a validations, you can now use this media type for validation:
+
+```Ruby
+Venue.valid?({
+  #...
+})
+# => true if valid, false otherwise
+
+Venue.validate!({
+  # /*...*/ 
+})
+# => raises if it's not valid
+```
+
+If an array is passed, check the scheme for each value, unless the scheme is defined as expecting a hash:
+```Ruby
+expected_hash = Scheme.new(expected_type: Hash) { attribute(:foo) }
+expected_object = Scheme.new { attribute(:foo) } 
+
+expected_hash.valid?({ foo: 'string' })
+# => true
+
+expected_hash.valid?([{ foo: 'string' }])
+# => false
+
+
+expected_object.valid?({ foo: 'string' })
+# => true
+
+expected_object.valid?([{ foo: 'string' }])
+# => true
+```
+
+## Formatting for headers
+Any media type object can be coerced in valid string to be used with `Content-Type` or `Accept`:
+
+```Ruby
+Venue.mime_type.to_s
+# => "application/vnd.mydomain.venue.v2+json"
+
+Venue.mime_type.version(1).to_s
+# => "application/vnd.mydomain.venue.v1+json"
+
+Venue.mime_type.version(1).suffix(:xml).to_s
+# => "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
+# => "application/vnd.mydomain.venue.v2.collection+json"
+
+Venue.mime_type.view('active').to_s
+# => "application/vnd.mydomain.venue.v2.active+json"
+```
+
+## Register in Rails or Rack
+Define a `registrations` block on your media type, indicating the symbol for the base type (`registrations :symbol do`)
+and inside use the registrations dsl to define which media types to register. `versions array_of_numbers` determines which versions, 
+`suffix name` adds a suffix, `type_alias name` adds an alias and `view name, symbol` adds a view.
+
+As long as `action_dispatch` is available, you can register the mime type with `action_dispatch/http/mime_type`:
+```Ruby
+Venue.register
+# => Mime type is now available using the symbol, or lookup the actual mimetype
+```
+
+You can do this in the `mime_types` initializer, or anywhere before your controllers are instantiated. Yes, the symbol
+(by default `<type>_v<version>_<suffix>`) can now be used in your `format` blocks, or as extension in the url.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can
+also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
+version number in `version.rb`, call `bundle exec rake release` to create a new git tag, push git commits and tags, and
+push the `.gem` file to rubygems.org.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [SleeplessByte/media-types-ruby](https://github.com/SleeplessByte/media-types-ruby)