Resource naming reference

These guidelines establish naming standards for Cognite Data Fusion (CDF) resources. This reference covers external IDs, separators, capitalization (snake_case, PascalCase, camelCase), type prefixes, and validation patterns. Consistent naming ensures maintainability, scalability, and compatibility with automation tools such as the Cognite Toolkit. The conventions apply to data models, building blocks, and core resource types across the CDF project lifecycle.

These conventions are guidelines only. Adjust them to your organizational needs and standards.

Scope and prerequisites

This document governs naming for all artifacts generated during a CDF project. It applies to resource definitions (schema) and instances (data). Artifacts in scope:

Data modeling: Data models, spaces and instance spaces, views, containers, instances, edges, and properties
Core resources: Time series, streams, records, 3D models and revisions, 3D scenes, locations, and files
Building blocks: CDF projects, extraction pipelines, hosted extractors, data workflows, Raw databases, transformations, functions, data sets, entity matching pipelines, access groups, app registrations, charts, canvases, Streamlit applications, and Atlas AI agents

Artifacts out of scope:

Legacy CDF asset-centric data model types unless mapped to the new framework
Code repository directory structure and Cognite Toolkit module names (governed by separate standards)

You need administrative or write access to the CDF project to create and manage resources. Familiarity with the Cognite Toolkit configuration and templating system is assumed for the implementation section. A git-based workflow is recommended for managing configuration files.

Glossary

Artifact

A generic term for a CDF resource type (for example, a time series) or a CDF building block (for example, a transformation).

Concept

A semantic element used to categorize or group artifacts. Concepts are the atomic units of a name (for example, Source System, Location, Data Domain).

Identifier (external ID)

A unique, machine-readable string used to programmatically address an artifact. Ideally immutable once created.

Name

A human-understandable label for an artifact, intended for display in user interfaces. Balances uniqueness with readability.

Location

A combination of one or more tokens that identifies the physical or organizational scope (Region, Country, Site, Asset, Area, or Unit).

Token

A specific segment of a name or identifier derived from a concept.

Separator

A character (typically underscore or colon) used to delimit tokens within an identifier.

Data domain

A high-level categorization of data based on business function (for example, Maintenance, Operations, Quality).

Naming philosophy

In CDF, naming is the primary interface for navigation, governance, and context. A well-constructed name serves as a semantic address, allowing you to infer content, context, provenance, and intended use without querying metadata. The architecture follows a hierarchical tokenization strategy. Treat a name as a sequence of ordered concepts (tokens), flowing from general to specific.

Type prefix: Technical class of the object (for example, ep for extraction pipeline)
Scope/location: Boundary of the data (for example, valhall)
Source: Origin of the data (for example, sap)
Content/intent: Specific function (for example, maintenance)
Suffix: Sub-component (for example, source)

This structure ensures resources group logically when sorted and supports efficient prefix searching.

Anti-patterns to avoid

Anti-patterns to avoid:

Ambiguity and generic naming: Avoid generic names like my_script, test_pipeline, data_loader, or transformation_1. These provide no context for scope, ownership, function, or lifecycle. In a shared environment, test_pipeline is meaningless and increases the risk of accidental deletion.
Semantic drift and casing chaos: In many systems, PumpID and pumpid are distinct identifiers. Inconsistent capitalization leads to “split-brain” scenarios where data is written to one but read from another, causing silent data loss. Identifiers that differ only by capitalization are prohibited.
Unsafe characters: Do not use spaces, special characters (for example, &, %, /, ), or non-ASCII characters in external IDs. They break downstream tools, require escaping in YAML/JSON, and may be misinterpreted by CLIs. External IDs must be variable-name-safe: alphanumerics and underscore only.
Implicit context: Do not omit location or source because “everyone knows we are on Project X.” Projects scale and merge. A pipeline named sap_assets collides when a second site also running SAP is added. Use explicit context (for example, valhall_sap_assets).
Hardcoded randomness: Random GUIDs/UUIDs guarantee uniqueness but sacrifice debuggability. A human operator cannot determine if job_a1b2 is critical without a lookup table. Semantic naming provides immediate situational awareness during incident response.

