Naming Convention EDH

You might also like

Download as pptx, pdf, or txt
Download as pptx, pdf, or txt
You are on page 1of 51

Naming convention for objects in EDH

Raw, Process, Enrich, others.


Prepared by: Metadata Management Team and Data Governance Team

05.08.21

© 2021 Petroliam Nasional Berhad (PETRONAS)


All rights reserved. No part of this document may be reproduced in any form possible, stored in a retrieval system, transmitted and/or disseminated
in any form or by any means (digital, mechanical, hard copy, recording or otherwise) without the permission of the copyright owner.

Internal
Document History

Version By Description
26-Mar-2020 • Adrian Thong • Created
• Sahrilnizam Ismail
30-Mar-2020 • Adrian Thong • Added explanations
01-Apr-2020 • Adrian Thong • Added guideline for ETL jobs
27-Apr-2020 • Adrian Thong • Revised naming conventions based on object hierarchies
observed in Talend Data Catalog
09-Jun-2020 • Adrian Thong • Added naming convention for API
• Sahrilnizam Ismail
25-Jun-2020 • Oo Woei Luen • Added naming convention for Data Mapping (Talend) and Other
Jobs (Talend)
01-Jul-2020 • Oo Woei Luen • Added naming convention for Data Lake
24-Jul-2020 • Oo Woei Luen • Amendment on Enrich zone where CDM will only be reflected
at Data Warehouse
• [Ref: Email from Zeffry Suzi Nasir (DE-PS/DIGITAL) dated 24
July 2020 3:37 PM]
5 July 2021 • Farah Hanum • Added staging section
5 August 2021 • Nafiz Izzat • Added data model object section and restructured the deck
10 January 2022 • Armizee Shah • Added SharePoint
14 July 2022 • Nurul Asyikin • Revise all Data Modeling object naming conventions (Data
Warehouse, Data Mart, general guideline)

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Content
01. Notes to user

02. Abbreviation

03. Naming convention for Data Structure - Directory Structure / Folder / File

04. Naming convention for Data Lake - Folder

05. Naming convention for Data Warehouse - Database / Schema / Table

06. Naming convention for Data Mart - Database / Schema / Table

07. Naming convention for Talend - Data Mapping

08. Naming convention for Talend - Other Jobs

09. Naming convention for API

10. Naming and definition guideline for Data Model Objects

11. Data Governance on Naming

© 2021 Petroliam Nasional Berhad (PETRONAS) | 3

Internal
Note to user

1) Object naming must be unique.

2) The naming convention in this document is currently based on the Talend ETL and the
capability of the Talend Data Catalog.

3) The objects from AWS and Azure will appear in the Azure Talend Data Catalog in a
centralized Metadata repository, hence the name Directory Structure and the Model
must be able to tell that the object is in Cloud / Container / Zone.

4) Objects in EDH is meant for Enterprise consumption hence naming of the Directory
Structure and Folders in Raw, Process and Enrich should not be too project specific.

5) This document is only meant for objects within EDH environment.

6) Do contact ED Architecture team with the project data domains to validate the
CommonDataModel grouping prior to resource request for EDH DEV.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Content
01. Notes to user

02. Abbreviation

03. Naming convention for Data Structure - Directory Structure / Folder / File

04. Naming convention for Data Lake - Folder

05. Naming convention for Data Warehouse - Database / Schema / Table

06. Naming convention for Data Mart - Database / Schema / Table

07. Naming convention for Talend - Data Mapping

08. Naming convention for Talend - Other Jobs

09. Naming convention for API

10. Naming and definition guideline for Data Model Objects

11. Data Governance on Naming

© 2021 Petroliam Nasional Berhad (PETRONAS) | 5

Internal
Abbreviation
Short name of the object should be in Capital Letter.

Objects Short name Long name


Cloud AW Amazon Web Services

Cloud AZ Azure

Zone DMT Data Mart

Zone DW Data Warehouse

Zone ER Enrich

Zone PR Process

Zone PROD Production

Zone RW Raw

