Glossary of Florida Department of Transportation (FDOT) for Element Naming Conventions

Florida Department of Transportation

Naming Conventions

Attributes, Columns and Elements
Data Administration
2/28/2012

 

Document the naming conventions used by the Florida Department of Transportation (FDOT) for naming Repository Elements.

Purpose

To define and document the naming conventions used by the Florida Department of Transportation (FDOT) for naming Repository elements and database table columns.

References

Naming Conventions – Physical Object Naming

Definitions

Abbreviation – A shortened form of a word or phrase. To make shorter by leaving out or substituting letters.

Acronym – a word formed from the first, or first few, letters of a series of words. E.g. radar = radio detecting and ranging.

Attribute – Represents a type of characteristic or property associated with a set of real or abstract things (people, places, events, and so on). An attribute is the logical equivalent to a column.

Business Name – A name provided for a discrete item of data that is recognized and understood by the business user or organization.

CASE– Computer Aided Software Engineering. Computer Aided Systems Engineering. A category of tools used to develop and deploy computer application software. All aspects of the software development process are documented in the tool from initial requirements to code development, testing and deployment.

COBOL – Common Business Oriented Language. A computer programming language developed for use in developing business related software.

Column – The physical implementation of an attribute in a database.

Element – An abstract item that forms the basis for attributes and columns. An attribute is a relationship between an element and an entity. A column is a relationship between an element and a table.

ERwin – The CA-ERwin data modeling tool used by FDOT to define and document data models and entity relationship diagrams.

Gen – The CA-Gen case tool. Used to define, produce and deliver application systems.

Glossary – A list of words or phrases with definitions and abbreviations.

Initialism – an acronym or abbreviation formed from the initial letters. Specifically one pronounced using he letters names rather than phonetically. E.g. CD for Compact Disk, DNA for Deoxyribonucleic Acid, UHF for Ultra High Frequency

Metadata – information or data about other data or the containers of the data.

Repository – The CA Repository for z/OS automatically captures business and technical metadata about program code, database catalogs and data modeling, providing you with a roadmap to your information assets. A software application designed to store, organize and make available electronically and organization’s metadata.

Repository Glossary – A list of business terms, words and phrases, with their abbreviations.

Background

This procedure was developed to document the naming conventions used to construct names for Repository Elements, Entity Attributes and Table Columns.

Procedure

Business Name

For the purposes of this document and Attribute name and a Business name are the same name. ERwin uses the “Attribute” term and the Repository uses the “Business” term.

Naming Rules

  • Order of terms from left to right:
    • Prime business term for the object being referenced. A noun.
    • Qualifier or modifier terms – usually adjectives or other nouns that qualify the context of the prime business term.
    • Class term.
  • Terms in a name should be limited to nouns and adjectives. These identify things and satisfy a primary concern of data modeling which is to answer the “What is it?” and “What does it look like?” questions. Verbs and adverbs, which represent actions or the “How is it done?” question, should be carefully scrutinized when they show up in a name. A process definition, code table or list of values may be lurking nearby.
  • Business names are limited to no more than 32 characters. The Repository and the ERwin modeling tool allow longer names to accommodate COTS data and metadata that may be documented using these tools.
  • Business name terms are separated by a space.
  • When the business name is longer than 32 characters then the order of actions to reduce the number of characters in the name is:
    • Eliminate name terms that do not contribute meaning to the name.
    • Translate name terms to their respective abbreviations working from right to left until the name is not longer than 32 characters.
    • Look for another name that can substitute for the requested name.
  1. FDOT does not support key unification. Role name attribute names that enter an entity (is a foreign key) from multiple relationships to prevent key unification. The role name is based on the parent entity contributing the attribute to the child entity and is generally a name prefix.

Name Construction

A common and recommended method for generating a business name is to determine a name using the IBM “OF” language syntax and then reverse the order of the name terms and eliminate the connector terms.

Examples:

  • “The name of the manager of the project.”
    • Eliminate the connectors to produce Name Manager Project.
    • Reverse the term order to produce Project Manager Name.
    • Project is the prime term, Manager is a qualifier for Name, Name is the class term.
  • “The code that is the status of the contract.
    • Eliminate the connectors to produce Code Status Contract.
    • Reverse the term order to produce Contract Status Code.
    • Contract is the prime term, Status is a qualifier for Code, Code is the class term.
  • “The date that is the beginning of the contract.”
    • Eliminate the connectors to produce Date Beginning Contract.
    • Reverse the term order to produce Contract Beginning Date.
    • Contract is the prime term, Beginning is a modifier for Date, Date is the class term.

Begin(ning) modifies Contract Date. Since Begin is a verb, evaluate the entity for more kinds of date. A decision to abstract to a code list may be lurking nearby.

