Fix @odata.bind key casing and harden OData annotation handling (#137)

# Fix @odata.bind key casing and harden OData annotation handling

## Summary

The SDK's `_lowercase_keys()` was unconditionally lowercasing all
dictionary keys in record payloads, including `@odata.bind` annotation
keys like `new_CustomerId@odata.bind`. This broke lookup field bindings
because the Dataverse OData parser validates navigation property names
**case-sensitively**.

**Root cause:** Dataverse uses two naming conventions:
- **Structural properties** (columns): LogicalName, always lowercase
(`new_name`, `new_priority`)
- **Navigation properties** (lookups): SchemaName, PascalCase
(`new_CustomerId`, `new_AgentId`)

The OData parser (`Microsoft.OData.Core`) rejects lowercased navigation
property names with: `ODataException: An undeclared property
'new_customerid' which only has property annotations in the payload but
no property value was found in the payload.`

Note: CDS's internal RelationshipService *is* case-insensitive, but it
never runs because the OData parser rejects the payload first.

## Changes

### Bug fixes
- **Preserve `@odata.bind` key casing** -- `_lowercase_keys()` now skips
keys containing `@odata.`, preserving the PascalCase navigation property
name that Dataverse requires
- **Skip `@odata.` keys in `_convert_labels_to_ints()`** -- Previously
made unnecessary HTTP metadata API calls for every `@odata.bind` key
(checking if it's a picklist attribute). These always returned empty
results but wasted an HTTP round-trip per annotation key per record on
every create/update/upsert
- **Fix `_get` `$select` consistency** -- Single-record `_get()` now
lowercases `$select` column names via `_lowercase_list()`, matching the
behavior of `_get_multiple()`

### Developer guardrails
- **Runtime warning for likely-wrong casing** -- `_lowercase_keys()` now
emits a `warnings.warn()` when it detects an `@odata.bind` key where the
navigation property portion is all-lowercase (e.g.,
`new_customerid@odata.bind`), alerting developers before they hit a
cryptic 400 error

### Tests
- `test_odata_bind_keys_preserve_case` -- PascalCase `@odata.bind` keys
are preserved through the write path
- `test_odata_bind_lowercase_warns` -- Lowercase nav property in
`@odata.bind` triggers a warning
- `test_odata_bind_pascalcase_no_warning` -- Correct PascalCase does not
trigger false positive
- `test_convert_labels_skips_odata_keys` -- Verifies
`_convert_labels_to_ints` does not call `_optionset_map` for `@odata.`
keys

### Documentation
- **`dataverse-sdk-dev` skill** -- Added "Dataverse Property Naming
Rules" section explaining structural vs navigation property conventions
and implementation rules for contributors
- **`dataverse-sdk-use` skill** -- Added `@odata.bind` usage examples,
400 error troubleshooting guidance, and corrected best practice on
casing

## Before / After

**Before:** SDK sent `{"new_customerid@odata.bind": ...}` -- 400 error

**After:** SDK sends `{"new_CustomerId@odata.bind": ...}` -- success

```python
# User code (unchanged -- SDK now preserves their casing correctly)
client.records.create("new_ticket", {
    "new_name": "TKT-001",
    "new_CustomerId@odata.bind": "/new_customers(guid)",
})

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: suyask-msft

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

@@ -20,6 +20,32 @@ 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** (relationships / lookups) | Navigation Property Name (usually SchemaName, PascalCase, case-sensitive) | `new_CustomerId`, `new_AgentId` | `$expand`, `@odata.bind` annotation keys |
+
+Navigation property names are case-sensitive and must match the entity's `$metadata`. Using the logical name instead of the navigation property name results in 400 Bad Request errors.
+
+**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.` (preserves navigation property casing in `@odata.bind` keys)
+- `_lowercase_list()` lowercases `$select` and `$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: use the navigation property name (case-sensitive, must match $metadata)
+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` is case-sensitive and must match the entity's `$metadata` exactly (e.g., `new_CustomerId@odata.bind` for custom lookups, `parentaccountid@odata.bind` for system lookups). The SDK preserves `@odata.bind` key 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, match `$metadata` for navigation properties** - Column names in `$select`/`$filter`/record payloads use lowercase LogicalNames. Navigation properties in `$expand` and `@odata.bind` keys are case-sensitive and must match the entity's `$metadata` (PascalCase for custom lookups like `new_CustomerId`, lowercase for system lookups like `parentaccountid`)
 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: use the navigation property name (case-sensitive, must match $metadata)
+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` is case-sensitive and must match the entity's `$metadata` exactly (e.g., `new_CustomerId@odata.bind` for custom lookups, `parentaccountid@odata.bind` for system lookups). The SDK preserves `@odata.bind` key 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, match `$metadata` for navigation properties** - Column names in `$select`/`$filter`/record payloads use lowercase LogicalNames. Navigation properties in `$expand` and `@odata.bind` keys are case-sensitive and must match the entity's `$metadata` (PascalCase for custom lookups like `new_CustomerId`, lowercase for system lookups like `parentaccountid`)
 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

@@ -96,10 +96,17 @@ def _lowercase_keys(record: Dict[str, Any]) -> Dict[str, Any]:
 
         Dataverse LogicalNames for attributes are stored lowercase, but users may
         provide PascalCase names (matching SchemaName). This normalizes the input.
+
+        Keys containing ``@odata.`` (e.g. ``new_CustomerId@odata.bind``) are
+        preserved as-is because the navigation property portion before ``@``
+        must retain its original casing (case-sensitive navigation property name).  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
-        return {k.lower() if isinstance(k, str) else k: v for k, v in record.items()}
+        return {k.lower() if isinstance(k, str) and "@odata." not in k else k: v for k, v in record.items()}
 
     @staticmethod
     def _lowercase_list(items: Optional[List[str]]) -> Optional[List[str]]:
@@ -720,7 +727,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)
@@ -1320,6 +1327,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

@@ -291,6 +291,156 @@ def test_select_bare_string_raises_type_error(self):
         self.assertIn("list of property names", str(ctx.exception))
 
 
+class TestCreate(unittest.TestCase):
+    """Unit tests for _ODataClient._create."""
+
+    def setUp(self):
+        self.od = _make_odata_client()
+        # Mock response with OData-EntityId header containing a GUID
+        mock_resp = MagicMock()
+        mock_resp.headers = {
+            "OData-EntityId": "https://example.crm.dynamics.com/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)"
+        }
+        self.od._request.return_value = mock_resp
+
+    def _post_call(self):
+        """Return the single POST call args from _request."""
+        post_calls = [c for c in self.od._request.call_args_list if c.args[0] == "post"]
+        self.assertEqual(len(post_calls), 1, "expected exactly one POST call")
+        return post_calls[0]
+
+    def test_record_keys_lowercased(self):
+        """Regular record field names are lowercased before sending."""
+        self.od._create("accounts", "account", {"Name": "Contoso", "AccountNumber": "ACC-001"})
+        call = self._post_call()
+        payload = call.kwargs["json"]
+        self.assertIn("name", payload)
+        self.assertIn("accountnumber", payload)
+        self.assertNotIn("Name", payload)
+        self.assertNotIn("AccountNumber", payload)
+
+    def test_odata_bind_keys_preserve_case(self):
+        """@odata.bind keys preserve navigation property casing in _create."""
+        self.od._create(
+            "new_tickets",
+            "new_ticket",
+            {
+                "new_name": "Ticket 1",
+                "new_CustomerId@odata.bind": "/contacts(00000000-0000-0000-0000-000000000001)",
+                "new_AgentId@odata.bind": "/systemusers(00000000-0000-0000-0000-000000000002)",
+            },
+        )
+        call = self._post_call()
+        payload = call.kwargs["json"]
+        self.assertIn("new_name", payload)
+        self.assertIn("new_CustomerId@odata.bind", payload)
+        self.assertIn("new_AgentId@odata.bind", payload)
+        self.assertNotIn("new_customerid@odata.bind", payload)
+        self.assertNotIn("new_agentid@odata.bind", payload)
+
+    def test_returns_guid_from_odata_entity_id(self):
+        """_create returns the GUID from the OData-EntityId header."""
+        result = self.od._create("accounts", "account", {"name": "Contoso"})
+        self.assertEqual(result, "00000000-0000-0000-0000-000000000001")
+
+    def test_returns_guid_from_odata_entity_id_uppercase(self):
+        """_create returns the GUID from the OData-EntityID header (uppercase D)."""
+        mock_resp = MagicMock()
+        mock_resp.headers = {
+            "OData-EntityID": "https://example.crm.dynamics.com/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000002)"
+        }
+        self.od._request.return_value = mock_resp
+        result = self.od._create("accounts", "account", {"name": "Contoso"})
+        self.assertEqual(result, "00000000-0000-0000-0000-000000000002")
+
+    def test_returns_guid_from_location_header_fallback(self):
+        """_create falls back to Location header when OData-EntityId is absent."""
+        mock_resp = MagicMock()
+        mock_resp.headers = {
+            "Location": "https://example.crm.dynamics.com/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000003)"
+        }
+        self.od._request.return_value = mock_resp
+        result = self.od._create("accounts", "account", {"name": "Contoso"})
+        self.assertEqual(result, "00000000-0000-0000-0000-000000000003")
+
+    def test_raises_runtime_error_when_no_guid_in_headers(self):
+        """_create raises RuntimeError when neither header contains a GUID."""
+        mock_resp = MagicMock()
+        mock_resp.headers = {}
+        mock_resp.status_code = 204
+        self.od._request.return_value = mock_resp
+        with self.assertRaises(RuntimeError):
+            self.od._create("accounts", "account", {"name": "Contoso"})
+
+    def test_issues_post_to_entity_set_url(self):
+        """_create issues a POST request to the entity set URL."""
+        self.od._create("accounts", "account", {"name": "Contoso"})
+        call = self._post_call()
+        self.assertIn("/accounts", call.args[1])
+
+
+class TestUpdate(unittest.TestCase):
+    """Unit tests for _ODataClient._update."""
+
+    def setUp(self):
+        self.od = _make_odata_client()
+        # _update needs _entity_set_from_schema_name to resolve entity set
+        self.od._entity_set_from_schema_name = MagicMock(return_value="new_tickets")
+
+    def _patch_call(self):
+        """Return the single PATCH call args from _request."""
+        patch_calls = [c for c in self.od._request.call_args_list if c.args[0] == "patch"]
+        self.assertEqual(len(patch_calls), 1, "expected exactly one PATCH call")
+        return patch_calls[0]
+
+    def test_record_keys_lowercased(self):
+        """Regular field names are lowercased in _update."""
+        self.od._update("new_ticket", "00000000-0000-0000-0000-000000000001", {"New_Status": 100000001})
+        call = self._patch_call()
+        payload = call.kwargs["json"]
+        self.assertIn("new_status", payload)
+        self.assertNotIn("New_Status", payload)
+
+    def test_odata_bind_keys_preserve_case(self):
+        """@odata.bind keys preserve navigation property casing in _update."""
+        self.od._update(
+            "new_ticket",
+            "00000000-0000-0000-0000-000000000001",
+            {
+                "new_status": 100000001,
+                "new_CustomerId@odata.bind": "/contacts(00000000-0000-0000-0000-000000000002)",
+            },
+        )
+        call = self._patch_call()
+        payload = call.kwargs["json"]
+        self.assertIn("new_status", payload)
+        self.assertIn("new_CustomerId@odata.bind", payload)
+        self.assertNotIn("new_customerid@odata.bind", payload)
+
+    def test_sends_if_match_star_header(self):
+        """PATCH request includes If-Match: * header."""
+        self.od._update("new_ticket", "00000000-0000-0000-0000-000000000001", {"new_status": 1})
+        call = self._patch_call()
+        headers = call.kwargs.get("headers", {})
+        self.assertEqual(headers.get("If-Match"), "*")
+
+    def test_url_formats_bare_guid(self):
+        """PATCH URL wraps a bare GUID in parentheses."""
+        self.od._update("new_ticket", "00000000-0000-0000-0000-000000000001", {"new_status": 1})
+        call = self._patch_call()
+        self.assertIn("(00000000-0000-0000-0000-000000000001)", call.args[1])
+
+    def test_returns_none(self):
+        """_update always returns None."""
+        result = self.od._update("new_ticket", "00000000-0000-0000-0000-000000000001", {"new_status": 1})
+        self.assertIsNone(result)
+
+    def test_resolves_entity_set_from_schema_name(self):
+        """_update delegates entity set resolution to _entity_set_from_schema_name."""
+        self.od._update("new_ticket", "00000000-0000-0000-0000-000000000001", {"new_status": 1})
+        self.od._entity_set_from_schema_name.assert_called_once_with("new_ticket")
+
+
 class TestUpsert(unittest.TestCase):
     """Unit tests for _ODataClient._upsert."""
 
@@ -335,6 +485,45 @@ def test_record_keys_lowercased(self):
         self.assertIn("name", payload)
         self.assertNotIn("Name", payload)
 
+    def test_odata_bind_keys_preserve_case(self):
+        """@odata.bind keys must preserve PascalCase for navigation property."""
+        self.od._upsert(
+            "accounts",
+            "account",
+            {"accountnumber": "ACC-001"},
+            {
+                "Name": "Contoso",
+                "new_CustomerId@odata.bind": "/contacts(00000000-0000-0000-0000-000000000001)",
+            },
+        )
+        call = self._patch_call()
+        payload = call.kwargs["json"]
+        # Regular field is lowercased
+        self.assertIn("name", payload)
+        # @odata.bind key preserves original casing
+        self.assertIn("new_CustomerId@odata.bind", payload)
+        self.assertNotIn("new_customerid@odata.bind", payload)
+
+    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"})