feat(changelog): add new features for component properties and taxonomy category

- Introduced optional `properties` for components in `system.yml`, allowing key/value pairs that are normalized into a dictionary.
- Added optional `taxonomy-category` field for models in library YAML files, accessible via `ModelSchema.taxonomy_category`.
- Updated documentation to reflect these changes and provided examples in the user guide.

Author: dusanparipovic

docs/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to GemsPy are documented here.
 
+## [Unreleased]
+
+### Added
+
+- **System components: `properties`** - introduces optional `properties` on components in `system.yml` (a list of `id`/`value` pairs). These are normalized into a `dict[str, str]` on the resolved `Component` (duplicate keys raise a `ValueError`).
+- **Model schema: `taxonomy-category`** - introduces optional `taxonomy-category` on models in library YAML files, exposed as `ModelSchema.taxonomy_category`.
+
 ## [0.1.0] - 2026-04-30
 
 ### Study folder structure

docs/getting-started.md

@@ -29,6 +29,7 @@ library:
 
     - id: generator
       description: A basic generator model
+      taxonomy-category: production
       parameters:
         - id: marginal_cost
           time-dependent: false
@@ -92,6 +93,9 @@ system:
   components:
     - id: G1
       model: basic.generator
+      properties:
+        - key: technology
+          value: nuclear
       parameters:
         - id: marginal_cost
           time-dependent: false

docs/user-guide/inputs.md

@@ -39,6 +39,28 @@ from `input/data-series/modeler-scenariobuilder.dat` (if present).
 Use the lower-level functions when you want to load files individually or build
 parts of the study from in-memory data.
 
+---
+
+## System YAML: optional component `properties`
+
+In `system.yml`, each component may define an optional `properties` section as a
+list of key/value pairs:
+
+~~~ yaml
+system:
+  components:
+    - id: nuclear_1
+      model: basic.generator
+      properties:
+        - id: technology
+          value: nuclear
+        - id: company
+          value: rhonepower
+~~~
+
+At resolution time (`resolve_system` / `load_study`), this list is normalized into
+a `dict[str, str]` stored on the resolved `Component`. Duplicate keys are rejected.
+
 ### Loading the library and the system
 
 ~~~ python

src/gems/study/parsing.py

@@ -56,7 +56,7 @@ class ComponentParameterSchema(ModifiedBaseModel):
 
 
 class ComponentPropertySchema(ModifiedBaseModel):
-    key: str
+    id: str
     value: str
 
 

src/gems/study/resolve_components.py

@@ -12,8 +12,6 @@
 from pathlib import Path
 from typing import Dict, List, Optional, Tuple, Union
 
-import pandas as pd
-
 from gems.model import Model
 from gems.model.library import Library
 from gems.study import (
@@ -50,10 +48,10 @@ def _resolve_properties_raw_to_dict(
         return {}
     properties: Dict[str, str] = {}
     for item in raw:
-        k = item.key
+        k = item.id
         if k in properties:
             raise ValueError(
-                f"Component {component_id!r}: duplicate properties key {k!r}"
+                f"Component {component_id!r}: duplicate properties id {k!r}"
             )
         properties[k] = item.value
     return properties

tests/unittests/system_parsing/test_components_parsing.py

@@ -110,9 +110,9 @@ def test_consistency_check_ko(
     - id: nuclear_1
       model: basic.generator
       properties:
-        - key: technology
+        - id: technology
           value: nuclear
-        - key: company
+        - id: company
           value: rhonepower
 """
 
@@ -162,9 +162,9 @@ def test_parse_yaml_components_properties_missing_key_raises() -> None:
     - id: A
       model: basic.node
       properties:
-        - key: technology
+        - id: technology
           value: nuclear
-        - key: technology
+        - id: technology
           value: gas
 """