** Begin is a verb, pick your dictionary it is still a verb. Begin and End are common terms in names even though they are not nouns or adjectives. A very clear definition is critical to ensure that a thing is being referenced rather than a process. Remember, verbs and adverbs in names infer the possibility of a code list lurking about somewhere.

Elements and Columns

Data Model Columns, Repository Elements and Repository Columns all have the same naming rules.

Naming Rules

  1. Element names are based on abbreviations for the terms that make up the business or attribute name.
  2. The order of terms is the same as for the business or attribute name.
  3. Business words or phrases are translated to element name terms using the Repository glossary. The Erwin naming standards file/model is kept synchronized with the Repository glossary.
    • The Repository Element screen will perform the translation from business name to element name using the Options, Name (O.N) command once a name has been typed into the business name field on the screen.
    • ERwin will perform translation from attribute name (business name) to column name (element name) automatically using the ERwin attribute to column naming macro and the ERwin naming standards file glossary.
  4. Element names are limited to no more than 18 characters. The Repository and the ERwin modeling tool allow longer names to accommodate COTS data and metadata that may be documented using these tools. This limit is imposed in order to correctly generate COBOL copybooks in our z/OS environment.
  5. Terms are separated by an underscore. The underscore between the class term and the term to its left is not optional and cannot be removed.
  6. When the direct translation of the attribute name results in a column name longer than 18 characters then the order of actions to reduce the number of characters in the name is:
    • Remove underscore characters except for the underscore which precedes the class term.
    • Remove characters from an abbreviation term as long as meaning is not sacrificed. Any vowels that are part of the abbreviation are candidates. This is usually not a good idea but evaluate the possibility anyway.
    • Remove abbreviated terms as long as overall meaning is not sacrificed. This is also not usually a good idea but evaluate the possibility anyway.
    • Look for another name that can substitute for the requested name and start again.
  7. Maximum length of an element name of data type VARCHAR or VARCHAR2 is 17 characters for all environments. This limit is imposed in order to correctly generate COBOL copybooks in our z/OS environment.
  8. Term abbreviations in the element name are separated by underscore characters. This is done by replacing space characters in the business name with underscore characters in the element name.
  9. FDOT does not support key unification when the same element name enters an entity (is a foreign key) from multiple relationships. Role name the element name to prevent key unification. The role name should be based on the parent entity contributing the element to the child entity.
  10. Elements created using the current rules shall have a status value of “PRIME” when created in the Repository.
  11. Examples:
    • “Outsider Location Contract Status Code “
      • The translated name Out_Loc_Cntrt_Stat_Cd is 21 characters.
      • Remove the underscores, except the one preceding the class term, and you get OutLocCntrtStat_Cd which is 18 characters.
    • “Vendor Location Contract Status Code”
      • The translated name Vend_Loc_Cntrt_Stat_Cd is 22 characters.
      • Remove the underscores and you get the 19 character name VendLocCntrtStat_Cd.
      • Remove the vowel from Vend and you get the 18 character name VndLocCntrtStat_Cd.

** While FDOT is attempting to phase out Outsider in favor of Vendor they are not synonyms. Outsider is more general and Vendor is more specific so the 2 names could mean, or refer to, different things.

Naming Guidelines

  1. Element names will be reused where reasonable and appropriate. An Element name represents a business idea, concept, characteristic or property. When an element name is used in multiple places the same element name should be used each time. Conversely, an element name is atomic in the Repository and means the same thing regardless of the entity or table in which it resides.
  2. If a business or element name acquires specialized characteristics because of the entity in which it resides then it may be appropriate to include the entity name, or abbreviation, in the business and element names. If the business name Work Activity Code has one set of values applied consistently throughout the organization except when it is used in the Maintenance business area then an appropriate application of this guideline would call for the creation of a new business name, and element, Maintenance Work Activity Code to represent the set of values used with the Maintenance business area.
  3. Use of numerals, Roman numerals or words.

Several factors are taken into consideration when developing element names that contain numbers:

  • Length – if the generated name is too long when using words then consider replacing words for numerals with the numerals. I.e. Replace “Four” with “4”, “MCCCIVIX” with “1349”.
  • Consistency and Sensibility – be consistent when creating a series of elements with numbers in them. Use all numerals rather than the first 10 as words and the remainder as numerals.
  • Size – always use numerals for numbers greater than 10.
  • Ease of Reporting – if you are creating a series of elements with numbers that cross a precision boundary then use the number of digits needed to represent the larger precision boundary. If there are 11 elements then use “01”, “02”, “03” … “11” instead of “1”, “2”, … “9”, “10”, “11”. In the second example “1” and “11” will sort together, before “2”, when you probably want “11” to sort after “2”.

