Refine nav property language: match $metadata, not SchemaName

Use "navigation property name (case-sensitive, must match $metadata)"
instead of "PascalCase SchemaName" per review feedback. System lookups
like parentaccountid are lowercase, so "PascalCase" was imprecise.

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

Author: suyask-msft

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

@@ -26,8 +26,10 @@ Dataverse uses two different naming conventions for properties. Getting this wro
 
 | 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 |
+| **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...`
 

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

@@ -108,7 +108,7 @@ for page in client.records.get(
 #### 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
+# 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})",
@@ -373,7 +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.
+- 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 and emits a warning if it detects likely-wrong lowercase casing on custom lookups.
 
 ## Best Practices
 
@@ -386,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 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`)
+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

@@ -108,7 +108,7 @@ for page in client.records.get(
 #### 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
+# 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})",
@@ -373,7 +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.
+- 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 and emits a warning if it detects likely-wrong lowercase casing on custom lookups.
 
 ## Best Practices
 
@@ -386,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 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`)
+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

@@ -100,7 +100,7 @@ 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).  The OData
+        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.
@@ -112,13 +112,14 @@ def _lowercase_keys(record: Dict[str, Any]) -> Dict[str, Any]:
                 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.
+                    # Custom lookup navigation properties use PascalCase
+                    # (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"navigation property name. Navigation property names "
+                        f"are case-sensitive and must match the entity's "
+                        f"$metadata (e.g. 'new_CustomerId@odata.bind', not "
+                        f"'new_customerid@odata.bind'). This will likely "
                         f"cause a 400 error.",
                         stacklevel=4,
                     )

tests/unit/data/test_odata_internal.py

@@ -371,7 +371,7 @@ def test_odata_bind_lowercase_warns(self):
             )
             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))
+            self.assertIn("case-sensitive", str(odata_warnings[0].message))
 
     def test_odata_bind_pascalcase_no_warning(self):
         """PascalCase @odata.bind nav property does NOT emit a warning."""