Naming standards

Establishing a naming standard for CDF resource types and configurations is key to successfully deploy and administer CDF projects with the Cognite Toolkit.

Separation tokens

In the naming standard, use separation tokens for "namespacing":

• For external IDs, use "_" (underscore).

  External IDs are often used in code and configuration files and must be easily processed by code.

• For names, use ":" (colon) or "_" (underscore).

  Names often appear in reports or user interfaces and should be easy to read.

Example naming standard

The example below sets up a project based on the Open Industry Data (OID), and uses oid as the location.

• The location_name = oid

• Source systems:

  • Workmate (asset and workorder data)
  • Fileshare (files and 3D)
  • PI (time series and 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
│   │   │
│   │   └── Authorization 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: fn_files_oid_fileshare_annotation ── name: files:oid:fileshare:annotation
│   │   │
│   │   └── Authorisation 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 the project)
• Source: Source system (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 (extractor, processing, read, ...)

Data sets

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

Extraction pipelines

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

RAW DB tables

DB: <data type>_<location>_<source>
Table: use name from source, or other descriptive name.
Example: asset_oid_workmate

Transformations

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

Functions

External ID: fn_<data type>_<location>_<source>_<operation type>
Name: <data type>:<location>:<source>:<operation type>
Example: fn_files_oid_fileshare_annotation / files:oid:fileshare:annotation

Authorization groups

Groups don't have external IDs. We still recommend using the same naming convention as for external IDs.

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

Authorization security categories

Security categories don't have external IDs. We still recommend using the same naming convention as for external IDs.

Name: sc_<data type>_<location>_<access type>
Example:  sc_asset_oid_extractor / sc_asset_oid_processing / sc_asset_oid_read

Data model spaces

For data model spaces, it's important to distinguish between data spaces and schema spaces. Schema spaces store the schema for the data model, containers, views, node_types, data_models, but not data itself. Data spaces stores data, nodes and edges.

Data model spaces for data

space: sp_<data type>_<source>
Name: <data type>:<source>
Example: sp_apm_oid / apm:oid

Data model spaces for schema

space: sp_<model_type>_<model_identifier>
Name: <model_type>:<model_identifier>
Example: sp_enterprise_model_cognite / enterprise_model:cognite
Example: sp_solution_model_finance_predictonis / solution_model:finance_prediction