Update README with some migration information.

README.md

@@ -4,6 +4,48 @@ A [go](http://www.golang.org) (or 'golang' for search engine friendliness) imple
 
 **NOTICE:** A vulnerability in JWT was [recently published](https://auth0.com/blog/2015/03/31/critical-vulnerabilities-in-json-web-token-libraries/).  As this library doesn't force users to validate the `alg` is what they expected, it's possible your usage is effected.  There will be an update soon to remedy this, and it will likey require backwards-incompatible changes to the API.  In the short term, please make sure your implementation verifies the `alg` is what you expect.
 
+## Migration Guide from v2 -> v3
+
+Added the ability to supply a typed object for the claims section of the token.
+
+Unfortunately this requires a breaking change. A few new methods were added to support this,
+and the old default of `map[string]interface{}` was changed to `jwt.MapClaim`.
+
+The old example for creating a token looked like this..
+
+```go
+	token := jwt.New(jwt.SigningMethodHS256)
+	token.Claims["foo"] = "bar"
+	token.Claims["exp"] = time.Now().Add(time.Hour * 72).Unix()
+```
+
+is now directly mapped to...
+
+```go
+	token := jwt.New(jwt.SigningMethodHS256)
+	claims := token.Claims.(jwt.MapClaim)
+	claims["foo"] = "bar"
+	claims["exp"] = time.Now().Add(time.Hour * 72).Unix()
+```
+
+However, we added a helper `jwt.NewWithClaims` which accepts a claims object.
+
+Any type can now be used as the claim object for inside a token so long as it implements the interface `jwt.Claims`.
+
+So, we added an additional claim type `jwt.StandardClaims` was added.
+This is intended to be used as a base for creating your own types from,
+and includes a few helper functions for verifying the claims defined [here](https://tools.ietf.org/html/rfc7519#section-4.1).
+
+```go
+	claims := jwt.StandardClaims{
+		Audience: "myapi"
+		ExpiresAt: time.Now().Add(time.Hour * 72).Unix(),
+	}
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
+```
+
+On the other end of usage all of the `jwt.Parse` and friends got a `WithClaims` suffix added to them.
+
 ## What the heck is a JWT?
 
 In short, it's a signed JSON object that does something useful (for example, authentication).  It's commonly used for `Bearer` tokens in Oauth 2.  A token is made of three parts, separated by `.`'s.  The first two parts are JSON objects, that have been [base64url](http://tools.ietf.org/html/rfc4648) encoded.  The last part is the signature, encoded the same way.
@@ -40,10 +82,10 @@ Parsing and verifying tokens is pretty straight forward.  You pass in the token
 
 ```go
 	// Create the token
-	token := jwt.New(jwt.SigningMethodHS256)
-	// Set some claims
-	token.Claims["foo"] = "bar"
-	token.Claims["exp"] = time.Now().Add(time.Hour * 72).Unix()
+	token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaim{
+		"foo": "bar",
+		"exp": time.Now().Add(time.Hour * 72).Unix(),
+	})
 	// Sign and get the complete encoded token as a string
 	tokenString, err := token.SignedString(mySigningKey)
 ```

example_test.go

@@ -2,7 +2,6 @@ package jwt_test
 
 import (
 	"fmt"
-	"time"
 
 	"github.com/dgrijalva/jwt-go"
 )
@@ -20,20 +19,30 @@ func ExampleParse(myToken string, myLookupKey func(interface{}) (interface{}, er
 }
 
 func ExampleNew(mySigningKey []byte) (string, error) {
-	// Set some claims
-	claim := jwt.MapClaim{
-		"foo": "bar",
-		"exp": time.Now().Add(time.Hour * 72).Unix(),
-	}
-
 	// Create the token
-	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claim)
+	token := jwt.New(jwt.SigningMethodRS256)
+
+	// Set some claims
+	claims := token.Claims.(jwt.MapClaim)
+	claims["foo"] = "bar"
+	claims["exp"] = 15000
 
 	// Sign and get the complete encoded token as a string
 	tokenString, err := token.SignedString(mySigningKey)
 	return tokenString, err
 }
 
+func ExampleNewWithClaims(mySigningKey []byte) (string, error) {
+	// Create the Claims
+	claims := jwt.StandardClaims{
+		ExpiresAt: 15000,
+		Issuer:    "test",
+	}
+
+	token := jwt.NewWithClaims(jwt.SigningMethodRS256, claims)
+	return token.SignedString(mySigningKey)
+}
+
 func ExampleParse_errorChecking(myToken string, myLookupKey func(interface{}) (interface{}, error)) {
 	token, err := jwt.Parse(myToken, func(token *jwt.Token) (interface{}, error) {
 		return myLookupKey(token.Header["kid"])