1.0 Title: Data Dictionary Key Code
2.0 Purpose: Key Codes are currently unique tags within any hri07e compliant project that define a data object - be it a number, a string, a line of text, a document, a concept, a computer code variable, a group of people, a report, a type of procedure, or any other item that people use regularly in project work without necessarily defining what they mean by their own reference.
Key Codes are used within hri07e Data Dictionaries and Data Sheets much as variable names are used in computer software code
3.0 Recommended Usage:
The primary use of Key Codes is in Data Sheets which define the engineering parameters
for example: "Failure Rate" means many things to many people - but a dd:ram kc:fr is defined to be <*****> and any data sheet which
are (eventually) intended to provide projects with the capability of automating the calculation of many parameters found in the data sheets.
A Data Dictionary (dd) can be created for any recognized subject discipline to define the jargon and “keycodes” which are to be used in specific way for the general case in whatever organization is using the data dictionary. For an individual project with very specialized or confidential terminology a Project Data Dictionary (pdd) can be created by importing the common terminology and modifying the key codes to the project – however – it is recommended that even in that case the standard definitions be used as much as possible and only the unique jargon be defined in the pdd.
Data Dictionaries can be created for all well recognized disciplines (for example Mechanical Engineering <dd:me>, Chemical Engineering <dd:che>, Finance <dd:fin> and Law <dd:leg>) however there needs to be a “common” data dictionary which is defines key codes which can be used for all classes. For example the artifact filenames starting with the well understood mnemonics a) “txt”, b) “dwg”, c) “doc”, and d) “ppt” are defined to be (in sequence) a) an Ascii or Unicode text message b) a drawing – (not necessarily an AutoCAD drawing) c) a computer formatted document (not necessarily MS Word) and d) a presentation – not necessarily in MS PowerPoint format.
In addition the key codes used to label the Data Dictionaries themselves are defined in the common or “default” Data Dictionary – which in the absence of any DD key code precursor indicates that the key code is defined in the common DD. For example ME = Mechanical Engineering is assumed to be the “common” usage. There are debatable cases – for example EE means Electrical Engineering whether or not Electronics Engineers (ElE) because the author of the common DD said so.
4.1 Organizational Data Dictionaries
There should be a standard Data Dictionary for each organization created once and continuously maintained. As much as possible the organization should license the Data Dictionary from the Domain Authorities for the subject matter area rather than attempt to create new Data Dictionaries for “Mechanical Engineering” for example. Trying to duplicate that sort of effort is both costly and hazardous as the whole idea of Domain Authorities is to develop a consistent and accurate view of the domain subject matter by means of excellence in research and experience.
4.2 Project Data Dictionaries
Projects are free to develop their own Data Dictionaries for specific aspects of the project. Duplicating and (especially) re-defining organizational and external keycodes and nomenclature is not recommended however.
4.3 External Data Dictionaries.
5.1 dd1 Data Dictionary irap08c.doc
5.2 dd1 List of data dictionaries r0 irap08c.xls
5.3 dd2 Contract Deliverable Item Descriptions irap08c.doc
5.4 dd3 Contract Deliverable Rquirements List CDRL irap08c.doc
5.5 dd4 Data Sheets irap08c.doc
5.6 http://en.wikipedia.org/wiki/Controlled_vocabulary
6.0 Responsibility:
There will be a designated DD Authority for each Data Dictionary domain who will control the definition within the Data Dictionary and the contents of the cdid’s to the standards of the DD and of the work order involved.
7.0 Ownership: dd01 Data Dictionary hri07e.doc is the intellectual and physical property of Hammond River Institute
There are other potential owners for Data Dictionaries
- the organization
- the project
In the preferred best case the Data Dictionary is owned by the most prominent internationally recognized authority on the subject matter domain being defined by the Data Dictionary.
8.0 Level of Effort (costs)
Data Dictionaries can be very expensive and time consuming and therefore Project Managers should avoid creating their own except where the project jargon is new or unique – in which case the key codes and cdid’s should be added to the corporate or public data dictionary, unless Intellectual Property or National Security considerations prevent that.
9.0 Risks
If a key code is improperly defined or its derivation is in error – and this results in a loss of life, injury or major property or environmental damage then there is nothing to protect the author and publisher from legal action within the scope of this project. Even if the information is absolutely correct but has been improperly used by untrained or reckless users; the author can expect to be blamed in some jurisdictions. Disclaimers should be built in to advise the end user of the limitations and assumptions of the various calculations and procedures.
10.0 CONTENTS:
10.1.2 Data Dictionary Key Code: DD (required)
This is the “key code” <see item > for the professional discipline that is responsible for the accuracy and application of the various data key codes which are defined within the dictionary. These are typically engineering disciplines but by no means limited to that. Any recognizable profession with a visible Special Interest Group discipline which feels a need to clarify and standardize the use of terminology should establish its own Data Dictionary and key codes. The list of Data Dictionaries for HRI is to be kept as an Annex to this CDID (c05) as c05 Annex A and will be under the control of the office in section 6.0.
some example current key codes are:
EE = Electrical Engineering
ME = Mechanical Engineering
Arch = Architecture
CE = Civil Engineering
ChE = Chemical Engineering
EnE = Electronics Engineering
PM = Project Management
Fin = Finance
Lgl = Legal
It should be noted that many engineering disciplines use identical or nearly identical notation for any number of terms and that simply defining the key code is unlikely to prevent misuse of the defined quantity. The context DD is intended to do that, and the DD responsible officers must ensure that their own DD is consistent and unique.
10.1 Header Information
10.1.1 Data Dictionary Keycode
The Data Dictionary Keycode is the shortest, meaningful acronym which can be used to identify a discipline for the largest audience of users. This becomes a compromise between re-typing longer acronyms and a lack clarity or a non-unique dd code. (A very similar problem to website URL’s)
10.1.2 Data Dictionary Title
10.1.3 Data Dictionary
10.1.4 Owner
the Data Dictionary keycode files will have the following filename structure:
dd<variable keycode> <variable keycode label> <work order>.<file extension>
10.1.2.1a DD Title
The full title of the DD key code should be included in the long form of each DD page.
10.1.2.2 Key Code (required) example: rho (gas density)
10.1.2.2.1 Key Code Symbol example: ρ (rho)
10.1.2.2.2 Key Code Label example: Density
10.1.2.2.3 Key Code Mnemonic example: gasdens
10.1.2.2.4 Key Code Title example: "Nominal Gas Density "
This should be a meaningful, but not exhaustive, title of the key code data item and while it may nor be unique within the Data Dictionary it should not be confusing with closely coupled data items which are likely to be used “nearby
This should be a terse, non-definitive summary of the nature and use of the data variable suitable for “pop-ups” and help screens. A full explanation should be reserved for the Description.
This should be a reasonably complete explanation of the data item. There is no shame in to reusing other peoples work – however, citation and attribution must be made, as well as some assurance the reference can be found.
This is the defining algebraic form of the key code symbol.
For keycodes which have mathematical significance (i.e. are mathematical expressions and can be calculated directly, with numerical methods or simply can be expressed with mathematical principles) the reference to derivation of the keycode should be include. Simpler models may derived as part of the Data Dictionary reference page but this should only be done in the shortest of derivations.
Full attribution of the derivation is not only a courtesy – it is a ethical requirements and plagiarism is one of the few misdemeanors that will be cause for direct action by the HRI community.
10.1.2.9 Technical Authority
10.1.2.10 Signing Authority
10.1.2.11 Citations
10.1.2.12 Tutorial
10.1.2.13 Revision History
10.2 CDID’s (Contract Deliverable Item Definitions)
CDID files will have the following filename structure
dd<cdid keycode> <cdid label> <work order>.<file extension>
Example CDID’s are:
dd01 Data Dictionary hri07e.doc (this document)
ram1629a Failure Modes, Effects Analysis hri07e.pdf (from ddRAM)
fin02 Business Plan hri07e.doc (a CDID for Business Plans)
dd04 Data Sheet hri07e.doc (the CDID for Data Sheets)
dd02 Contract Deliverable Item Description hri07e.doc (the CDID about CDID’s)
10.3 Data Sheet Examples & Templates
Data Sheet examples and Template files will have the following filename structure:
ds<system id> <system item label “Example” or “Template”> <dd work order>.<file extension>
10.2 CDID’s (Contract Deliverable Item Definitions)
CDID files will have the following filename structure
dd<cdid keycode> <cdid label> <work order>.<file extension>
Example CDID’s are:
dd01 Data Dictionary hri07e.doc (this document)
ram1629a Failure Modes, Effects Analysis hri07e.pdf (from ddRAM)
fin02 Business Plan hri07e.doc (a CDID for Business Plans)
dd04 Data Sheet hri07e.doc (the CDID for Data Sheets)
dd02 Contract Deliverable Item Description hri07e.doc (the CDID about CDID’s)
10.3 Data Sheet Examples & Templates
Data Sheet examples and Template files will have the following filename structure:
ds<system id> <system item label “Example” or “Template”> <dd work order>.<file extension>
Example Data Sheets are:
dd04 PEMFC02 Nexa Fuel Cell hri07e.xls
<dd:km kc:km3type>
11.0 Metadata (Data Typing)
The Data Dictionary is intended to be the driving force in the ability of the information system to automate its functionality using key codes. The Data Sheets and Data Dictionary are themselves human readable documents - but the formats and the “relationship” descriptions are intended to be directly translatable into XML and RDF procedures. The CDID section 11’s should follow this pattern and be consistent with the Data Sheets in their reference calculation descriptions.
Future Data Dictionaries can be expected to define their key codes in ways that permit the codes to be machine read and the data from data sheets extracted and generated by procedures which may or may not be part of other data dictionaries.
<dd:km kc:policy>
12.0 File Handling Policy
12.1 Backup
Backup policies must be stated for time of retention
12.2 Privacy
PIPEDA (Canada), Sorbanes Oxley (USA) and equivalent privacy handling methods must be specified.
12.3 Security
Appendix:
How to create a Data Dictionary for web publication: