Dataverse SDK Development Guide

Overview

This skill provides guidance for developers working on the PowerPlatform Dataverse Client Python SDK repository itself (not using the SDK).

Best Practices

API Design

1. Public methods in operation namespaces - New public methods go in the appropriate namespace module under src/PowerPlatform/Dataverse/operations/ (records.py, query.py, tables.py, batch.py). The client.py file exposes these via namespace properties (client.records, client.query, client.tables, client.batch). Public types and constants live in their own modules (e.g., models/metadata.py, models/batch.py, common/constants.py)
2. Every public method needs README example - Public API methods must have examples in README.md
3. Reuse existing APIs - Always check if an existing method can be used before making direct Web API calls
4. Update documentation when adding features - Keep README and SKILL files (both copies) in sync
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
7. Async client - The SDK ships a full async client (AsyncDataverseClient) under src/PowerPlatform/Dataverse/aio/. When adding a feature to the sync client, add it to the async client too. The async operation namespaces mirror the sync ones: aio/operations/async_records.py, async_query.py, async_tables.py, async_batch.py, async_files.py. Pure logic (payload builders, URL construction) goes in data/_odata_base.py — inherited by both _ODataClient and _AsyncODataClient — so it only needs to be written once; HTTP-calling code goes in data/_odata.py (sync) or aio/data/_async_odata.py (async). Async tests live in tests/unit/aio/ and async examples in examples/aio/. The aiohttp dependency is an optional extra (pip install "PowerPlatform-Dataverse-Client[async]") — do not move it into the required dependencies list in pyproject.toml.

Dataverse Property Naming Rules