Autodocodec

Autodocodec is short for "self(auto)- documenting encoder and decoder".

In short: You write a single instance, of the 'Codec' type-class, for your type, and you get:

• A 'ToJSON' instance from 'aeson' with both a toJSON and toEncoding implementation
• A 'FromJSON' instance from 'aeson'
• A 'ToYaml' instance from 'yaml'
• A json schema
• A nicely-coloured human-readable yaml schema
• A Swagger schema
• An Openapi schema
• A Nixos module type

See the golden test directory directory for example outputs.

Features

• ✓ Correct-by-construction encoding and decoding, without generating code.
• ✓ Generate automatically-correct documentation from code.
• ✓ Support for recursive types.

State of this project

This project is ready to try out!

Fully featured example

{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE DerivingVia #-}
{-# LANGUAGE TypeApplications #-}
module Main (main) where


import Autodocodec
import Autodocodec.Yaml
import GHC.Generics
import Data.Aeson (FromJSON, ToJSON)
import Data.Text (Text)
import qualified Data.Text as T

data Example = Example
  { exampleTextField :: !Text,
    exampleIntField :: !Int
  }
  deriving stock (Show, Eq, Generic)
  deriving
    ( FromJSON, -- <- FromJSON instance for free.
      ToJSON  -- <- ToJSON instance for free.
    )
    via (Autodocodec Example)

instance HasCodec Example where
  codec =
    object "Example" $
      Example
        <$> requiredField "text" "documentation for the text field" .= exampleTextField
        <*> requiredField "int" "documentation for the int field" .= exampleIntField

main :: IO ()
main =  do
  let schema = T.unpack $ renderColouredSchemaViaCodec @Example
  putStrLn schema

This will output a nice coloured yaml-schema:

# Example
text: # required
  # documentation for the text field
  <string>
int: # required
  # documentation for the int field
  <integer> # 64 bit int

Tests

While we don't provide any actual guarantees, we do have tests for the following properties that we would like to maintain:

• Encoding and decoding roundtrips through JSON.
• For standard types, encoding behaves in the same way that aeson does.
• Error messages for decoding are still good.
• Generated human-readable documentation looks good.
• Generated JSON schemas look good.
• Generated Swagger schemas look good.
• Generated OpenAPI schemas look good.
• Generated values are accepted by the corresponding generated JSON schemas.
• Generated values are accepted by the corresponding generated Swagger schemas.
• Generated values are accepted by the corresponding generated OpenAPI schemas.
• Encoding and decoding roundtrips through YAML.
• We try to make sure that backward compatibility is maintained.
• Codecs are more or less inspectable.
• Encoding and decoding is still fast