Zone STG Staging

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Abbreviation
Short name of the object should be in Capital Letter.

Objects Short name Long name


ProcessName BG Business Glossary

ProcessName DC Data Cleansing

ProcessName DM Data Mapping

ProcessName DQ Data Quality

ProcessName DT Data Transformation

ProcessName M Data Model

ProcessName QM Query Mapping

ProcessName SM Semantic Mapping

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Abbreviation
Short name of data model object should be in Capital Letter.

Objects Short name Long name


ModelStandard CFIHOS Capital Facilities Information Handover Specification

ModelStandard EDM Enterprise Data Model

ModelStandard OSDU Open Subsurface Data Universe

ModelStandard PPDM Professional Petroleum Data Management

DataDomain AE Asset Management

DataDomain FIN Finance

DataDomain HR Human Resource

DataDomain HSSE Health, Safety, Security and Environment

DataDomain OE Operation Excellence

DataDomain ESD External Subscription Data

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Content
01. Notes to user

02. Abbreviation

03. Naming convention for Data Structure - Directory Structure / Folder / File

04. Naming convention for Data Lake - Folder

05. Naming convention for Data Warehouse - Database / Schema / Table

06. Naming convention for Data Mart - Database / Schema / Table

07. Naming convention for Talend - Data Mapping

08. Naming convention for Talend - Other Jobs

09. Naming convention for API

10. Naming and definition guideline for Data Model Objects

11. Data Governance on Naming

© 2021 Petroliam Nasional Berhad (PETRONAS) | 9

Internal
Data Structure
Naming convention for Staging, Raw, Process and Enrich zone’s directory structure

Zone Azure example AWS example


Staging AZ_ADLS_STG_GBPP AW_S3_STG_DataAdjacency
Raw AZ_ADLS_RW_SAPECC AW_S3_RW_ePTW
Process AZ_ADLS_PR_SAPECC AW_S3_PR_ePTW
Enrich AZ_ADLS_ER_SAPECC AW_S3_ER_ePTW

Logical folder in Talend Data Catalog (TDC):


Reference * Required
• Staging *<Cloud> AZ, AW
<Cloud>_<Container>_<Zone>_<ProjectName> *<Container> ADLS, S3
*<Zone> RW, PR, ER
• Raw, Process and Enrich Zone:
<Cloud>_<Container>_<Zone>_<DataSourceType> *<DataSourceType> SAPS4, SAPECC, ORACLE,
MSSQL, MYSQL, POSTGRES, API
(Short business description of the
data source)

Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Data Structure
Naming convention for Staging zone’s directory structure / folder

Zone Azure example AWS example


<Cloud>_<Container>_<Zone>_<ProjectName>
Staging
AZ_ADLS_STG_VesselAnalytics AW_S3_STG_DataAdjacency

• Only for staging container, Access to ADLS container will require Security Group or Service
Principal. Request for security group no. should be made via ICT2U, ORF only captures the name
provided by ICT2U.

• For Staging at EDH AWS, project only requires to key-in directory section, as S3 credential are to
be provided by EDH CORE DevOps.

• Folder in Staging Zone is only a temporary file for system that require to push/dump data into
EDH. Directory will be deleted once the data is moved into raw zone.

Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Data Structure
Naming convention for Raw, Process and Enrich zone’s directory structure / folder

Zone Azure example AWS example


Raw | <DataSourceType_DataSourceName>
Process |
SAPECC_P35 ePTW
Enrich
ORACLE_PGPS

• *<DataSourceType_DataSourceName> = Short business description of the data source type


followed by data source name/system name. Example: SAPS4, SAPECC_P35, ORACLE_PGPS,
MSSQL_IM, MYSQL, POSTGRES, API_DART

* Required
Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Data Structure
Naming convention for Raw, Process and Enrich zone’s
directory structure / folder / sub-folder
Zone Azure example AWS example
Raw | <Version>
Process |
V01 V01
Enrich

• <Version> = Version number is a running number within EDH.

* Required
Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Data Structure
Naming convention for Raw, Process and Enrich zone’s
directory structure / folder / sub-folder
Zone Azure example AWS example
Raw |
Process | VBAK
Enrich