General principles

All naming in CDF should adhere to these core principles. Apply them consistently across all resource types and layers. The following table lists each principle and its rationale.

Principle	Rationale
Consistency	Create a register (Excel or YAML enum) for concept values. Share with stakeholders to prevent variation sprawl (for example, NY, NewYork, NYC for the same location).
Uniqueness	Include sufficient concepts to make identifiers globally unique, even when moved across folders or projects.
Readability balance	Use the minimum number of concepts for uniqueness and clarity. Avoid unwieldy identifiers.
Ordered concepts	Maintain the same concept order across artifacts (for example, Type_Location_Source). Predictability allows correct guessing.
Standardized language	Use English, singular forms (Pump, not Pumps), and present tense (Calculate, not Calculated).
Essentialism	Use only essential words. Avoid articles, conjunctions, and prepositions unless required. Use FlowRate instead of TheRateOfFlow.
Semantic parity	Use the same identifier and name for the same concept across objects. If Description is used in one model, do not use Desc or Comment elsewhere.
Casing integrity	Do not create names or identifiers that differ only by capitalization. If `asset_id` exists, `Asset_Id` is prohibited.
Building block prefixing	Prefix building block identifiers with the type (for example, `ep_`, `ds_`) for filtering and sorting.
Instance neutrality	For data instances, do not use a type prefix. A pump instance is P-101, not asset_P-101.

Anatomy of a name or identifier

A name or identifier has these components:

Artifact type abbreviation: (0:1) Optional or mandatory prefix depending on resource type
Artifact type: (0:1) For example, Transformation
Concepts: (1:n) Semantic tokens defining the object
Separators: (1:n) Delimiters between tokens

Separator tokens

Context	Separator	Example	Rationale
External ID (machine-readable)	Underscore (_)	`ep_valhall_sap_maintenance`	URL-safe, filesystem-safe, variable-name-safe in Python, SQL, JavaScript. No escaping in standard configs.
Name (human-readable)	Colon (:), hyphen (-), or underscore (_)	Valhall : SAP : Maintenance Extraction	Improves visual separation in dashboards for easier scanning.

Concepts and token standardization

Typical concepts in CDF names:

Source system: Originating technology (for example, sap, pi, sharepoint)
Enterprise: Top-level company code (for example, cognite, celanese)
Location: Physical or organizational scope
Industry segment: For example, upstream, manufacturing, grid
Industry functions/processes: For example, maintenance, operations, quality
Resource categorization: For example, Asset, Material, WorkOrder
Data model categorization: src (Source), dom (Domain), sol (Solution)
Access role/persona: For example, planner, engineer, admin

Location strategy

Location is often the most critical concept for scalability. It is typically a composite token:

Region/country: eu, us, no
Site: Production facility (manufacturing terminology)
Asset: Production facility (oil and gas terminology)
Area: One area of a facility
Unit/zone/line: Most granular physical scope

If an artifact applies to all locations (for example, a global reference data model), use the token all or similar. This preserves the token structure (for example, ep_all_sap_assets) and allows consistent parsing.

Data modeling resource types

Data modeling uses strict capitalization and suffixing to distinguish layers (Source, Domain, Solution). See Designing scalable data models for the layered architecture (source, enterprise, solution) that these abbreviations map to. Data model type abbreviations:

src: Source data model (mirrors source system schema) – see layered architecture
dm: Data model (generic)
dom: Domain object model (enterprise-wide canonical model)
sol: Solution data model (app-specific consumption model)
inst: Instances – see spaces and instances

Data models

Data model names can have up to 255 characters. They must explicitly state their layer.

Attribute	Convention	Example
External ID	`{General naming}`_src/dom/sol	Process_Industry_Data_Model_DOM
Name	`{General naming}` SRC/DOM/SOL	Process industry data model DOM
Capitalization	PascalCase for ID	General principles for naming

Spaces

