Harden @odata.bind handling: perf fix, warning, and skill docs

- Skip @OData. keys in _convert_labels_to_ints to avoid unnecessary
  metadata HTTP calls for every @odata.bind key in record payloads
- Add runtime warning when @odata.bind keys use lowercase navigation
  property names (likely to cause 400 "undeclared property" errors)
- Fix _get $select consistency: lowercase column names like _get_multiple
- Add tests for warning behavior and _convert_labels_to_ints skip
- Update dataverse-sdk-dev skill with property naming rules (structural
  vs navigation) to help contributors avoid casing bugs
- Update dataverse-sdk-use skill with @odata.bind examples and
  troubleshooting guidance

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: suyask-msft

.claude/skills/dataverse-sdk-dev/SKILL.md

@@ -20,6 +20,28 @@ This skill provides guidance for developers working on the PowerPlatform Dataver
 5. **Consider backwards compatibility** - Avoid breaking changes
 6. **Internal vs public naming** - Modules, files, and functions not meant to be part of the public API must use a `_` prefix (e.g., `_odata.py`, `_relationships.py`). Files without the prefix (e.g., `constants.py`, `metadata.py`) are public and importable by SDK consumers
 
+### Dataverse Property Naming Rules
+
+Dataverse uses two different naming conventions for properties. Getting this wrong causes 400 errors that are hard to debug.
+
+| Property type | Name convention | Example | When used |
+|---|---|---|---|
+| **Structural** (columns) | LogicalName = always lowercase | `new_name`, `new_priority` | `$select`, `$filter`, `$orderby`, record payload keys |
+| **Navigation** (lookups) | SchemaName = PascalCase | `new_CustomerId`, `new_AgentId` | `$expand`, `@odata.bind` annotation keys |
+
+**Critical rule:** The OData parser validates `@odata.bind` property names **case-sensitively** against declared navigation properties. Lowercasing `new_CustomerId@odata.bind` to `new_customerid@odata.bind` causes: `ODataException: An undeclared property 'new_customerid' which only has property annotations...`
+
+**SDK implementation:**
+- `_lowercase_keys()` lowercases all keys EXCEPT those containing `@odata.` -- this preserves navigation property casing in `@odata.bind` keys
+- `_lowercase_list()` lowercases `$select`/`$orderby` params (structural properties)
+- `$expand` params are passed as-is (navigation properties, PascalCase)
+- `_convert_labels_to_ints()` skips `@odata.` keys entirely (they are annotations, not attributes)
+
+**When adding new code that processes record dicts or builds query parameters:**
+- Always use `_lowercase_keys()` for record payloads -- never manually call `.lower()` on all keys
+- Never lowercase `$expand` values or `@odata.bind` key prefixes
+- If iterating record keys, skip keys containing `@odata.` when doing attribute-level operations
+
 ### Code Style
 
 6. **No emojis** - Do not use emoji in code, comments, or output

.claude/skills/dataverse-sdk-use/SKILL.md

