Naming convention for datasets and tables is not documented

[Ludee]

Description of the issue

Naming convention for datasets and tables is not documented.
User inputs on a collaborative platform lead to messy naming and sorting.
There are existing naming recommendations from RDM, but not specific to OE-Data.

Ideas of solution

List and document existing rules and recommendations.
Discuss and decide on rules.
Implement in Dataset Architect, Data Porter and Review Process.

Workflow checklist

• I am aware of the workflow in
  CONTRIBUTING.md

[Ludee]

Naming Conventions for Datasets and Tables on the OEP

Proposal for a shared naming standard to improve collaborative data publications using OEMetadata on the Open Energy Platform (OEP).

Background

When publishing datasets to the OEP community database (OEDB), these distinct name fields must be filled:

Field	Purpose	Constraints
dataset.name	OEP dataset identifier	snake_case, lowercase, max. 63 chars, no special characters, no leading number
dataset.title	Human-readable dataset label	Free text, spaces and special characters allowed
resources[].name	PostgreSQL table identifier	snake_case, lowercase, max. 63 chars, no special characters, no leading number
title	Human-readable table label	Free text, spaces and special characters allowed

All four fields are part of the OEMetadata JSON structure and serve different audiences: machines and humans.
This issue proposes a shared convention for all of them.

Dataset vs. Table

A dataset is the top-level publication unit on the OEP. It groups one or more related tables and carries shared metadata (license, contributors, spatial/temporal coverage, keywords). A table (resource) is a single structured data object within a dataset — one PostgreSQL table in the OEDB.

Dataset  ←──  bkg_vg250                          (one publication)
  ├── Table   bkg_vg250_krs                       (districts)
  ├── Table   bkg_vg250_lan                       (federal states)
  └── Table   bkg_vg250_gem                       (municipalities)

This distinction matters for naming:

• The dataset name identifies the publication as a whole. It should be short and refer to the source product.
• The table name identifies the specific content. It extends the dataset name with topic, spatial level, or type where needed.
• In simple cases (one dataset = one table), both names may be identical.

---

Naming Pattern

Both dataset.name and resources[].name follow the same structural pattern, ordered from broad (origin) to narrow (granularity):

{source}_{project}_{topic}_{spatial}_{temporal}_{type}

The dataset name uses the outer blocks; the table name adds the inner blocks that distinguish individual tables within that dataset.

Building Blocks

Block	Description	Example values	Level
source	Data origin / institute / project abbreviation	bkg, osm, agora, rli, uba	Dataset + Table
project	Project name or product abbreviation	vg250, knde, vernetzen	Dataset + Table
topic	Subject matter or measured quantity	wind, pressure, rahmendaten	Table
spatial	Spatial level or region (ISO 3166 Alpha-3)	deu, eur, krs, nuts3	Table
temporal	Year or temporal resolution	2024, annual, ts	Dataset or Table
type	Geometry type or table type	point, line, area, scalar	Table

Technical Rules (apply to both dataset.name and resources[].name)

• Lowercase only — PostgreSQL folds unquoted identifiers to lowercase. Mixed case requires quoting everywhere and causes hard-to-debug errors.
• Underscores as separators — No hyphens (-), spaces, dots, or special characters.
• Start with a letter — Identifiers must not begin with a digit.
• Max. 63 characters — PostgreSQL silently truncates longer names.
• No reserved SQL keywords — Avoid names like order, table, value, timestamp as standalone identifiers. Always prefix with context.
• No umlauts or non-ASCII characters — Use transliterations: jaehrlich not jährlich.

---

Naming Pattern for title Fields

The title fields (dataset and table) are the full, human-readable labels. They should be descriptive and follow this general structure:

{Source/Institute} {Project} – {Topic/Description} ({Spatial}) {Year}

No length restriction applies. Spaces, em dashes (–), parentheses, and abbreviations in brackets are welcome here.

• dataset.title describes the publication as a whole: source, product name, and coverage.
• resources[].title describes the specific table: adds the distinguishing content (geometry type, scenario, measured quantity, etc.).

---

Examples by Data Category

Geodata

dataset.name	dataset.title	resources[].name	resources[].title
bkg_vg250	BKG Verwaltungsgebiete 1:250,000	bkg_vg250_krs	BKG Verwaltungsgebiete 1:250,000 – Districts (KRS)
bkg_vg250	BKG Verwaltungsgebiete 1:250,000	bkg_vg250_lan	BKG Verwaltungsgebiete 1:250,000 – Federal States (LAN)
osm_deu	OpenStreetMap (OSM) Germany	osm_deu_line	OpenStreetMap (OSM) Germany – Line
osm_deu	OpenStreetMap (OSM) Germany	osm_deu_point	OpenStreetMap (OSM) Germany – Point

Measurement Data / Time Series

dataset.name	dataset.title	resources[].name	resources[].title
hsrm_cleanengine	HSRM cleanEngine - Fuel Cell Measurement	hsrm_cleanengine_ts_48cell_pressure	HSRM cleanEngine - Time Series - 48 Cell FC Stack - Pressure Variation
vernetzen_wind	VerNetzen - Wind Potential	vernetzen_wind_potential_area	VerNetzen - Wind Potential Area

Scenario Data

dataset.name	dataset.title	resources[].name	resources[].title
agora_knde_2024	Agora Energiewende – Klimaneutrales Deutschland (KNDE) 2024	agora_knde_2024_jaehrlich	Agora Energiewende – KNDE 2024 – Annual Values
bmwk_projektionsbericht_2023	BMWK – Projection Report 2023	bmwk_projektionsbericht_2023_rahmendaten	BMWK – Projection Report 2023 – Framework Data

