Refactor BPMN handling for consistency and parsing improvements

.github/workflows/build-python.yaml

@@ -25,7 +25,7 @@ jobs:
       attestations: write
     steps:
       - name: Checkout
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
           ref: ${{ inputs.ref }}
@@ -62,7 +62,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Download packages built by build-and-inspect-python-package
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v7
         with:
           name: Packages
           path: dist

.github/workflows/bump-version-preview.yaml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout the repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 

.github/workflows/bump-version.yaml

@@ -15,7 +15,7 @@ jobs:
       tag_name: ${{ steps.bump-version.outputs.tag_name }}
     steps:
       - name: Checkout the repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
@@ -60,6 +60,8 @@ jobs:
               echo "build_package=false" >> $GITHUB_OUTPUT
               ;;
           esac
+        env:
+          GH_TOKEN: ${{ github.token }}
 
   call-build-python:
     needs: bump-version

.github/workflows/codeql-analysis.yml

@@ -38,7 +38,7 @@ jobs:
 
     steps:
     - name: Checkout repository
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL

.github/workflows/publish-docs-preview.yaml

@@ -21,7 +21,7 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
       with:
         fetch-depth: 0
 

.github/workflows/publish-docs.yaml

@@ -17,7 +17,7 @@ jobs:
 
     steps:
     - name: Checkout
-      uses: actions/checkout@v5
+      uses: actions/checkout@v6
       with:
         fetch-depth: 0
 

.github/workflows/release-container.yaml

@@ -29,7 +29,7 @@ jobs:
       id-token: write
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v5
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
           ref: ${{ inputs.ref }}

.github/workflows/release-github.yaml

@@ -16,7 +16,7 @@ jobs:
       packages: write
       id-token: write
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         name: Checkout the repository
         with:
           fetch-depth: 0
@@ -30,7 +30,7 @@ jobs:
           target-version: ${{ inputs.ref }}
 
       - name: Download packages built by build-and-inspect-python-package
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v7
         with:
           name: Packages
           path: dist

.github/workflows/test.yaml

@@ -15,7 +15,7 @@ jobs:
         python-version: ["3.12", "3.13"]
 
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v6
 
     - name: Install uv
       uses: astral-sh/setup-uv@v7

docs/SUMMARY.md

@@ -8,7 +8,7 @@
     * [Using Vendor Extensions](tutorials/extensions.md)
 * [Architecture Overview](architecture/index.md)
     * [Core Components](architecture/components.md)
-* [API Reference](reference/index.md)
+* [API Reference](reference/)
 * [Development Guide](development.md)
 * [Explanation](explanation.md)
 * [How-Tos](howtos/index.md)

docs/index.md

@@ -62,7 +62,7 @@ See the [Installation Guide](installation.md) for more options.
 - **[How-Tos](howtos/index.md)** - Solutions to specific problems
 
 ### Reference
-- **[API Reference](reference/index.md)** - Complete API documentation
+- **[API Reference](reference/api/)** - Complete API documentation
 - **[Architecture](architecture/index.md)** - System design and internals
 
 ### Extending

docs/reference/SUMMARY.md

@@ -0,0 +1 @@
+[API](api/)

mkdocs.yml

@@ -106,17 +106,3 @@ extra_css:
 
 watch:
   - pybpmn_parser
-
-nav:
-  - Home: index.md
-  - Installation: installation.md
-  - Quick Start: quickstart.md
-  - Tutorials: tutorials/index.md
-  - Examples Gallery: examples/index.md
-  - Plugin Guide: plugins/index.md
-  - Architecture Overview: architecture/index.md
-  - Core Components: architecture/components.md
-  - Reference: reference/index.md
-  - Development Guide: development.md
-  - Explanation: explanation.md
-  - How-Tos: howtos/index.md

pybpmn_parser/bpmn/activities/activity.py