@@ -105,6 +105,20 @@ for page in client.records.get(
         print(f"{account['name']} - {contact.get('fullname', 'N/A')}")
 ```
 
+#### Create Records with Lookup Bindings (@odata.bind)
+```python
+# Set lookup fields using @odata.bind with PascalCase navigation property names
+# CORRECT: PascalCase SchemaName before @odata.bind
+guid = client.records.create("new_ticket", {
+    "new_name": "TKT-001",
+    "new_CustomerId@odata.bind": f"/new_customers({customer_id})",
+    "new_AgentId@odata.bind": f"/new_agents({agent_id})",
+})
+
+# WRONG: lowercase navigation property causes 400 error
+# "new_customerid@odata.bind" -> ODataException: undeclared property 'new_customerid'
+```
+
 #### Update Records
 ```python
 # Single update
@@ -359,6 +373,7 @@ except ValidationError as e:
 - Check filter/expand parameters use correct case
 - Verify column names exist and are spelled correctly
 - Ensure custom columns include customization prefix
+- For `@odata.bind` errors ("undeclared property"): the navigation property name before `@odata.bind` must use **PascalCase SchemaName** (e.g., `new_CustomerId@odata.bind`), not lowercase. The OData parser is case-sensitive for navigation property names. The SDK preserves `@odata.bind` key casing and emits a warning if it detects likely-wrong lowercase casing.
 
 ## Best Practices
 
@@ -371,7 +386,7 @@ except ValidationError as e:
 5. **Use production credentials** - ClientSecretCredential or CertificateCredential for unattended operations
 6. **Error handling** - Implement retry logic for transient errors (`e.is_transient`)
 7. **Always include customization prefix** for custom tables/columns
-8. **Use lowercase** - Generally using lowercase input won't go wrong, except for custom table/column naming
+8. **Use lowercase for column names, PascalCase for navigation properties** - Column names in `$select`/`$filter`/record payloads use lowercase LogicalNames. Navigation properties in `$expand` and `@odata.bind` keys use PascalCase SchemaName (e.g., `new_CustomerId@odata.bind`)
 9. **Test in non-production environments** first
 10. **Use named constants** - Import cascade behavior constants from `PowerPlatform.Dataverse.common.constants`
 

src/PowerPlatform/Dataverse/claude_skill/dataverse-sdk-use/SKILL.md

@@ -105,6 +105,20 @@ for page in client.records.get(
         print(f"{account['name']} - {contact.get('fullname', 'N/A')}")
 ```
 
+#### Create Records with Lookup Bindings (@odata.bind)
+```python
+# Set lookup fields using @odata.bind with PascalCase navigation property names
+# CORRECT: PascalCase SchemaName before @odata.bind
+guid = client.records.create("new_ticket", {
+    "new_name": "TKT-001",
+    "new_CustomerId@odata.bind": f"/new_customers({customer_id})",
+    "new_AgentId@odata.bind": f"/new_agents({agent_id})",
+})
+
+# WRONG: lowercase navigation property causes 400 error
+# "new_customerid@odata.bind" -> ODataException: undeclared property 'new_customerid'
+```
+
 #### Update Records
 ```python
 # Single update
@@ -359,6 +373,7 @@ except ValidationError as e:
 - Check filter/expand parameters use correct case
 - Verify column names exist and are spelled correctly
 - Ensure custom columns include customization prefix
+- For `@odata.bind` errors ("undeclared property"): the navigation property name before `@odata.bind` must use **PascalCase SchemaName** (e.g., `new_CustomerId@odata.bind`), not lowercase. The OData parser is case-sensitive for navigation property names. The SDK preserves `@odata.bind` key casing and emits a warning if it detects likely-wrong lowercase casing.
 
 ## Best Practices
 
@@ -371,7 +386,7 @@ except ValidationError as e:
 5. **Use production credentials** - ClientSecretCredential or CertificateCredential for unattended operations
 6. **Error handling** - Implement retry logic for transient errors (`e.is_transient`)
 7. **Always include customization prefix** for custom tables/columns
-8. **Use lowercase** - Generally using lowercase input won't go wrong, except for custom table/column naming
+8. **Use lowercase for column names, PascalCase for navigation properties** - Column names in `$select`/`$filter`/record payloads use lowercase LogicalNames. Navigation properties in `$expand` and `@odata.bind` keys use PascalCase SchemaName (e.g., `new_CustomerId@odata.bind`)
 9. **Test in non-production environments** first
 10. **Use named constants** - Import cascade behavior constants from `PowerPlatform.Dataverse.common.constants`
 

src/PowerPlatform/Dataverse/data/_odata.py

@@ -13,6 +13,7 @@
 import re
 import json
 import uuid
+import warnings
 from datetime import datetime, timezone
 import importlib.resources as ir
 from contextlib import contextmanager
@@ -99,10 +100,28 @@ def _lowercase_keys(record: Dict[str, Any]) -> Dict[str, Any]:
 
         Keys containing ``@odata.`` (e.g. ``new_CustomerId@odata.bind``) are
         preserved as-is because the navigation property portion before ``@``
-        must retain its original casing (PascalCase SchemaName).
+        must retain its original casing (PascalCase SchemaName).  The OData
+        parser validates ``@odata.bind`` property names **case-sensitively**
+        against the entity's declared navigation properties, so lowercasing
+        these keys causes ``400 - undeclared property`` errors.
         """
         if not isinstance(record, dict):
             return record
+        for k in record:
+            if isinstance(k, str) and "@odata.bind" in k:
+                nav_prop = k.split("@odata.bind")[0]
+                if nav_prop and nav_prop == nav_prop.lower() and "_" in nav_prop:
+                    # Likely already-lowercased navigation property name.
+                    # Navigation properties use PascalCase SchemaName (e.g.
+                    # new_CustomerId), not lowercase LogicalName.
+                    warnings.warn(
+                        f"@odata.bind key '{k}' appears to use a lowercase "
+                        f"navigation property name. Dataverse requires "
+                        f"PascalCase SchemaName (e.g. 'new_CustomerId@odata.bind',"
+                        f" not 'new_customerid@odata.bind'). This will likely "
+                        f"cause a 400 error.",
+                        stacklevel=4,
+                    )
         return {k.lower() if isinstance(k, str) and "@odata." not in k else k: v for k, v in record.items()}
 
     @staticmethod
@@ -724,7 +743,7 @@ def _get(self, table_schema_name: str, key: str, select: Optional[List[str]] = N
         params = {}
         if select:
             # Lowercase column names for case-insensitive matching
-            params["$select"] = ",".join(select)
+            params["$select"] = ",".join(self._lowercase_list(select))
         entity_set = self._entity_set_from_schema_name(table_schema_name)
         url = f"{self.api}/{entity_set}{self._format_key(key)}"
         r = self._request("get", url, params=params)
@@ -1324,6 +1343,9 @@ def _convert_labels_to_ints(self, table_schema_name: str, record: Dict[str, Any]
         for k, v in list(out.items()):
             if not isinstance(v, str) or not v.strip():
                 continue
+            # Skip OData annotations — they are not attribute names
+            if isinstance(k, str) and "@odata." in k:
+                continue
             mapping = self._optionset_map(table_schema_name, k)
             if not mapping:
                 continue

tests/unit/data/test_odata_internal.py

@@ -354,6 +354,63 @@ def test_odata_bind_keys_preserve_case(self):
         self.assertIn("new_CustomerId@odata.bind", payload)
         self.assertNotIn("new_customerid@odata.bind", payload)
 
+    def test_odata_bind_lowercase_warns(self):
+        """Lowercase @odata.bind nav property emits a warning."""
+        import warnings
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            self.od._upsert(
+                "accounts",
+                "account",
+                {"accountnumber": "ACC-001"},
+                {
+                    "name": "Contoso",
+                    "new_customerid@odata.bind": "/contacts(00000000-0000-0000-0000-000000000001)",
+                },
+            )
+            odata_warnings = [x for x in w if "@odata.bind" in str(x.message)]
+            self.assertEqual(len(odata_warnings), 1)
+            self.assertIn("PascalCase", str(odata_warnings[0].message))
+
+    def test_odata_bind_pascalcase_no_warning(self):
+        """PascalCase @odata.bind nav property does NOT emit a warning."""
+        import warnings
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            self.od._upsert(
+                "accounts",
+                "account",
+                {"accountnumber": "ACC-001"},
+                {
+                    "name": "Contoso",
+                    "new_CustomerId@odata.bind": "/contacts(00000000-0000-0000-0000-000000000001)",
+                },
+            )
+            odata_warnings = [x for x in w if "@odata.bind" in str(x.message)]
+            self.assertEqual(len(odata_warnings), 0)
+
+    def test_convert_labels_skips_odata_keys(self):
+        """_convert_labels_to_ints should skip @odata.bind keys (no metadata lookup)."""
+        # Patch _optionset_map to track calls
+        calls = []
+        original = self.od._optionset_map
+
+        def tracking_optionset_map(table, attr):
+            calls.append(attr)
+            return original(table, attr)
+
+        self.od._optionset_map = tracking_optionset_map
+        record = {
+            "name": "Contoso",
+            "new_CustomerId@odata.bind": "/contacts(00000000-0000-0000-0000-000000000001)",
+            "@odata.type": "Microsoft.Dynamics.CRM.account",
+        }
+        self.od._convert_labels_to_ints("account", record)
+        # Only "name" should be checked, not the @odata keys
+        self.assertEqual(calls, ["name"])
+
     def test_returns_none(self):
         """_upsert always returns None."""
         result = self.od._upsert("accounts", "account", {"accountnumber": "ACC-001"}, {"name": "Contoso"})