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.
Fact
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:
-
a Type
Each of these elements are further described below, using the claim fact as an example. See current facts for more examples.
Description
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.
Type
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
}Model
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
ExampleModel
exampleFact1
([] : List ExampleModel )