Spaces function as namespaces for data models. Space names can have up to 255 characters. Data model spaces:

Attribute	Convention	Example
Identifier	dm_`{src/dom/sol}`_`{general naming}`	dm_dom_maintenance_management
Name	`{General naming}` DM - SRC/DOM/SOL	Maintenance management - DM - DOM
Capitalization	snake_case for ID	General principles for naming

Data model instance spaces (see spaces and instances):

Attribute	Convention	Example
External ID	inst_`{general naming}`	inst_yggdrasil
Name	`{General naming}` - INST	Yggdrasil instance space - INST
Capitalization	snake_case for ID	General principles for naming

Views, containers, and edges

Views, containers, and edges define the schema structure. Use PascalCase, similar to class definitions.

Attribute	Convention	Example
External ID	`{General naming}`	FailureCause
Name	`{General naming}`	Failure cause container
Capitalization	PascalCase for ID	General principles for naming

Properties

Properties represent attributes of a view or container. Use camelCase, similar to variable definitions.

Attribute	Convention	Example
Identifier	`{General naming}`	errorCode
Description	Follow AI-friendly description practices	Error code returned by the sensor
Capitalization	camelCase	Same as identifier

Core resource types

These resources often originate from source systems. The naming strategy prioritizes traceability.

Time series, streams, and records

Resource	External ID pattern	Components
Time series	`{Source System}``{Site}``{Original ID}`	Originating system (pi, sap), site/asset
Streams	`{Source System}``{Site}``{Concept}`	Originating system, site/asset
Records	`{Source System}``{Site}``{Machine}`_`{ID}`	Originating system, site/asset, machine number

Use snake_case for generated prefixes.

3D models and revisions

3D revisions often have system-generated IDs. The model and scenes can be named.

Resource	External ID	Name	Capitalization
3D model	N/A (system)	`{General naming}`	PascalCase for name
3D revision	N/A (system)	N/A (system)	System-generated
3D scene	N/A (system)	`{General naming}`	snake_case for name

Location filters and files

Resource	External ID	Name
Location filter	loc_`{location}`	`{General naming}`
File	N/A (use source ID)	N/A (use source name)

CDF building blocks

Building blocks must use type prefixes for filtering and sorting in the CDF portal and API. For names, do not use a prefix.

Building block prefixes

Building block	Prefix
CDF project	None
CDF organization	None
Extraction configurations	ec
Extraction pipeline	ep
Raw databases	raw (optional)
Transformations	tr
Data workflows	wf
Functions	fn
Data sets	ds
Location filters	loc
Access groups (IDP, identity provider)	gp_cdf
Access groups (Cognite)	gp
App registrations	app
Charts	None
Canvases	None

Detailed building block conventions

CDF project

Name: {enterprise}-{segment}-{region}-{country}-{project level}
Example: am-long-europe-dev

Extraction pipelines

External ID: ep_{data type}{location}{source system}
Example: ep_files_valhall_sharepoint (ID), Valhall Sharepoint File Extraction (name)

Hosted extractors

External ID: he_{data type}{location}{messaging provider}_{source system}
Example: he_timeseries_valhall_kafka_pi_source

Data workflows

External ID: wf_{location}{intent}{source data structure}_{target data structure}
Example: wf_all_sap_assets_to_cdm or wf_valhall_calculate_asset_downtime

Transformations

External ID: tr_{source data structure}_{location}to{target data structure}
Example: tr_sap_oid_to_cdm

Functions

External ID: fn_{source data structure}{location}{intent}_{target data structure}
Example: fn_timeseries_valhall_anomalydetection_alerts

Data sets

External ID: ds_{data type}_{location}
Example: ds_files_valhall

Access groups (IDP, identity provider, and CDF)

IDP external ID: gp_cdf_{location}{persona|resource type|data domain}{action}_{project level}
Example: gp_cdf_valhall_process_engineer_read_dev or gp_valhall_timeseries_read
CDF external ID: gp_{convention} (mirror the IDP name)

App registrations / service principals

