event-data-model theory

This section will expound on the key ideas presented in the introduction. facts, the data model and tags are the focus of this section.

See the asclepias documentation for more details on event and context.


What is a fact?

A Fact is metadata attached to an event. Typically a Fact will allow for distinguishing one event from another for the purpose of classification and analysis. The only limitation in defining a Fact is that it must be expressible as a Dhall type. A Fact may, for example, contain other Fact s.

For concrete examples, see the current facts section of fact-models.

Anatomy of a Fact.dhall File

Fact information is stored in dhall files. These dhall files live in fact-models, under the src and Facts directories. Fact types are meant to be concise, modular, and ultimately nested into a single Fact type, which corresponds to a top-level variant of a Model.

A Fact.dhall file consists of 4 key elements:

Each of these elements are further described below, using the claim fact as an example. See current facts for more examples.


A description is included for documentation purposes. It contains information on what the fact is, and how it should be used. An example of a description is included below.

{- 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[] -}

The syntax of the description is important. AsciiDoc syntax is required in order for the text to render on Noviverse correctly.


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

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

a union type (also refered to as a sum type) with non-empty variants:

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

or a union type with empty variants:

let ServiceLocation = < Inpatient | Outpatient >

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

let ClaimFact =
      { claim : claim.Type
      , cost : Optional cost.Type
      , provider : Optional provider.Type
      , service : Optional service.Type


Each fact file must contain at least one example. The example must include at least one fact. Below is an example for the Claim fact.

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


What is a model?

A Model is a placeholder for some choice of one among a selection of Facts. It is implemented as a sum type in Dhall, with a different Fact for each 'variant', meaning possible value, of the Model. For example, a ClaimsModel can denote Demographic, or Death or any of the other Fact s listed among its possibilities. A Model should not contain other Model s. In that sense a Model is at the top level of a collection of Fact s, defining all possible Fact s that might be used as metadata for events in some particular application.

For concrete examples, see the current models section of fact-models.

Anatomy of a Model.dhall File

Model information is also stored in dhall files. These dhall files live in fact-models, under the src and Models directories. Model types are meant to be union type, where the variants are Fact types. (A variant need not have an associated Fact type, however. Death in ClaimsModel is an example.) Since Fact types themselves can be unions of other Fact types, a Model is not so different from a Fact. A Model.dhall file contains the same sections as a Fact.dhall file.

See anatomy of a fact for a complete description of these 4 key elements.

Below is an example of a complete model. Other examples may be found in the current models section.

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

An example data model.

{- end::description[] -}

let Model = ../../utils/Model.dhall

let facts = ../../Facts/package.dhall

let ExampleModel =
      < FooPlan : facts.plan.Type
      | Bar
      | BazValue : facts.tn_value.Type

let exampleFact1
    : ExampleModel
    = ExampleModel.FooPlan facts.plan.examples.head

in Model
      ([] : List ExampleModel )


What is a tag?

Tags summarize the Model. If the Model and its Fact s provide the information with which to distinguish events, Tags provide the group labels to classify events based on that information. The TagSet type in an asclepias project corresponds to the Tags here.