• Subfolder for raw and process to follow source name.

• Subfolder for enrich to follow data lake / data warehouse table name.

Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Data Structure
Naming convention for Raw, Process and Enrich zone’s
directory structure / folder / sub-folder (year)
Zone Azure example AWS example
Raw |
Process | 2020 2020
Enrich

• Highly recommended to have time series subfolders. Creation of these subfolders can be done
automatically by the ingestion or ETL process.

Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Data Structure
Naming convention for Raw, Process and Enrich zone’s
directory structure / folder / sub-folder (month)
Zone Azure example AWS example
Raw |
Process | 01 01
Enrich

• Highly recommended to have time series subfolders. Creation of these subfolders can be done
automatically by the ingestion or ETL process.

Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Data Structure
Naming convention for Raw, Process and Enrich zone’s
directory structure / folder / sub-folder (day)
Zone Azure example AWS example
Raw |
Process | 31 30
Enrich

• Highly recommended to have time series subfolders. Creation of these subfolders can be done
automatically by the ingestion or ETL process.

• How low the time series subfolders go depends on the velocity of the data, for example, if data is
ingested 2 or more times a day, then subfolders can go to day level. If data is ingested one a week,
then MM is sufficient.

Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Data Structure
Naming convention for Raw, Process and Enrich zone’s
directory structure / folder / sub-folder (example)
Zone Azure example AWS example
Raw | SAPECC_P35 ePTW
Process | ->V01 ->V01
Enrich -->VBAK -->2020
--->2020 --->04
---->01 ---->30
----->31

• The above is an example of a Folder with sub-Folders in the EDH zones.

• Directory structure only exists in the Talend Data Catalog and is not a folder in the EDH zone.

Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Data Structure
Naming convention for Raw, Process and Enrich zone’s
directory structure / folder / file
Zone Azure example AWS example
<UnixTimeStamp>_<Object>.format
Raw 1587102843_ZFIGLD014.json 1587102843_ZFIGLD014.json
Process 1587102843_ZFIGLD014.json 1587102843_ZFIGLD014.json
Enrich 1587102843_ZFIGLD014.json 1587102843_ZFIGLD014.json

• *<UnixTimeStamp> = Unix time stamp in Malaysia’s local time. Only required when the timestamp is
required. Example: Transactional data

• *<Object> = Data object. If it is database table, it should follow the table name.

• Format .psv is preferred for structured file enrich zone.

* Required
Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Content
01. Notes to user

02. Abbreviation

03. Naming convention for Data Structure - Directory Structure / Folder / File

04. Naming convention for Data Lake - Folder

05. Naming convention for Data Warehouse - Database / Schema / Table

06. Naming convention for Data Mart - Database / Schema / Table

07. Naming convention for Talend - Data Mapping

08. Naming convention for Talend - Other Jobs

09. Naming convention for API

10. Naming and definition guideline for Data Model Objects

11. Data Governance on Naming

© 2021 Petroliam Nasional Berhad (PETRONAS) | 20

Internal
Data Lake
Naming convention for Staging, Raw, Process and Enrich zone’s folder

Zone Azure example


Staging AZ_ADLS_STG_GBPP
Raw AZ_ADLS_RW_SAPECC
Process AZ_ADLS_PR_SAPECC
Enrich AZ_ADLS_ER_SAPECC

Physical folder in Data Lake:


Reference * Required
• Staging *<Cloud> AZ, AW
<Cloud>_<Container>_<Zone>_<ProjectName> *<Container> ADLS, S3
*<Zone> RW, PR, ER
• Raw, Process and Enrich Zone:
<Cloud>_<Container>_<Zone>_<DataSourceType> *<DataSourceType> SAPS4, SAPECC, ORACLE,
MSSQL, MYSQL, POSTGRES, API
(Short business description of the
data source)

Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Data Lake
Naming convention for Raw, Process and Enrich zone’s sub-folder

Zone Example
<DataSourceName>
Raw PGPS
Process PGPS
Enrich PGPS

