collection-json

Collection+JSON—Hypermedia Type tools for Haskell.

By Alex Brandt. Source at https://github.com/alunduil/collection-json.hs.

collection-json lets you encode, decode, and manipulate application/vnd.collection+json documents. The library exposes a single module, Data.CollectionJSON, with aeson ToJSON/FromJSON instances for each type defined by the spec—Collection, Item, Link, Query, Template, Datum, and Error.

Install

You need the Glasgow Haskell Compiler (GHC) and cabal-install.

Add collection-json to the build-depends of your package, or install it directly:

cabal install --lib collection-json

CHANGELOG.md records what changed in each release.

Usage

Roundtrip a minimal collection through aeson:

{-# LANGUAGE OverloadedStrings #-}

import Data.Aeson (decode, encode)
import qualified Data.ByteString.Lazy.Char8 as BL
import Data.CollectionJSON (Collection (..))
import Data.Maybe (fromJust)
import Network.URI (parseURI)

main :: IO ()
main = do
  let c =
        Collection
          { cVersion = "1.0"
          , cHref = fromJust (parseURI "http://example.com/friends/")
          , cLinks = []
          , cItems = []
          , cQueries = []
          , cTemplate = Nothing
          , cError = Nothing
          }
      json = encode c

  BL.putStrLn json
  -- {"collection":{"href":"http://example.com/friends/","version":"1.0"}}

  print (decode json :: Maybe Collection)
  -- Just (Collection {cVersion = "1.0", cHref = ..., ...})

Full API reference on Hackage. The Collection+JSON specification is at https://github.com/collection-json/spec.

Scope

collection-json stops at the wire format: it models the envelope and bridges your domain types through FromCollection/ToCollection, but leaves content negotiation, profile semantics, and request-shape validation to adjacent layers. For href values, network-uri-json provides Network.URI JSON instances that compose with these types.

Contributing

Report bugs and feature requests on the issue tracker. See CONTRIBUTING.md for the build, test, formatter, branch, and release conventions. CODE_OF_CONDUCT.md covers how contributors treat each other.

Support is free and comes from one maintainer working in spare time.

License

Use, modify, and redistribute this library, including inside proprietary software, as long as you keep the copyright and permission notices. LICENSE reproduces the MIT license in full.