@@ -196,6 +196,7 @@ class Activity(FlowNode):  # Is Abstract
         default=None,
         metadata={
             "type": "Attribute",
+            "is_reference": True,
         },
     )
     """The Sequence Flow that receives a token when `conditionExpression`s on other outgoing Sequence Flows are false.

pybpmn_parser/bpmn/activities/loop_characteristics.py

@@ -49,6 +49,7 @@ class MultiInstanceLoopCharacteristics(LoopCharacteristics):
             "name": "loopDataInputRef",
             "type": "Element",
             "namespace": "http://www.omg.org/spec/BPMN/20100524/MODEL",
+            "is_reference": True,
         },
     )
     loop_data_output_ref: Optional[str] = field(
@@ -57,6 +58,7 @@ class MultiInstanceLoopCharacteristics(LoopCharacteristics):
             "name": "loopDataOutputRef",
             "type": "Element",
             "namespace": "http://www.omg.org/spec/BPMN/20100524/MODEL",
+            "is_reference": True,
         },
     )
     input_data_item: Optional[DataInput] = field(
@@ -109,13 +111,15 @@ class MultiInstanceLoopCharacteristics(LoopCharacteristics):
         metadata={
             "name": "oneBehaviorEventRef",
             "type": "Attribute",
+            "is_reference": True,
         },
     )
     none_behavior_event_ref: Optional[str] = field(
         default=None,
         metadata={
             "name": "noneBehaviorEventRef",
             "type": "Attribute",
+            "is_reference": True,
         },
     )
 

pybpmn_parser/bpmn/activities/receive_task.py

@@ -32,13 +32,15 @@ class ReceiveTask(Task):
         metadata={
             "name": "messageRef",
             "type": "Attribute",
+            "is_reference": True,
         },
     )
     operation_ref: Optional[str] = field(
         default=None,
         metadata={
             "name": "operationRef",
             "type": "Attribute",
+            "is_reference": True,
         },
     )
 

pybpmn_parser/bpmn/activities/send_task.py

@@ -26,13 +26,15 @@ class SendTask(Task):
         metadata={
             "name": "messageRef",
             "type": "Attribute",
+            "is_reference": True,
         },
     )
     operation_ref: Optional[str] = field(
         default=None,
         metadata={
             "name": "operationRef",
             "type": "Attribute",
+            "is_reference": True,
         },
     )
 

pybpmn_parser/bpmn/common/resource_parameter_binding.py

@@ -37,6 +37,7 @@ class ResourceParameterBinding(BaseElement):
             "name": "parameterRef",
             "type": "Attribute",
             "required": True,
+            "is_reference": True,
         }
     )
 

pybpmn_parser/element_registry.py

@@ -100,7 +100,7 @@ def descriptor_from_class(element_class: Any) -> ElementDescriptor:
     return ElementDescriptor(type=element_class, name=q_name.local, q_name=q_name, properties=property_name_map)
 
 
-def type_hint_to_property(name: str, type_hint: Any, field_metadata: dict[str, str]) -> ElementProperty:
+def type_hint_to_property(name: str, type_hint: Any, field_metadata: dict[str, Any]) -> ElementProperty:
     """
     Converts a type hint represented as a dictionary into an `ElementProperty` object.
 
@@ -131,6 +131,7 @@ def type_hint_to_property(name: str, type_hint: Any, field_metadata: dict[str, s
     is_attr = field_metadata.get("type", "Element") == "Attribute"
     is_optional = origin == Union and type(None) in args
     is_many = origin is list or (origin == Union and list in args)
+    is_reference: bool = field_metadata.get("is_reference", False)
     base_type = get_base_type(type_)
     q_name = QName(uri=base_type.Meta.namespace, local=base_type.Meta.name) if hasattr(base_type, "Meta") else None
 
@@ -141,6 +142,7 @@ def type_hint_to_property(name: str, type_hint: Any, field_metadata: dict[str, s
         is_attr=is_attr,
         is_optional=is_optional,
         is_many=is_many,
+        is_reference=is_reference,
     )
 
 
@@ -235,13 +237,6 @@ def get_base_type(type_: type) -> Any:
 
     # Handle list type
     if origin is list:
-        if not args:
-            return list
-        return get_base_type(args[0])
-
+        return get_base_type(args[0]) if args else list
     # Handle dict type
-    if origin is dict:
-        return dict
-
-    # Handle other generic types
-    return type_
+    return dict if origin is dict else type_