fact-models Developer Guide

Nix Setup

To develop within event-data-model, and to use the fact-models tool we recommend using a development shell defined in flake.nix. This guarantees applications are pinned to the same version as other developers and the CI.

For instructions on installing nix, see the nsBuild setup instructions.

For information on nix usage, see the nsBuild usage guide.

Versioning

Versioning of fact-models and other packages in this repository follow semantic versioning (MAJOR.MINOR.PATCH), where you increment:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards compatible manner
PATCH version when you make backwards compatible bug fixes

In particular, adding new facts or models typically only requires a MINOR update, while changing the shape of existing facts or models should trigger a MAJOR update. Bug fixes to the library functions should only trigger a PATCH update.

Tests

An important part of this repository are the integration tests that ensure that application logic is correct and that data can be marshalled to/from applications as appropriate.

This page documents checks done in this repo and where they are found.

Table 1. Tests
Description Notes Implemented

Serialization of facts and models in Haskell, Dhall, and JSON

See fact-models/internal/Tests.hs module for code that generates tests. The makeFactIOTest (or makeFactIOTestWithDepth) function test the following properties:

  1. Haskell → dhall → Haskell === Haskell

  2. dhall → json → Haskell === Haskell

  3. dhall → json → Haskell === Haskell ← json ← Haskell

  4. dhall → Haskell → json === json ← dhall

The testFactExamplesJSON (testModelExamplesJSON) function tests that:

  1. Fact-examples.json → Haskell (Model-examples.json → Haskell)

See fact-models/src/Models/ClaimsModel/Tests.hs for example usage.

Each model needs to call the test functions in a test module.

Yes, though see note.

Eventlines values produced by upstream processes can be marshalled to/from Haskell applications

No

Notable Indirections

This sections tries to document where and why the structure of certain parts of the repository may not be straightfoward.

  • Tests for models are not automatically created in the fact-models library. Model creators should create a Test module for their model, and add those tests to the main Test module.

  • This repo uses ormolu for Haskell formatting. Other repos such as asclepias use brittany, but as of 2022-04-22 brittany yields errors likely due to incompatability with template haskell.

  • The build-fragments application (see flake.nix in project root) creates a dhall file than be used to check the integrity of each Fact.dhall (or Model.dhall) file. This is checked by the check-fragments.sh check (see flake.nix) with dhall freeze $1 --check --all. This also serves to check that the fragments are up-to-date assuming that the fragments are only created by build-fragments and not edited otherwise.