Model Data

dataset.name	dataset.title	resources[].name	resources[].title
uba_emissions_deu	UBA – Greenhouse Gas Emissions Germany	uba_emissions_deu_sector_2022	UBA – Greenhouse Gas Emissions Germany by Sector 2022

Do / Don't

name fields (dataset and table)

✅ Correct	❌ Incorrect	Reason
bkg_vg250_krs	BKG_VG250_Kreise	Uppercase causes PostgreSQL quoting issues
agora_knde_2024_jaehrlich	Agora-KNDE-2024	Hyphens cause SQL syntax errors
osm_deu_line	osm_germany_line_data	Verbose; use ISO country code
rli_opsd_wind_deu_2019	data_2024_final_v3_new	No identifiable source or topic
uba_emissions_sector_2022	2022_emissions	Identifiers must not start with a digit
cleanengine_ts_pressure	cleanEngine_TS_Pressure	Mixed case invalid without quoting

title fields (dataset and table)

✅ Correct	❌ Incorrect	Reason
BKG Verwaltungsgebiete 1:250,000 – Districts (KRS)	bkg_vg250_krs	Title should be human-readable, not a DB identifier
Agora Energiewende – KNDE 2024 – Annual Values	KNDE Annual	Too brief; source and year missing
VerNetzen – Wind Potential Area	Wind Data Table 3	Generic numbering is not meaningful

---

Recommended Abbreviation Registry

To prevent inconsistencies across contributors, a shared abbreviation table should be maintained (e.g., in the project wiki or a dedicated file in this repository).

Sources / Institutes

Abbreviation	Full name
agora	Agora Energiewende
bkg	Bundesamt für Kartographie und Geodäsie
bmwk	Bundesministerium für Wirtschaft und Klimaschutz
osm	OpenStreetMap
rli	Reiner Lemoine Institut
uba	Umweltbundesamt

Spatial Levels (ISO 3166 Alpha-3 + internal)

Abbreviation	Meaning
deu	Germany (national)
eur	Europe
krs	Landkreis / district level
lan	Bundesland / federal state
nuts3	NUTS-3 region
mun	Municipality

Geometry / Table Types

Abbreviation	Meaning
point	Point geometry
line	Line / polyline geometry
area	Polygon / area geometry
ts	Time series
scalar	Non-spatial scalar values

Temporal Resolution

Abbreviation	Meaning
annual	Annual resolution
monthly	Monthly resolution
ts	Time series (generic)
2024	Reference year

---

Checklist for New Datasets

Before uploading a dataset to the OEP, verify the following:

Dataset level

• dataset.name is fully lowercase
• dataset.name uses only letters, digits, and underscores
• dataset.name starts with a letter
• dataset.name is 63 characters or fewer
• dataset.title is a descriptive human-readable label including source and product name
• keywords contains at least one term from the OEO vocabulary
• spatial.location uses ISO 3166 Alpha-3 where applicable
• temporal.referenceDate is set in ISO 8601 format (YYYY-MM-DD)

Table level (per resources[] entry)

• resources[].name is fully lowercase
• resources[].name uses only letters, digits, and underscores
• resources[].name starts with a letter
• resources[].name is 63 characters or fewer
• resources[].name does not use any reserved SQL keywords
• resources[].title extends the dataset title with table-specific detail
• resources[].description explains the content in 1–3 sentences

General

• Source abbreviation is registered in the team abbreviation table
• Dataset name is a prefix of all its table names (or identical for single-table datasets)

---

References

• OEMetadata specification
• OEMetadata schema (latest)
• Open Energy Ontology (OEO)
• OEP Data Review guidelines
• PostgreSQL identifier syntax
• FAIR Principles

[jh-RLI]

That is a very nice initiative 👍 We actually had documentation about it but as not even im able to find it again its really about time to do this properly. Especially with all the new developments.

It should be put onto the documentation page. I think this is also a good point to review the current documentation again. We should provide:

• Docs on how to install the OEP (for development and Production)
• Docs on how get setup and involved in devlopment
• Docs for users, like the conventions this issues tackles
• Docs on the Code

[jh-RLI]

In simple cases (one dataset = one table), both names may be identical.

This is one thing i want to discuss about:
I dont think we should force datasets. I get the point that we always fill the information, etc. As I implement datasets currently they are independent from a table object / resource metadata. I like this separation very much especially regarding how the OEP was designed initially and how dataset metadata is structured also in DCAT-AP etc. . As you mentioned the dataset collects the data resources relevant to the process / scope / task they collected the data for or the data was generated from. Especially if the dataset is input data, it can happen that the same table is used across multiple datasets.

Each table holds its resource metadata. this means we use the resource metadata schema only on table level. If one creates a dataset then they fill the additioanl dataset metadata and then select tables to add to the dataset. Once they added a table the resource metadata added to the dataset resources automatically.

I like this approach because it highlights the difference between the dataset and the resource. One resource / table is created, worked on, edited, deleted, created again, and sooner or later is added to one or multiple datasets. This is very close to how users actually work with data.

What i describe is not against our idea to provide the possibility to create a dataset and tables in one go using the reworked (Work in progress) Upload wizard or the WEB-API. But this only helps users which already have a complete dataset at thier hands.

I vote against always creating a dataset for each table.