aeson-deriving: data types for compositional, type-directed serialization

[ library, mit, serialization ] [ Propose Tags ]

Please see the README on GitHub at

[Skip to Readme]
Versions [RSS] [faq], 0.1.1,,
Change log
Dependencies aeson (>=1.2 && <1.6), base (>=4.7 && <5), regex-tdfa, text, unordered-containers [details]
License MIT
Copyright 2020
Author Cliff Harvey
Category Serialization
Home page
Bug tracker
Source repo head: git clone
Uploaded by Cliff_Harvey at 2020-10-10T12:36:49Z
Distributions NixOS:
Downloads 680 total (28 in the last 30 days)
Rating (no votes yet) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Hackage Matrix CI
Docs available [build log]
Last success reported on 2020-10-10 [all 1 reports]


[Index] [Quick Jump]


Maintainer's Corner

For package maintainers and hackage trustees


Readme for aeson-deriving-

[back to package description]


Build Status Hackage

Define JSON encoding and decoding behavior in a unified way with DerivingVia. This ensures the instances for the two aeson type classes stay in sync and eliminates much needless boilerplate, besides supporting many extra features.

Uses and examples

Basic encoding options & common patterns

Aeson's generics support governs the basic mapping between Haskell definitions and the JSON format. This functionality, along with its tunable parameters, can be specified with the GenericEncoded newtype.

type MyEncoding = GenericEncoded
  '[ ConstructorTagModifier := SnakeCase  -- extensible function support
  , FieldLabelModifier :=
      [ SnakeCase, DropSuffix "_" ]       -- functions can be composed
  , SumEncoding := TaggedObject "type" "contents"

data User = User
  { firstName :: Text
  , id_       :: UserId
  , companyId :: CompanyId
  deriving stock (Generic, Show)
  deriving (FromJSON, ToJSON)
    via MyEncoding User

data Document = Document
  { name      :: Text
  , id_       :: Int64
  , companyId :: CompanyId
  , parts     :: [SubDocument]
  deriving stock (Generic, Show)
  deriving (FromJSON, ToJSON)
    via MyEncoding Document

-- >>> encode (User "jake" 1 29)
-- { "type": "user", "first_name": "jake", "id": 1, "company_id": 29}

Modifier newtypes

Constrant Fields

data Transaction = Transaction
  { transactionId :: UUID }
  deriving stock (Generic, Show)
  deriving (FromJSON, ToJSON) via
     '[ "version" := "1.0"
      , "system_info" := "👍"
      (MyEncoding Transaction)

Note: Some newtypes that modify the instances come in an inbound and outbound variant. For example WithConstantFields is defined as the composition of WithConstantFieldsIn and WithConstantFieldsOut.

Constant Objects

Sometimes you may need an entire object of constant fields, with no information passing to the haskell representation. This is modeled as a single-value type and can also be used with the WithConstantFields newtype, as long as the base type is wrapped in the EmptyObject newtype (because otherwise unit types do not serialize to the empty object by default).

data Requirements = Requirements
  deriving (Show, Eq, Generic)
  deriving (FromJSON, ToJSON) via
     '[ "api_version" := "2.0"
      , "check_performed" := 'True
      (EmptyObject Requirements)

Apply arbitrary functions before encoding/decoding

Example: Special treatment for magic values
data Feedback = Feedback
  { comment :: Text }
  deriving stock (Generic, Show)
  deriving (FromJSON, ToJSON) via
    ModifyFieldIn "comment"
      ("booo!" ==> "boo-urns!")
      (MyEncoding Feedback)

-- x ==> y  maps the value x to y and leaves others unchanged
-- Implement your own instances of `KnownJSONFunction` for other behavior

Preventing infinite loops

Newtypes that modify an inner type class instance must be careful not to do so in an infinitely recursive way. Here the inner type should use the generic-based instance, rather than reference the instance being defined.

This package employs a custom compiler error to prevent this very easy mistake.

Improved error messages for sums of records

See RecordSumEncoded documentation.

To be expanded...