• *<DataSourceName> = System name. Example: PGPS, PI, DART

• Not applicable for staging.

Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Data Lake
Naming convention for Raw and Process zone’s sub-folder (example)

Zone Azure example


Enrich AZ_ADLS_RW_Oracle
->PGPS
-->V01
--->ProdWellTest
---->2020
----->01
------>31

• Refer to “Data Structure - Naming convention for Directory Structure / Folder / File”.

Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Data Lake
Naming convention for Enrich zone’s sub-folder (example)

Zone Azure example


Raw | Process AZ_ADLS_RW_Oracle
->PGPS
-->V01
--->ProdWellTest
---->2020
----->01
------>31

• Refer to “Data Structure - Naming convention for Directory Structure / Folder / File”.

Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Content
01. Notes to user

02. Abbreviation

03. Naming convention for Data Structure - Directory Structure / Folder / File

04. Naming convention for Data Lake - Folder

05. Naming convention for Enterpise Data Warehouse & Business Tenant -
Database / Schema / Table/ Attribute/ Keys
06.
Naming convention for Enterprise Data Mart & Business Tenant Mart -
07. Database / Schema / Table/ Attribute/ Keys

08. Naming convention for Talend - Data Mapping

09. Naming convention for Talend - Other Jobs

10. Naming convention for API

11. Naming and definition guideline for Data Model Objects

Data Governance on Naming © 2021 Petroliam Nasional Berhad (PETRONAS) | 25