Glossary

Creating Glossary Abbreviations

Rules

  1. All business terms used in the Repository, an ERwin model or a Gen model, and their abbreviations, will be stored in the Repository Glossary.
  2. The established abbreviations for terms will be used. I.e. The established abbreviation for the term “Administration” is “ADM”. “ADMIN” is not an acceptable abbreviation for this term and will not be used for this term.
  3. All terms will use the abbreviation established for the root form of the term. I.e. Accept, Accepts, Accepted, Accepting and Acceptance all use the abbreviation for Accept (ACPT).
  4. The root form of a term will always be the singular form of the term. Accept is the singular form of Accepts.
  5. All terms that are not word forms will have their own unique abbreviations.
  6. Commonly used phrases, such as “Year-to-Date”, abbreviated “YTD” will be stored in the Glossary twice.
    • The abbreviated term (phrase) will be entered in the Glossary Item Name and the Primary Abbreviation.
    • The full text of the phrase will be entered in the Glossary Item Name and the abbreviated phrase will be entered in the Primary Abbreviation.
  7. Commonly used acronyms and initialisms will be entered in the Glossary twice.
    • The acronym or initialism will be entered in the Glossary Item Name and the Primary Abbreviation.
    • The full text of the acronym or initialism will be entered in the Glossary Item Name and the acronym or initialism will be entered in the Primary Abbreviation.

Guidelines

  1. Use commonly recognized abbreviations or use an abbreviation that conveys an intuitive meaning and attempt to be as brief as possible.
  2. Do not abbreviate in a vacuum. For example, consider CITY, COUNTY and COUNTRY. An abbreviation for each of these could be CTY. However, consider more commonly recognized or more intuitive abbreviations. One possible scenario of abbreviations for these three terms might by CTY, CNTY and CNTRY.
  3. If a term with 4 or fewer characters has no generally accepted abbreviation, it is acceptable to not abbreviate the word in the Glossary. Add the term as both the Glossary Item Name and the Primary Abbreviation.

Creating Glossary Abbreviations

  1. Enter the term into the glossary worksheet to request a new term and abbreviation be established in the glossary. Urgency of the need for the new term should be noted in the worksheet entry.
  2. If another term in the glossary has the same root as the term needing an abbreviation then identify the root term in the worksheet and propose the abbreviation for the root term be used for the new term.
  3. If there is a “standard” abbreviation for the term then propose the standard abbreviation and notate that the abbreviation is considered to be a standard for the term.
  4. The abbreviation should be meaningful.
  5. Notify the Data Administration (DA) team that a new abbreviation is needed. The current notification method is e-mail.
  6. The proposed abbreviation is voted upon by the DA team, with alternative abbreviations proposed by the team.
  7. Majority vote rules.
  8. The approved term and abbreviation are entered into the Repository Glossary by the requestor of the abbreviation.
  9. If the new term will appear on any one of several acronym lists on the FDOT Infonet website then two (2) entries are required in the Repository.
    • The full term in the Glossary Name field, the abbreviation in the Primary Abbreviation field and the full term, with optional additional text, in the Description Leave the Department field blank. Do not put “ACRNM” in the Department field.
    • The abbreviation in the Glossary Name and Primary Abbreviation fields, the full term only in the Description Enter “ACRNM” in the Department field.

**Entering “ACRNM” in the Department field for the full term entry and adding commentary text in the Description field causes problems with the lists found on the Infonet website.

  1. A request is sent to the ERwin Model Manager administrators to include the new term in the ERwin Model Manager glossary and to generate the export files from the glossary.
  2. The ERwin Model Manager administrator that performs the synchronization will notify the DA team when the synchronization is complete, the glossary files have been generated and the updated files have been copied to the DA SharePoint site.

Change History

Effective Date:  December 1, 2011  
Create Date:  November 21, 2011 Created By:  Sarah Close

 

Last Update Date

 Last Updated By

Reason for Change
November 21, 2011 Sarah Close Convert procedure to new format
December 8, 2011 Sarah Close Updates based on received comments.
February 8, 2012 Sarah Close Updates based on received comments.
February 15, 2012 Sarah Close Minor typographical corrections and re-ordering.
February 28, 2012 Sarah Close Updates based on received comments.

 

Glossary of Florida Department of Transportation (FDOT) for Element Naming Conventions – Download [Optimized PDF]

Glossary of Florida Department of Transportation (FDOT) for Element Naming Conventions – Download

Related posts:

  1. Grant Glossary of Terms – State Department of Education
  2. XBRL Glossary of Terms
  3. Glossary of Utah Department of Health Terms
  4. Abstract

Leave a comment

Your email address will not be published. Required fields are marked *