Anatomy of a `Fact.dhall` file

A Fact.dhall consists of 4 key elements:

a description
a Type
a corresponding predicate Type
examples

Each of these elements are further described below, using the claim fact as an example.

This documentation does not use AsciiDoctor’s callouts. It should, but at the time of this writing, Dhall’s linter removes the end of line of comments.

Description

The description should describe how the fact should be used.

{-|
{- tag::description[] -}

= Claim

The claim fact is used to capture claim information
about an event.
This would most commonly be used in insurance claim data.

{- end::description[] -}
-}

Description text must be written:

in AsciiDoc syntax
within the Dhall comment header and enclosed by {- tag::description[] -} and {- end::description[] -},
include an AsciiDoc level 0 section with the fact’s name:
```
= Some name
```

Type

A fact’s type specifies what data a fact may contain. Fact types may either be a record or a union type.

let Claim =
      { id : Text
      , claim_type : Optional Text
      , index : Optional Integer
      , procedure : Optional Text
      }

The Claim fact defined above is a record type with 4 fields, only one of which is required: id.

View example json for Claim fact

{ "id": "abcd" }

{ "id": "abcd", "claim_type": "some_type", "index": 1 }

Facts can be composed of other facts. The ClaimsFacts type, for example, includes the claim field which contains a Claim fact:

let claim = ../Claim/Fact.dhall
      { claim : claim.Type
      , cost : Optional cost.Type
      , provider : Optional provider.Type
      , service : Optional service.Type
      }

let combineClaimCost =

The ServiceLocation fact is an example of union type, in this case simply enumerating the possible locations:

let ServiceLocation = < Inpatient | Outpatient >

The TNValue fact in an example of union type which contains values. This fact specifies that a value of its type must either be a TextValue containing Text or a NumberValue containing a number.

let TNValue = < NumberValue : Double | TextValue : Text >

The Dhall types are used to automatically generate Haskell types, so the types need to conform to Haskell requirements. Specifically,

The word type cannot be used as a record key.
Names of union type variants must start with a capital letter. For example, this will successfully generate Haskell code:
```
< Foo : Text | Bar >
```
while this will not:
```
< Foo : Text | bar >
```

PredCons Type

Every fact type has a corresponding predicate constructor (PredCons) type. This type specifies how predicates of the fact type are defined based on the predicate logic.

The Claim fact, for example, specifies that predicates may only be defined on the claim_type field:

let exampleFact1

Future versions of the fact-models packages may automatically derive the predicate constructor shape(s). For now, it must be defined by the developer.

Examples

Each fact file must contain examples of values of the fact, predicate constructors of the fact, and the value (True or False) of what the predicate should return for a given fact. See the complete fact an example.

    = { id = "foo"
      , claim_type = None Text
      , index = Some +7
      , procedure = None Text
      }

let exampleFact2

The fact-models utilities contains Dhall functions for combining facts from other facts. See the functions in fact-models/src/utils/example_utils.dhall.

At least one example is required; more examples are highly encouraged.

Complete fact

The result of compiling a Fact.dhall file is required to be a particular shape. The Dhall function in fact-models/src/utils/Fact.dhall takes the Type, predicate constructor Type, and examples to create a value of the required shape. The following is an outline of how a Fact.dhall might be structured, minus the description.

let Fact = ../../utils/Fact.dhall

let MyType = <...>

let MyTypePredCons = <...>

let exampleFact1 = <...>

let exampleFact2 = <...>

let examplePredCons1 = <...>

let examplePredCons2 = <...>

in Fact
    MyType
    MyTypePredCons
    { shouldbe = True, notion = examplePredCons1, fact = exampleFact1 }
    [{ shouldbe = True, notion = examplePredCons2, fact = exampleFact2 }]

The following shows a complete example of a working Fact.dhall file.

{-|
{- tag::description[] -}

= Claim

The claim fact is used to capture claim information
about an event.
This would most commonly be used in insurance claim data.

{- end::description[] -}
-}
let Fact = ../../utils/Fact.dhall

let Claim =
      { id : Text
      , claim_type : Optional Text
      , index : Optional Integer
      , procedure : Optional Text
      }

let exampleFact1
    : Claim
    = { id = "foo"
      , claim_type = None Text
      , index = Some +7
      , procedure = None Text
      }

let exampleFact2
    : Claim
    = { id = "foo"
      , claim_type = Some "notbar"
      , index = Some +7
      , procedure = None Text
      }



in  Fact
      Claim
      exampleFact1
      [ exampleFact2 ]