README.md · typeable/schematic

git.iko.soy/typeable/schematic

on superrecord help sign in

113 lines 4.0 kB history raw

1# schematic

3[![Build Status](https://travis-ci.org/dredozubov/schematic.svg?branch=master)](https://travis-ci.org/dredozubov/schematic)

5## Goal

7The goal of the library is to provide a type-safe transport layer for serializing and validating JSON. It can be thought of as a subset of [json-schema](http://json-schema.org), which is basically a specification of a JSON document. The other goal is getting as much as possible from this specification for free. Right now the following bits are prototyped:

9* All of the instantiations of the transport types structurally follow the schema provided by user

10* Serializers are generic, so they follow from the type-level schema and the're supposed to have a roundtrip property by an implementation.

11* Runtime value validators are generated from the schema. Validation errors are reported as a pairs of a json-path to the element and an error message.

12* There are migrations. It's possible to describe a series of migrations to the schema and have all the necessary machinery to deserialize a user specified version of the schema if there's a few versions.

14## TODO

16* Describing versioned http endpoints

17* Schema pretty-printing

18* More validators

19* Overall user friendliness

21Be aware that library is experimental and subject to change a lot. The current state can be viewed as a prototype.

23## Installation

25* Install [Stack](https://github.com/commercialhaskell/stack)

27```

28$ stack install schematic

29```

31## Basic Examples

33```

34type SchemaExample

35 = SchemaObject

36 '[ '("foo", SchemaArray '[AEq 1] (SchemaNumber '[NGt 10]))

37 , '("bar", SchemaOptional (SchemaText '[TEnum '["foo", "bar"]]))]

38```

40* This schema says that's structurally it's a JSON object which has two fields:

41 * field "foo" contains an array of numeric values

42 * field "bar" contains an optional text value

43* It also allows you to validate JSON values itself:

44 * an array in "foo" contains exactly one element

45 * that element must be strictly greater than 10

46 * value of "bar" field must be either "foo" or "bar" if presented

49This one is valid for example

51```

52schemaJson :: ByteString

53schemaJson = "{\"foo\": [13], \"bar\": null}"

54```

56Also valid

58```

59schemaJson :: ByteString

60schemaJson = "{\"foo\": [13], \"bar\": \"bar\"}"

61```

63it can be parsed and validated like this:

65```

66decodeAndValidateJson schemaJson :: ParseResult (JsonRepr SchemaExample)

67```

69`ParseResult` type encodes three possible situations:

70* json is structurally consistent with a schema and runtime validations pass

71* json source is malformed or doesn't correspond to a schema structurally

72* some of the runtime validations have failed, but it's structurally correct

73 overall

75It implies a transport layer representation of that data that can be traversed and transformed to whatever internal types user has. It's called `JsonRepr`. Type parameter is the schema itself.

78```

79jsonExample :: JsonRepr SchemaExample

80jsonExample = ReprObject $

81 FieldRepr (ReprArray [ReprNumber 12])

82 :& FieldRepr (ReprOptional (Just (ReprText "bar")))

83 :& RNil

84```

86## Migrations

88It's possible to represent schema changes as a series of migrations, which describes a series of json-path/change pairs. Migrations can be applied in succession.

90This piece of code will apply a migration to the schema, decode and validate the latest version.

92```

93type SchemaExample

94 = SchemaObject

95 '[ '("foo", SchemaArray '[AEq 1] (SchemaNumber '[NGt 10]))

96 , '("bar", SchemaOptional (SchemaText '[TEnum '["foo", "bar"]]))]

98type TestMigration =

99 'Migration "test_revision"

100 '[ 'Diff '[ 'PKey "bar" ] ('Update ('SchemaText '[]))

101 , 'Diff '[ 'PKey "foo" ] ('Update ('SchemaNumber '[])) ]

102

103type VS = 'Versioned SchemaExample '[ TestMigration ]