Set Best Practices for the Harmonized Data Store

This is a composite decision for different practices adopted for the HDS

The Standard is Described in Normative Standards Documents Available on the Wiki

Parent: OIDL-0002 - Data Architecture

Context and Problem Statement

The Architecture of openIDL must we well documented in a formal way.  Usually, standards organization create a normative document.  This document must provide enough information for a reader to understand what is being standardized and enough detail to be used as a guide to understand if the standard is being followed. 

Decision Drivers

• the standard must be readable by all members of the openIDL community
• the standard must be available in a document form that can be shared outside the wiki (not with just a link)
• the standard must be version controlled with change log
• the breakdown of possible documentation is
  • an overall standard for openidl data handling which describes the injestion/submission, at rest expectations, extraction, network transmission, lifecycle, reporting and sharing

Considered Options

• readme files and code in the github repository
• Use and Industry template like IEEE standard template attached.  See attachments.

All Reference Data Rows have Effective and Expiration Date

Validation Rules Verify That Data Loaded Does Not Use Codes Outside their Effective Date Range

Special Value for Beginning of Time is 1900-01-01

Special Value for End of Time is 9999-12-31

Null Values Are Handled on a Per Field Basis

sometimes allow null value 

sometimes use special value to describe field is null

only use for string fields

do not use for dates, numerics or boolean fields

Context and Problem Statement

{Describe the context and problem statement, e.g., in free form using two to three sentences or in the form of an illustrative story. You may want to articulate the problem in form of a question and add links to collaboration boards or issue management systems.}

Decision Drivers

• {decision driver 1, e.g., a force, facing concern, …}
• {decision driver 2, e.g., a force, facing concern, …}
• …

Considered Options

• {title of option 1}
• {title of option 2}
• {title of option 3}
• …

Decision Outcome

Chosen option: "{title of option 1}", because {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.

Consequences

• Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
• Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
• …

Validation

{describe how the implementation of/compliance with the ADR is validated. E.g., by a review or an ArchUnit test}

Pros and Cons of the Options

{title of option 1}

{example | description | pointer to more information | …}

• Good, because {argument a}
• Good, because {argument b}

• Neutral, because {argument c}
• Bad, because {argument d}
• …

{title of other option}

{example | description | pointer to more information | …}

• Good, because {argument a}
• Good, because {argument b}
• Neutral, because {argument c}
• Bad, because {argument d}
• …

More Information

{You might want to provide additional evidence/confidence for the decision outcome here and/or document the team agreement on the decision and/or define when this decision when and how the decision should be realized and if/when it should be re-visited and/or how the decision is validated. Links to other decisions and resources might here appear as well.}