External ID: app_{location}{persona}{source system}{data type}{action}_{project level}
Example: app_valhall_extractor_pi_timeseries_write_dev

Visualizations (charts, canvases, Streamlit)

External ID: N/A
Name: Follow general naming and capitalization guidelines

External standards

Align concepts with established international standards where possible:

Standard	Scope	Requirement
CFIHOS (Capital Facilities Information Handover Specification)	Disciplines, document type	Use specific codes from CFIHOS standards
ISO 3166	Country codes	Use standard 2-letter codes (NO, US)
ISO 639-1/2	Language codes	Use standard language codes (en, no)
ISA-95 (Enterprise-Control System Integration)	Manufacturing hierarchy	Use levels (Site, Area, Line, Work Center) for equipment and location tokens

Implementation

Token construction workflow

Identify the artifact

Determine if the object is a building block or a resource. If a building block, look up the mandatory prefix (for example, Extraction Pipeline → ep_). If a resource, determine if the resource requires a prefix (Data Model → Yes, Time Series → No).

Identify the scope (location)

Determine the geographical or organizational scope. Is it specific to Plant A? Use token: planta. Is it global? Use token: all or global.

Identify the source

Where does the data originate? SAP ERP? Use token: sap. Manual input? Use token: manual.

Assemble and separate

Combine tokens using the underscore separator for external IDs. Example: ep + _ + planta + _ + sap = ep_planta_sap.

Toolkit integration

The Cognite Toolkit supports variable substitution for automated naming compliance. Define variables in the configuration file and use Jinja2 templating in resource definitions.

# config.yaml
variables:
  location: valhall
  source: sap
  prefix_ep: ep
  prefix_db: raw

Running the Toolkit generates ep_valhall_sap_assets automatically, preventing manual errors and ensuring the separator standard is applied across environments.

Governance and validation

Naming register (soft gate). Maintain a Naming Standards Register (Excel or YAML enum) listing approved codes for Locations, Sources, Personas, and Industry Segments. Require engineers to consult the register before creating names. Add new concepts through a formal approval process.

CI/CD linting (hard gate). Implement regex validation in the CI/CD pipeline. Scan configuration files for externalId fields and validate against defined patterns. Example: ^ep_[a-z0-9]+_[a-z0-9]+$ ensures ep_ prefix and snake_case. Reject pull requests that fail validation.

Handling exceptions

Exceptions should be rare and documented:

Brownfield constraints: If a legacy system requires a naming format that violates the standard, document the deviation in the Description or Metadata field of the artifact in CDF.
Customer requirements: If a client demands a specific convention (for example, for access groups to align with Active Directory), adhere to the client’s requirement and note the deviation in project documentation.

Validation checklist

Use this checklist before merging a pull request or deploying a resource:

Category	Checklist item	Check
Syntax	Do all external IDs use the underscore (_) separator?	☐
Syntax	Are all external IDs snake_case unless specified otherwise (for example, PascalCase for data models)?	☐
Uniqueness	Do IDs include sufficient location/source tokens to prevent global collisions?	☐
Prefixes	Do all building blocks (pipelines, data sets, groups) have the correct type prefix (ep_, ds_, gp_)?	☐
Data modeling	Are data models named using PascalCase (for example, MyModel)?	☐
Data modeling	Do data model IDs end with the correct suffix (_src, _dom, _sol)?	☐
Properties	Are data model properties named using camelCase (for example, pressureRating)?	☐
Names	Are human-readable names standardized to English, singular, and present tense?	☐
Token order	Is the token order consistent (for example, Type_Location_Source)?	☐
External standards	Are ISO codes used for countries/languages and ISA-95 levels for equipment hierarchies?	☐
Register	Have all new concepts (sites, sources) been added to the central Naming Register?	☐

Quick reference tables

The following tables provide a quick lookup for naming conventions by resource type. In the Name casing column, General means follow the general principles for capitalization (English, singular, present tense) described above. N/A means not applicable (for example, system-generated IDs or when the resource uses the source system’s identifier).

