Skip to main content

Naming standards

A common structure on naming different CDF resource types and configuration are important from day 1. Easy to use and understandable naming standard makes it easy to navigate and search on all components in a project as is grows in data sources, code, configuration, supported solutions and human resources working with and using the CDF solutions.

Separation tokens

Separation tokens are used to create "namespacing" in the naming standard. The separation tokens are used to separate different parts of the name, and thus simplify the readability of the name. The separation tokens are:

  • For external IDs the separation token is ’_’ (underscore) - this token works for all OS, when external ID matches usage of files
  • For names the separation token is ’:’ or '_' (colon or underscore) - these tokens matches usage in other CLI tools and gives good readability

Names are often displayed in a report or in a user interface and should be easy to read. External IDs are often used in code and configuration files, so they need to be easily processed by code.

Example usage of naming standard

In the example below we are setting up a project based on the Open Industry Data (OID), that originates from the Valhall oil rig. Hence the example location below is oid.

  • the location_name = oid
  • The different source systems that we get data from are:
    • workmate (asset & workorder data)
    • fileshare (files and 3D)
    • PI (time series / data points)
CDF project

├── Data Sets:
│   ├── extId: ds_asset_oid ── name: asset:oid
│   │ ├── Extraction Pipelines:
│   │ │ └── extId: ep_src_asset_oid_workmate ── name: src:asset:oid:workmate
│ │ │
│   │ ├── RAW DB/tables:
│   │ │ └── DB: asset_oid_workmate ── table: assets
│ │ │
│   │ ├── Transformations:
│   │ │ └── extId: tr_asset_oid_workmate_asset_hierarchy ── name: asset:oid:workmate:asset_hierarchy
│ │ │
│   │ └── Autorisation groups:
│   │ ├── id: asset:oid:extractor
│   │ ├── id: asset:oid:prosessing
│   │ └── id: asset:oid:read
│ │ 
│   ├── extId: ds_files_oid ── name: files:oid
│   │ ├── Extraction Pipelines:
│   │ │ ├── extId: ep_src_files_oid_fileshare ── name: src:files:oid:fileshare
│   │ │ └── extId: ep_ctx_files_oid_fileshare:annotation ── name: ctx:files:oid:fileshare:annotation
│ │ │
│   │ ├── RAW DB/tables:
│   │ │ └── DB: files_oid_fileshare ── table: file_metadata
│ │ │
│   │ ├── Transformations:
│   │ │ └── extId: tr_file_oid_fileshare_file_metadata ── name: file:oid:metadata:fileshare:file_metadata
│ │ │
│   │ ├── Functions:
│   │ │ └── extId: fu_files_oid_fileshare_annotation ── name: files:oid:fileshare:annotation
│ │ │
│   │ └── Autorisation groups:
│   │ ├── id: gp_files_oid_extractor
│   │ ├── id: gp_files_oid_prosessing
│   │ └── id: gp_files_oid_read
│ │ 
│   ├── extId: ds_workorder_oid ── name: workorder:oid
│   │ ├── ...
│ │  ...
│ │
│   ├── extId: ds_timeseries_oid ── name: timeseries:oid
│   │ ├── ...
│ │ ... 
│ │
│   ├── extId: ds_3d_oid ── name: 3d:oid
│   │ ├── ...
│ │ ... 
│ 
└── Spaces:
   └── extId: sp_apm_oid ── name: oid

Naming elements

  • Data Type: asset, timeseries, workorder, files, 3d,... (use what is relevant for project)
  • Source: Source system where data originates from (ex, SAP, Workmate, Aveva, PI, Fileshare, SharePoint,..)
  • Location: Location for Asset / System / Plant / installation
  • Pipeline Type: src = source data, ctx = contextualization, uc = use case, ...
  • Operation Type: Type of operation/action/functionality in transformation or CDF function
  • Access Type: Type of access used in authorization groups (ex: extractor, processing, read, ...)

Data sets

External ID: ds_<data type>_<location>
Name: <data type>:<location>
Ex: ds_asset_oid / asset:oid

Extraction Pipelines

External ID: ep_<pipeline type>_<data type>_<location>_<source>
Name: <pipeline type>:<data type>:<location>:<source>:
Ex: ep_src_asset_oid_workmate / src:asset:oid:workmate

RAW DB/tables

DB: <data type>_<location>_<source>
Ex: asset_oid_workmate
Table: use name from source, or other describing name

Transformations

External ID: tr_<data type>_<location>_<source>_<operation type>
Name: <data type>:<location>:<source>:<operation type>
Ex: tr_asset_oid_workmate_asset_hierarchy / asset:oid:workmate:asset_hierarchy

Functions

External ID: fu_<data type>_<location>_<source>_<operation type>
Name: <data type>:<location>:<source>:<operation type>
Ex: fu_files_oid_fileshare_annotation / files:oid:fileshare:annotation

Authorization groups

Name: gp_<data type>_<location>_<access type>
Ex: gp_asset_oid_extractor / gp_asset_oid_processing / gp_asset_oid_read

Note that groups do not have external IDs. However, to make sure that we programatically can find the groups, we use the same naming convention as for external IDs. It also clearly indicates that these names should not be altered manually as the name is used as a reference.

Data Model Spaces

External ID: sp_<data type>_<source>
Name: <data type>:<source>
Ex: sp_apm_oid / apm:oid