Internal
Enterprise Data Warehouse
Naming convention for the Enterprise Data Model schema name, table name, attribute
name, key
Schema Table Name AttributeName Key
<ModelStandard> <Tablename> <AttributeName> <TableName>+Id
For Synapse
(or databases that
can accept multi- EDM CustomerSales CustomerName CustomerId
case object names
in Pascal Case)
For Redshift EDM VENDOR_TYPE CUSTOMER_NAME CUSTOMER_ID
(or databases that Or edm or vendor_type or customer_name Or customer_id
cannot accept multi-
case object names,
prefer upper case Prefer upper case Prefer upper case Prefer upper case Prefer upper case

* Required
For <ModelStandard>, there are four standard name: CFIHOS, EDM, OSDU, PPDM
For naming <Tablename>, <AttributeName> refer to the respective objects in the data model standard

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Enterprise Data Warehouse
Naming convention for custom object within Enterprise Data Model table name,
attribute name
Schema Table Name AttributeName
<ModelStandard> <Tablename> <AttributeName>
For custom at Table
EDM P_CustomerCertificate CertificateName
level
For custom at Attribute
level but at Table is not EDM CustomerSales P_Gender
a custom table

* Required
For <ModelStandard>, there are four standard name: CFIHOS, EDM, OSDU, PPDM

For naming custom objects, refer Data Model Naming and Definition Guideline

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Enterprise Data Warehouse & Business Tenant
Naming convention for the Non Enterprise Data Model (Custom) schema name, table
name, attribute name, key

Schema Table Name AttributeName Key


<DataDomain> <Tablename> <AttributeName> <TableName>+Id
For Synapse
(or databases that Respective Data
can accept multi- Domain e.g. CustomerAccount CustomerName CustomerId
case object names GroupDigital
in Pascal Case)

For Redshift GROUP_DIGITAL CUSTOMER_ACOUNT CUSTOMER_NAME CUSTOMER_ID


(or databases that Or group_digital or customer_account or customer_name Or customer_id
cannot accept multi-
case object names,
prefer upper case Prefer upper case Prefer upper case Prefer upper case Prefer upper case

* Required
For name of Schema <DataDomain> in Enterprise Data Warehouse, refer to Data Model and Design, ED.

For naming custom objects, refer Data Model Naming and Definition Guideline

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Content
01. Notes to user

02. Abbreviation

03. Naming convention for Data Structure - Directory Structure / Folder / File

04. Naming convention for Data Lake - Folder

05. Naming convention for Data Warehouse - Database / Schema / Table

06. Naming convention for Data Mart - Database / Schema / Table

07. Naming convention for Talend - Data Mapping

08. Naming convention for Talend - Other Jobs

09. Naming convention for API

10. Naming and definition guideline for Data Model Objects

11. Data Governance on Naming

© 2021 Petroliam Nasional Berhad (PETRONAS) | 29

Internal
Talend
Naming convention for data mapping in Talend

Zone Azure example AWS example


Raw AZ_DM_SAPECC_RW_ER AW_DM_ePTW_RW_ER
Process AZ_DM_SAPECC_PR_ER AW_DM_ePTW_PR_ER
Enrich AZ_DM_SAPECC_ER_DW AW_DM_ePTW_ER_DW

• Raw, Process and Enrich Zone:


<Cloud>_<ProcessName>_<DataSourceType>_<Source>_<Destination>

Reference * Required
*<Cloud> AZ, AW
*<ProcessName> ADLS, S3
*<DataSourceType> SAPS4, SAPECC, ORACLE, MSSQL, MYSQL, POSTGRES, API
(Short business description of the data source)
*<Source> RW, PR, ER, DMT, DW
*<Destination> RW, PR, ER, DMT, DW

• Data source replace with application name.

Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Content
01. Notes to user

02. Abbreviation

03. Naming convention for Data Structure - Directory Structure / Folder / File

04. Naming convention for Data Lake - Folder

05. Naming convention for Enterpise Data Warehouse & Business Tenant -
Database / Schema / Table/ Attribute/ Keys
06.
Naming convention for Enterprise Data Mart & Business Tenant Mart -
07. Database / Schema / Table/ Attribute/ Keys

08. Naming convention for Talend - Data Mapping

09. Naming convention for Talend - Other Jobs

10. Naming convention for API

11. Naming and definition guideline for Data Model Objects

Data Governance on Naming © 2021 Petroliam Nasional Berhad (PETRONAS) | 31

Internal
Enterprise Data Mart & Business Tenant Data Mart
Naming convention for the view schema name, table name, attribute name

Schema Table Name AttributeName Key


<DataDomain> <Tablename> <AttributeName> NA
For Synapse
(or databases that
can accept multi- DMT_Finance Vw_GeneralLedger LedgerNo NA
case object names
in Pascal Case)

For Redshift DMT_FINANCE VW_GENERAL_LEDGER LEDGER_NO


(or databases that Or dmt_finance or vw_general_ledger or ledger_no
cannot accept multi- NA
case object names,
prefer upper case Prefer upper case Prefer upper case Prefer upper case

* Required
Data Governance - Refer Data Model Naming and Definition Guideline in naming data model objects
For name of Schema <DataDomain> in Enterprise Data Mart, refer to Data Model and Design, ED
© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Enterprise Data Mart & Business Tenant Data Mart
Naming convention for analytical data mart (star schema name, fact/ dim table name,
attribute name)

Schema Table Name AttributeName Key


<TableName
<DataDomain> <Tablename> <AttributeName> without
Fact/Dim>+Id
For Synapse
(or databases that FactSalesOrder
can accept multi- DMT_Analytics SalesDate SalesOrderId
DimCustomer
case object names
in Pascal Case)

DMT_ANALYTICS FACT_SALES_ORDER SALES_DATE SALES_ORDER_ID


Or dmt_analytics DIM_CUSTOMER or sales_date Or sales_order_id
For Redshift or
(or databases that fact_sales_order
cannot accept multi- dim_customer
case object names,
prefer upper case
Prefer upper case Prefer upper case Prefer upper case Prefer upper case

* Required
For name of Schema <DataDomain> in Enterprise Data Warehouse, refer to Data Model and Design, ED.
For naming data model objects, refer Data Model Naming and Definition Guideline

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Content
01. Notes to user

02. Abbreviation

03. Naming convention for Data Structure - Directory Structure / Folder / File

04. Naming convention for Data Lake - Folder

05. Naming convention for Data Warehouse - Database / Schema / Table

06. Naming convention for Data Mart - Database / Schema / Table

07. Naming convention for Talend - Data Mapping

08. Naming convention for Talend - Other Jobs

09. Naming convention for API

10. Naming and definition guideline for Data Model Objects

11. Data Governance on Naming

© 2021 Petroliam Nasional Berhad (PETRONAS) | 34

Internal
Talend
Naming convention for other jobs in Talend

Zone Azure example AWS example


Raw AZ_M_RW_SAPECC AW_M_RW_ePTW
Process AZ_M_PR_SAPECC AW_M_PR_ePTW
Enrich AZ_M_ER_SAPECC AW_M_ER_ePTW

• Raw, Process and Enrich Zone:


<Cloud>_<ProcessName>_<Zone>_<DataSourceType>

Reference * Required
*<Cloud> AZ, AW
*<ProcessName> BG, M, QM, SM
*<Zone> RW, PR, ER, DMT, DW
*<DataSourceType> SAPS4, SAPECC, ORACLE, MSSQL, MYSQL, POSTGRES, API
(Short business description of the data source)

Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Content
01. Notes to user

02. Abbreviation

03. Naming convention for Data Structure - Directory Structure / Folder / File

04. Naming convention for Data Lake - Folder

05. Naming convention for Data Warehouse - Database / Schema / Table

06. Naming convention for Data Mart - Database / Schema / Table

07. Naming convention for Talend - Data Mapping

08. Naming convention for Talend - Other Jobs

09. Naming convention for API

10. Naming and definition guideline for Data Model Objects

11. Data Governance on Naming

© 2021 Petroliam Nasional Berhad (PETRONAS) | 36

Internal
API
Naming convention for API – Azure App Function

Following guideline applies:

1) Follow the naming convention as owned by the Cloud Operation Center or COC.

2) ONE Azure App function for ONE Database Schemas for example App function.

3) ALL Azure App function will be connected to the ONE Azure Service Account.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
API
Naming convention for API – Azure App Function

Zone Azure example AWS example


<Technology>_<RunningNo>_<Schema>
STG <No API for Staging> <No API for Staging>
DEV Ptsg_5edhjs01_HSSE ??
Ptsg_5edhnet01_HSSE
PRD Ptsg_5edhjs01_HSSE ??
Ptsg_5edhnet01_HSSE

• *<Technology> = js (javascript) or net (.net).

• *<RunningNo> = Double digit running number.

• *<Schema> = Schema name.

• All letters are to be converted into small letter in Azure component

* Required
Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
API
Naming convention for API – Triggers in Azure App function

Zone Azure example AWS example


<CommonDataModel>_<Trigger/KPI>_<RunningNo>
DEV | HSSE_Incident_01 HSSE_Incident_01
PRD HSSE_Safety_01 HSSE_Safety_01

• *<CommonDataModel> = Short business description of the common data model.


Example: FIN, HSSE, OE

• *<Trigger/KPI> = Name of trigger or KPI.

• *<RunningNo> = Double digit running number.

• Data triggers used for data entitlement.

• All letters are to be converted into small letter in Azure component

* Required
Data Governance - Refer to the general rule on Letters, Description of File Names and Elements in File Names as
specified in “Some General Dos and Don’ts on Naming Convention” at the end of this pack.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
API
Naming convention for API – URI in the API gateway layer

1) Refer to the detail API Design at:


https://devops101-dev.oex-apps-env-v2.p.azurewebsites.net/developing/api-design/

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Content
01. Notes to user

02. Abbreviation

03. Naming convention for Data Structure - Directory Structure / Folder / File

04. Naming convention for Data Lake - Folder

05. Naming convention for Data Warehouse - Database / Schema / Table

06. Naming convention for Data Mart - Database / Schema / Table

07. Naming convention for Talend - Data Mapping

08. Naming convention for Talend - Other Jobs

09. Naming convention for API

10. Naming and definition guideline for Data Model Objects

11. Data Governance on Naming

© 2021 Petroliam Nasional Berhad (PETRONAS) | 41

Internal
Data Model Objects
Naming and definition guideline

Data model objects must be named described at a sufficient level of detail to ensure that they are discrete
and clearly understood.

The naming guidelines are as follows:


1) Be representative of the object that it represents
2) Be clear, avoiding use of vague terms
3) Be concise, using fewer number of words possible, avoiding articles and needless prepositions
4) Be unique, avoiding wording similar to other names
5) Contain only letters of alphabet
6) Use complete names wherever possible instead of abbreviations or acronyms
7) Use registered abbreviations or acronyms when tools restricts the length of the name

Names are accompanied by definition, which describes in more detail the object the name refers to.