CDF building blocks

Building block	Prefix	External ID casing	Name casing	Example ID
CDF project	None	kebab-case	kebab-case	am-long-europe-dev
Organization	None	kebab-case	kebab-case	cognite
Extraction config	ec	snake_case	General	ec_sap_maint
Extraction pipeline	ep	snake_case	General	ep_valhall_sap
Hosted extractor	he	snake_case	General	he_ts_valhall_pi
Data workflow	wf	snake_case	General	wf_valhall_calc
Raw database	raw	snake_case	General	raw_sap_assets
Transformation	tr	snake_case	General	tr_sap_to_cdm
Function	fn	snake_case	General	fn_anomaly_detect
Data set	ds	snake_case	General	ds_files_valhall
Entity matching	em	snake_case	General	em_sap_pi
Access group (IDP, identity provider)	gp_cdf	snake_case	General	gp_cdf_read_all
Access group (CDF)	gp	snake_case	General	gp_read_all
App registration	app	snake_case	General	app_extractor_pi
Location filter	loc	snake_case	General	loc_valhall
Atlas AI agent	agent	snake_case	General	agent_maintenance

Data modeling

Resource type	External ID casing	Name casing	Suffix rule	Example ID
Data model	PascalCase	General	_src, _dom, _sol	AssetModel_DOM
Space	snake_case	General	No suffix	dm_dom_assets
View	PascalCase	General	No suffix	PumpView
Container	PascalCase	General	No suffix	PumpContainer
Edge	PascalCase	General	No suffix	PumpEdge
Instance	snake_case	N/A	No suffix	pump_101
Property	camelCase	camelCase	No suffix	flowRate

Other resources

Resource type	External ID casing	Name casing	Example ID
Time series	snake_case	General	pi_valhall_2342
Records	snake_case	General	sap_valhall_rec1
3D model	N/A (system)	PascalCase	ValhallModel
3D scene	snake_case	General	scene_deck_a
Location filter	snake_case	General	loc_valhall
File	N/A (use source)	N/A (use source)	N/A

Deploy

Resource naming reference

Scope and prerequisites

Glossary

Naming philosophy

Anti-patterns to avoid

General principles

Anatomy of a name or identifier

Separator tokens

Concepts and token standardization

Location strategy

Data modeling resource types

Data models

Spaces

Views, containers, and edges

Properties

Core resource types

Time series, streams, and records

3D models and revisions

Location filters and files

CDF building blocks

Building block prefixes

Detailed building block conventions

External standards

Implementation

Token construction workflow

Toolkit integration

Governance and validation

Handling exceptions

Validation checklist

Quick reference tables

CDF building blocks

Data modeling

Other resources

Further reading

Deploy

​Scope and prerequisites

​Glossary

​Naming philosophy

​Anti-patterns to avoid

​General principles

​Anatomy of a name or identifier

​Separator tokens

​Concepts and token standardization

​Location strategy

​Data modeling resource types

​Data models

​Spaces

​Views, containers, and edges

​Properties

​Core resource types

​Time series, streams, and records

​3D models and revisions

​Location filters and files

​CDF building blocks

​Building block prefixes

​Detailed building block conventions

​External standards

​Implementation

​Token construction workflow

​Toolkit integration

​Governance and validation

​Handling exceptions

​Validation checklist

​Quick reference tables

​CDF building blocks

​Data modeling

​Other resources

​Further reading

Scope and prerequisites

Glossary

Naming philosophy

Anti-patterns to avoid

General principles

Anatomy of a name or identifier

Separator tokens

Concepts and token standardization

Location strategy

Data modeling resource types

Data models

Spaces

Views, containers, and edges

Properties

Core resource types

Time series, streams, and records

3D models and revisions

Location filters and files

CDF building blocks

Building block prefixes

Detailed building block conventions

External standards

Implementation

Token construction workflow

Toolkit integration

Governance and validation

Handling exceptions

Validation checklist

Quick reference tables

CDF building blocks

Data modeling

Other resources

Further reading