dataforcanada/d4c-service-main-site
1
0
Fork 0
mirror of https://github.com/dataforcanada/d4c-service-main-site.git synced 2026-06-13 14:00:51 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add versioning to the file naming convention

Browse Source
This commit is contained in:
Diego Ripley
2026-02-11 17:49:23 -05:00
parent 538fff57e8
commit 6d03f28f32
1 changed files with 25 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/docs/getting_started/file_naming_convention.md
+24 -12
View File
@@ -18,15 +18,15 @@ We are open to feedback on the current file naming convention.
#### **Syntax** #### **Syntax**
`[iso-region]_[source-identifier]_[theme]_[iso-date]_[variant].[extension]` `[iso-region]_[source-identifier]_[theme]_[iso-date]_[variant]_[version].[extension]`
**Example**: **Example**:
`ca-ab_edmonton-2023A00054811061_orthoimagery_2023_075mm.pmtiles` `ca-ab_edmonton-2023A00054811061_orthoimagery_2023_075mm_v0.0.1.pmtiles`
#### **Component Breakdown** #### **Component Breakdown**
| Segment | Definition | Format / Rules | Example | | Segment | Definition | Format / Rules | Example |
| --- | --- | --- | --- | | :--- | :--- | :--- | :--- |
| **1. ISO Region** | The ISO 3166-2 code for the jurisdiction. | Lowercase. Hyphenated. | `ca-ab`, `ca` | | **1. ISO Region** | The ISO 3166-2 code for the jurisdiction. | Lowercase. Hyphenated. | `ca-ab`, `ca` |
| **_** | *Separator* | Underscore | | | **_** | *Separator* | Underscore | |
| **2. Source / Location ID** | **Organization** OR **Location**. | Use `[colloquial-name]-[dguid]` for locations, OR `[organization-name]` for national bodies. | `edmonton-2023A00054811061` OR `statcan` | | **2. Source / Location ID** | **Organization** OR **Location**. | Use `[colloquial-name]-[dguid]` for locations, OR `[organization-name]` for national bodies. | `edmonton-2023A00054811061` OR `statcan` |
@@ -36,6 +36,8 @@ We are open to feedback on the current file naming convention.
| **4. ISO Date** | The vintage of the data source. | **ISO 8601**. Flexible precision. | `2023`, `2023-06`, `2023-06-01` | | **4. ISO Date** | The vintage of the data source. | **ISO 8601**. Flexible precision. | `2023`, `2023-06`, `2023-06-01` |
| **_** | *Separator* | Underscore | | | **_** | *Separator* | Underscore | |
| **5. Variant** | Resolution or specific subset info. | **No Projections.** Alphanumeric. Units included. | `075mm`, `30cm` | | **5. Variant** | Resolution or specific subset info. | **No Projections.** Alphanumeric. Units included. | `075mm`, `30cm` |
| **_** | *Separator* | Underscore | |
| **6. Version** | **Semantic Versioning**. | `v[Major].[Minor].[Patch]` | `v0.0.1` |
## 2. Component Detail ## 2. Component Detail
@@ -44,11 +46,9 @@ We are open to feedback on the current file naming convention.
This segment defines the "Who" or "Where" of the dataset. This segment defines the "Who" or "Where" of the dataset.
* **For Geographic Datasets:** Use the **Colloquial Name** + **Hyphen** + **DGUID**. * **For Geographic Datasets:** Use the **Colloquial Name** + **Hyphen** + **DGUID**.
* *Example:* `edmonton-2023A00054811061` * *Example:* `edmonton-2023A00054811061`
* **For Organization Datasets:** Use the **Organization Acronym** when the data is national or not tied to a single DGUID. * **For Organization Datasets:** Use the **Organization Acronym** when the data is national or not tied to a single DGUID.
* *Example:* `statcan`, `cmhc`, `nrcan` * *Example:* `statcan`, `cmhc`, `nrcan`
### B. The DGUID (Capitalization Exception) ### B. The DGUID (Capitalization Exception)
@@ -66,8 +66,8 @@ Dates follow strictly **ISO 8601**, but the precision can vary based on the natu
**Examples of Date Precision:** **Examples of Date Precision:**
* **Month Precision:** `ca_statcan_national_address_register_2024-12.parquet` * **Month Precision:** `ca_statcan_national_address_register_2024-12_v0.0.1.parquet`
* **Day Precision:** `ca_statcan_open_database_of_buildings_2025-04-15.parquet` * **Day Precision:** `ca_statcan_open_database_of_buildings_2025-04-15_v0.0.1.parquet`
### D. Variant ### D. Variant
@@ -76,18 +76,30 @@ This field is strictly for **resolution** (e.g., `075mm`, `1m`) or content subse
* **Rule:** **Do not include projection information** (e.g., `EPSG:3857`, `NAD83`) in the filename. * **Rule:** **Do not include projection information** (e.g., `EPSG:3857`, `NAD83`) in the filename.
* **Reasoning:** Projection details are handled exclusively in the file format metadata or the accompanying **[FAIR Data Catalog](https://stac-utils.github.io/stac-geoparquet/latest/spec/stac-geoparquet-spec/)** item. * **Reasoning:** Projection details are handled exclusively in the file format metadata or the accompanying **[FAIR Data Catalog](https://stac-utils.github.io/stac-geoparquet/latest/spec/stac-geoparquet-spec/)** item.
### E. Semantic Versioning
We use **SemVer** (`vMAJOR.MINOR.PATCH`) to track changes to datasets.
* **Link:** [SemVer.org](https://semver.org/)
| Component | Logic for Data | Example Scenario |
| :--- | :--- | :--- |
| **MAJOR** | **Breaking Change.** The schema changed, columns were renamed/removed, or the meaning of the data changed significantly. Old code will break. | `v0.0.1` → `v1.0.0`<br>*(Renamed column `geo_id` to `dguid`)* |
| **MINOR** | **New Feature (Non-Breaking).** New columns were added, or coverage was expanded, but old columns remain. Old code still runs. | `v0.0.1` → `v0.1.0`<br>*(Added a `population_density` column)* |
| **PATCH** | **Bug Fix.** Incorrect data values were fixed, but the schema (columns) is identical. | `v0.0.1` → `v0.0.2`<br>*(Fixed typo in metadata or coordinate precision)* |
## 3. Example Scenarios ## 3. Example Scenarios
### **Scenario 1: High-Res Orthoimagery (Location Based)** ### **Scenario 1: High-Res Orthoimagery (Location Based)**
* **Context:** 7.5cm pixel resolution imagery of Edmonton, Alberta from 2023. * **Context:** Initial release (v0.0.1) of 7.5cm pixel resolution imagery of Edmonton, Alberta from 2023.
* **File Name:** `ca-ab_edmonton-2023A00054811061_orthoimagery_2023_075mm.pmtiles` * **File Name:** `ca-ab_edmonton-2023A00054811061_orthoimagery_2023_075mm_v0.0.1.pmtiles`
* **Reference:** [Preview and Download Orthoimagery](https://www.dataforcanada.org/docs/processes/orthoimagery/#download-and-preview) * **Reference:** [Preview and Download Orthoimagery](https://www.dataforcanada.org/docs/processes/orthoimagery/#download-and-preview)
### **Scenario 2: National Organization Data (Source Based)** ### **Scenario 2: National Organization Data (Source Based)**
* **Context:** The Open Database of Buildings released by Statistics Canada on April 15, 2025. * **Context:** The Open Database of Buildings released by Statistics Canada on April 15, 2025.
* **File Name:** `ca_statcan_census_pop_dissemination_areas_tabular_2021` * **File Name:** `ca_statcan_census_pop_dissemination_areas_tabular_2021_v0.0.1.parquet`
* **Reference:** [Preview and Download Census Data](https://www.dataforcanada.org/docs/processes/statistical_products/statistics_canada/census_data/#how-to-use-the-map-preview) * **Reference:** [Preview and Download Census Data](https://www.dataforcanada.org/docs/processes/statistical_products/statistics_canada/census_data/#how-to-use-the-map-preview)
## 4. Helper Tools ## 4. Helper Tools