The definition guideline is as follow:


8) Be representative of the object it represents
9) Be precise, concise and unambiguous. The definition should be clear enough to allow only one
possible interpretation
10) A definition shall not use abbreviations unless the abbreviations are commonly understood

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
General Do’s and Don’ts on Data Mode Objects Naming
Convention
No. Topic General Rule Correct Incorrect Explanation
1. Keys All keys are Examples: Examples: 1. All keys regardless of type
standardized to (surrogate, primary or
<Tablename>+Id 1) CustomerId 1) CustomerSK foreign keys) will follow
2) Id <Tablename>+Id standard

2. Name of table is not


included in the key attribute
name

2. Description of Name should Example: Example: 1. The object name is


Objects meaningful and ambiguous and will cause
descriptive 1) IssuanceDate 1) Date confusion on the actual
content of the object

3 Abbreviation Avoid abbreviation Example: 1. The object name is not


(unless it is an understandable
industry standard 1) FieldName 1) FldName
term or due to 2) PSCName 2. PSC is Malaysia’s Oil &
technical Gas standard industry term
constraint of that is understandable to
database)* many. It is the abbreviation
for Production Sharing
Contract

* Currently Data Modeling & Design, ED do not produce a list of standard abbreviation except for <DataDomain>.
© 2021 Modern
Petroliam Nasional Berhad databases
(PETRONAS) have
|
large max length for data object names. If a database has technical limitation on length, refer to Data Modeling & Design team.
Internal
General Do’s and Don’ts on Data Mode Objects Naming
Convention
No. Topic General Rule Correct Incorrect Explanation
4 Letters case For database that Examples: Examples: 1. Only pascal case is
accepts multicase, accepted where words
the default is to use 1) CustomerName 1) customer_name begin with a large case.
Pascal case, with 2) customerName 2. Use of delimiter (e.g: -,_) is
no hypens or other 3) CUSTOMER_NAME not acceptable in between
delimiters 4) Customer-Name two words

For database that Example: Example 1. Only _ is acceptable in


accepts only one between two words
case, use 1) CUSTOMER_NAME 1) CUSTOMER-NAME
underscore as the 2) customer_name 2) CUSTOMER.NAME
differentiator
between two words

Upper case is
preferable

* Currently Data Modeling & Design, ED do not produce a list of standard abbreviation except for <DataDomain>.
© 2021 Modern
Petroliam Nasional Berhad databases
(PETRONAS) have
|
large max length for data object names. If a database has technical limitation on length, refer to Data Modeling & Design team.
Internal
Content
01. Notes to user

02. Abbreviation

03. Naming convention for Data Structure - Directory Structure / Folder / File

04. Naming convention for Data Lake - Folder

05. Naming convention for Data Warehouse - Database / Schema / Table

06. Naming convention for Data Mart - Database / Schema / Table

07. Naming convention for Talend - Data Mapping

08. Naming convention for Talend - Other Jobs

09. Naming convention for API

10. Naming and definition guideline for Data Model Objects

11. Data Governance on Naming

© 2021 Petroliam Nasional Berhad (PETRONAS) | 45

Internal
Some General Do’s and Don’ts on Naming Convention
No. Topic General Rule Correct Incorrect Explanation
1. Letters It is best to use Examples: Examples: 1. The file name will be
capital letters identifiable by using
except in the 1) AZ_ADLS_RW_SAPECC 1) az_adls_rw_sapecc capital letters to
situation where 2) AZ_ADLS_PR_SAPECC 2) az_adls_pr_sapecc differentiate between
the format for 3) AZ_ADLS_ER_FIN 3) az_adls_er_fin the words.
letters of a file
name MUST not
all be in capital
letters.

