Modulecanonical-json-0.6.0.1Haskell2010

Text.JSON.Canonical

An implementation of Canonical JSON.

http://wiki.laptop.org/go/Canonical_JSON

The "canonical JSON" format is designed to provide repeatable hashes of JSON-encoded data. It is designed for applications that need to hash, sign or authenitcate JSON data structures.

The format is an extended subset of the normal JSON format.

Canonical JSON is parsable with any full JSON parser, and it allows whitespace for pretty-printed human readable presentation, but it can be put into a canonical form which then has a stable serialised representation and thus a stable hash.

The basic concept is that a file in the canonical JSON format can be read using parseCanonicalJSON. Note that this input file does not itself need to be in canonical form, it just needs to be in the canonical JSON format. Then the renderCanonicalJSON function is used to render into the canonical form. This is then the form that can be hashed or signed etc.

The prettyCanonicalJSON is for convenience to render in a human readable style, since the canoncal form eliminates unnecessary white space which makes the output hard to read. This style is again suitable to read using parseCanonicalJSON. So this is suitable to use for producing output that has to be later hashed or otherwise checked.

Known bugs/limitations:

Decoding/encoding Unicode code-points beyond U+00ff is currently broken

5 types
5 classes
10 values

Packagecanonical-json-0.6.0.1
Exports20
LanguageHaskell2010
LicenceBSD-3-Clause
SourceCanonical.hs

Types

3 declarations

datadata JSValue

Constructors

Instances7Eq, Ord, Read, Show, NFData, FromJSON, …

Eq JSValueDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Ord JSValueDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Read JSValueDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Show JSValueDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
NFData JSValueDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Monad m => FromJSON m JSValueDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
Monad m => ToJSON m JSValueDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class

newtypenewtype Int54

54-bit integer values

JavaScript can only safely represent numbers between -(2^53 - 1) and 2^53 - 1.

TODO: Although we introduce the type here, we don't actually do any bounds checking and just inherit all type class instance from Int64. We should probably define fromInteger to do bounds checking, give different instances for type classes such as Bounded and FiniteBits, etc.

Instances17Bounded, Enum, Eq, Integral, Data, Num, …

Bounded Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Enum Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Eq Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Integral Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Data Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Num Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Ord Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Read Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Real Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Show Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Ix Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Bits Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
FiniteBits Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Storable Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
PrintfArg Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
ReportSchemaErrors m => FromJSON m Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
Monad m => ToJSON m Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class

newtypenewtype JSString

Canonical JSON strings are in fact just bytes.

Instances13Eq, Ord, Read, Show, IsString, Semigroup, …

Eq JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Ord JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Read JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Show JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
IsString JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Semigroup JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
Monoid JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
PrintfArg JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
NFData JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Types
ReportSchemaErrors m => FromJSON m JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
Monad m => FromObjectKey m JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
Monad m => ToJSON m JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
Monad m => ToObjectKey m JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class

Parsing and printing

3 declarations

valueparseCanonicalJSON :: ByteString -> Either String JSValue

Parse a canonical JSON format string as a JSON value. The input string does not have to be in canonical form, just in the "canonical JSON" format.

Use renderCanonicalJSON to convert into canonical form.

valuerenderCanonicalJSON :: JSValue -> ByteString

Render a JSON value in canonical form. This rendered form is canonical and so allows repeatable hashes.

For pretty printing, see prettyCanonicalJSON.

NB: Canonical JSON's string escaping rules deviate from RFC 7159 JSON which requires

"All Unicode characters may be placed within the quotation marks, except for the characters that must be escaped: quotation mark, reverse solidus, and the control characters (U+0000 through U+001F)."

Whereas the current specification of Canonical JSON explicitly requires to violate this by only escaping the quotation mark and the reverse solidus. This, however, contradicts Canonical JSON's statement that "Canonical JSON is parsable with any full JSON parser"

Consequently, Canonical JSON is not a proper subset of RFC 7159.

valueprettyCanonicalJSON :: JSValue -> String

Render a JSON value in a reasonable human-readable form. This rendered form is not the canonical form used for repeatable hashes, use renderCanonicalJSON for that.

Type classes

8 declarations

classclass ToJSON (m :: Type -> Type) a where

Methods

toJSON :: a -> m JSValue

Instances6ToJSON

Monad m => ToJSON m Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
Monad m => ToJSON m JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
Monad m => ToJSON m JSValueDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
Monad m => ToJSON m StringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
(Monad m, ToJSON m a) => ToJSON m [a]Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
(Monad m, ToObjectKey m k, ToJSON m a) => ToJSON m (Map k a)Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class

classclass FromJSON (m :: Type -> Type) a where

Methods

fromJSON :: JSValue -> m a

Instances6FromJSON

ReportSchemaErrors m => FromJSON m Int54Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
ReportSchemaErrors m => FromJSON m JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
ReportSchemaErrors m => FromJSON m StringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
Monad m => FromJSON m JSValueDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
(ReportSchemaErrors m, FromJSON m a) => FromJSON m [a]Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
(ReportSchemaErrors m, Ord k, FromObjectKey m k, FromJSON m a) => FromJSON m (Map k a)Defined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class

classclass ToObjectKey (m :: Type -> Type) a where

Used in the ToJSON instance for Map

Methods

toObjectKey :: a -> m JSString

Instances2ToObjectKey

Monad m => ToObjectKey m JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
Monad m => ToObjectKey m StringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class

classclass FromObjectKey (m :: Type -> Type) a where

Used in the FromJSON instance for Map

Methods

fromObjectKey :: JSString -> m (Maybe a)

Instances2FromObjectKey

Monad m => FromObjectKey m JSStringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class
Monad m => FromObjectKey m StringDefined in canonical-json-0.6.0.1 · Text.JSON.Canonical.Class

classclass (Applicative m, Monad m) => ReportSchemaErrors (m :: Type -> Type) where

Monads in which we can report schema errors

Methods

expected :: Expected -> Maybe Got -> m a

typetype Expected = String

typetype Got = String

valueexpectedButGotValue :: ReportSchemaErrors m => Expected -> JSValue -> m a

Utility

6 declarations

valuetoJSString :: String -> JSString

valuefromJSString :: JSString -> String

valuefromJSObject :: ReportSchemaErrors m => JSValue -> m [(JSString, JSValue)]

valuefromJSField

:: (ReportSchemaErrors m, FromJSON m a)
=> JSValue
-> JSString
-> m a

Extract a field from a JSON object

valuefromJSOptField

:: (ReportSchemaErrors m, FromJSON m a)
=> JSValue
-> JSString
-> m (Maybe a)

valuemkObject :: Monad m => [(JSString, m JSValue)] -> m JSValue