2. Description of File names Example: Example: 1. Long file names will


File Names should be short, have long paths and
but it must be AZ_ADLS_ER_FIN The_AZ_of_ADLS_ER_Fi URLS. In which case,
meaningful and nance there will be possibility
descriptive of error.

2. Long file names are


also difficult to
remember and
recognised.

3. Words which adds


length to a file name
but is not meaningful
should be removed.

4. The file name should


also describe exactly
what they contain.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Some General Do’s and Don’ts on Naming Convention
No. Topic General Rule Correct Incorrect Explanation
3. Dates If a date is be Examples: Examples: 1. By using the format,
used in the file the sequence of the
name, use the 1) 2020 1. 1April2020 records will be
following format: 2) 202004 2. Apr1st2020 maintained.
a) YYYY; or 3) 20200401
b) YYYMM; or 2. It also helps if need to
c) YYYYMMD retrieve the latest
D dated record.

4. Elements of If elements are Examples Examples: 1. If the records are


File Names to be used in the retrieved according to
file name, it 1) HSSE_Incident_01 1) Incident_01_HSSE their date, the date
should be 2) HSSE_Safety_01 2) 02_HSSE_Safety element should appear
ordered first.
according to the
way in which the 2. If the records are
record will be retrieved according to
retrieved their description, the
description element
should appear first.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Some General Do’s and Don’ts on Naming Convention
No. Topic General Rule Correct Incorrect Explanation
5. Numbering When there is a Examples: Examples: To include the zero for
need to include numbers 0-9. This is to
a number in a FIN_01 FIN1 maintain the numeric order.
file name, use FIN_02 FIN2 This will assist to retrieve
two-digit number FIN_03 FIN3 the latest record number.
instead of one FIN_04 FIN4 i.e. 01, 02 … 99 except if it
digit number. FIN_05 FIN5 is a year or another
FIN_06 FIN6 number with more than two
FIN_07 FIN7 digits.
FIN_08 FIN8
FIN_09 FIN9

6. Versions If there is need Examples: Examples: To distinguish between


to include a various drafts and the final
version number, 1.GET_HSSE_Incident_1_ version .
it must appear in 1.GET_HSSE_V01Draft_Incide April_2020
the file name so nt 2.GET_HSSE_2_April_20
that the most 2.GET_HSSE_V01Final_Incide 20
recent version nt
can be easily
identified and
retrieved.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Some General Do’s and Don’ts on Naming Convention
No. Topic General Rule Correct Incorrect Explanation
7. Timestamp When there is a Examples: Examples: Unix time is a system for
need to use describing a point in time.
Unix timestamp, 1) 1587102843_P35.json 1) P35_1587102843.json By using,
to start with the 2) 1587102843_FIN.json 2) FIN_1587102843.json <UnixTimeStamp>_<Objec
Unix timestamp, t>.format, it is certainly
followed by the easier to be read by a
data object and layperson
then the format.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
Some General Do’s and Don’ts on Naming Convention
1) Except where the file names require to include characters such as * : \ / < > | " ? [ ] ; =
+ & £ $ , try to AVOID saving files containing the said characters as these characters
will make it difficult to search the file name.

2) DON'T use codes, abbreviations and initials which are not usually understood.

3) Except if it easier to retrieve the record, AVOID using common words such as ‘draft’ or
‘letter’ at the beginning of file names.

4) DON’T use repetition and redundant words in file names.

5) AVOID using team names as the basis for folder names as company structure may
change.

6) AVOID names with similar meanings or unclear names such as document.pdf. Use
descriptive information and include dates in files names if possible. It is best if
we know what’s in the file without having to open it.

7) Do not use cryptic codes that only YOU understand (example: prk22–1sple.doc).
Make it meaningful to everyone else.

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal
File type summary

© 2021 Petroliam Nasional Berhad (PETRONAS) |

Internal

You might also like