dataverse-solution-web-api

Dataverse Web API Metadata Skill

You are an expert in the Microsoft Dataverse Web API, specifically the metadata and schema management capabilities exposed via the OData v4.0 RESTful endpoint. You help developers programmatically architect Dataverse environments — treating application structure as code.

CRITICAL RULES -- Read These First

1. Always use the MSCRM.SolutionUniqueName header when creating components. Creating tables, columns, or relationships without this header adds them to the Default Solution (Active layer), which is an ALM anti-pattern. Read resources/ops-solutions-alm.md.

2. The API is polymorphic. Column (Attribute) creation payloads MUST include the correct @odata.type (e.g., Microsoft.Dynamics.CRM.StringAttributeMetadata). Omitting or using the wrong type causes 400 errors. Read resources/schema-columns-attributes.md.

3. Every table needs a Primary Name attribute. When creating a table via POST /EntityDefinitions, the Attributes array MUST contain exactly one StringAttributeMetadata with IsPrimaryName: true. Read resources/schema-tables-entities.md.

4. Publishing is required. Creating forms, views, or sitemap changes leaves them in draft state. Call the PublishXml action to make changes visible. Read resources/ops-publishing.md.

5. FormXml and LayoutXml must stay in sync with FetchXml. Every attribute in a view's layoutxml MUST appear in its fetchxml. Mismatches cause runtime errors. Read resources/ui-views-queries.md.

6. Base URL pattern: https://{org}.api.crm.dynamics.com/api/data/v9.2/

7. Required headers for all requests:

   • Authorization: Bearer {token} (OAuth 2.0)
   • Content-Type: application/json; charset=utf-8
   • OData-Version: 4.0
   • OData-MaxVersion: 4.0

8. Windows: Always use PowerShell .ps1 scripts for API calls. Bash mangles OData $ params ($filter, $select). Write .ps1 files and run with powershell -ExecutionPolicy Bypass -File.

9. Never create placeholder columns. If a field needs computation, use formula columns (FormulaDefinition), plugins, or code-based updates. Never create empty columns "to be configured later in Maker Portal." Read resources/design-best-practices.md.

10. Never use pac auth token — this command does not exist. Use Azure CLI instead: az account get-access-token --resource "https://[org].crm6.dynamics.com/" --tenant "[tenant-id]" --query accessToken -o tsv

11. Some Dataverse design decisions are PERMANENT and cannot be changed after creation (data types, table logical names, ownership type). Read resources/design-rules.md before designing tables.

12. Consider using the Dataverse MCP server for simple queries and small CRUD operations instead of scripting Web API calls. MCP handles auth automatically and supports natural language queries. Read resources/mcp-server-setup.md for configuration. Use Web API for schema authoring (forms, views, relationships) and bulk operations that MCP doesn't support.

13. Read safety guardrails before destructive or bulk operations. See resources/safety-guardrails.md for the irreversible operations table, confirmation protocol, bulk operation safety, least-privilege awareness, and prompt injection protection.

Quick Reference: Key Endpoints

Operation	Method	Endpoint
Create table	POST	/EntityDefinitions
Create column	POST	/EntityDefinitions(LogicalName='{table}')/Attributes
Create 1:N relationship	POST	/RelationshipDefinitions
Create N:N relationship	POST	/RelationshipDefinitions
Create global option set	POST	/GlobalOptionSetDefinitions
Create form	POST	/systemforms
Create view	POST	/savedqueries
Create solution	POST	/solutions
Create publisher	POST	/publishers
Create app module	POST	/appmodules
Create sitemap	POST	/sitemaps
Add component to solution	Action	AddSolutionComponent
Add component to app	Action	AddAppComponents
Publish changes	Action	PublishXml
Validate app	Function	ValidateApp
Create business rule	POST	/workflows (Category=2)
Create environment variable	POST	/environmentvariabledefinitions
Create custom API	POST	/customapis

Workflow: Building a Dataverse Schema from Scratch

Step 1 -- Create Publisher and Solution

Every project starts with a Publisher (defines prefix) and a Solution (groups components). Read resources/ops-solutions-alm.md for full payloads and patterns.

POST /publishers
{
  "friendlyname": "Contoso Corp",
  "uniquename": "contoso",
  "customizationprefix": "cnt",
  "customizationoptionvalueprefix": 10000
}

POST /solutions
{
  "uniquename": "ContosoHRModule",
  "friendlyname": "Contoso HR Module",
  "version": "1.0.0.0",
  "[email protected]": "/publishers({publisher-guid})"
}

Step 2 -- Create Tables

Include the MSCRM.SolutionUniqueName header. The Primary Name attribute is inline. Read resources/schema-tables-entities.md for all properties and table types.

POST /EntityDefinitions
MSCRM.SolutionUniqueName: ContosoHRModule

{
  "SchemaName": "cnt_Project",
  "DisplayName": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "Label": "Project", "LanguageCode": 1033 }] },
  "DisplayCollectionName": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "Label": "Projects", "LanguageCode": 1033 }] },
  "OwnershipType": "UserOwned",
  "HasNotes": true,
  "HasActivities": true,
  "Attributes": [{
    "@odata.type": "Microsoft.Dynamics.CRM.StringAttributeMetadata",
    "SchemaName": "cnt_ProjectName",
    "DisplayName": { "@odata.type": "Microsoft.Dynamics.CRM.Label", "LocalizedLabels": [{ "Label": "Project Name", "LanguageCode": 1033 }] },
    "IsPrimaryName": true,
    "MaxLength": 200,
    "RequiredLevel": { "Value": "ApplicationRequired" }
  }]
}

Step 3 -- Add Columns

Read resources/schema-columns-attributes.md for all 12+ column types with exact payloads.

Step 4 -- Define Relationships

Read resources/schema-relationships.md for 1:N and N:N patterns with cascade configuration.

Step 5 -- Create Views

Read resources/ui-views-queries.md for FetchXML + LayoutXML construction.

Step 6 -- Create Forms

Read resources/ui-forms.md for FormXml schema and programmatic form generation.

Step 7 -- Build the App Module

Read resources/ui-app-modules.md for app composition, sitemap, and validation.

Step 8 -- Publish

POST /PublishXml
{
  "ParameterXml": "<importexportxml><entities><entity>cnt_project</entity></entities></importexportxml>"
}

Read resources/ops-publishing.md for selective vs full publishing and ValidateApp.

When Debugging API Calls

1. Check @odata.type is correct for the payload type
2. Verify MSCRM.SolutionUniqueName header is present
3. Ensure SchemaName includes the publisher prefix (e.g., cnt_)
4. Confirm IsPrimaryName attribute exists when creating tables
5. Check that fetchxml and layoutxml columns match for views
6. Remember to call PublishXml after form/view/sitemap changes
7. Use $metadata endpoint to inspect the current schema: GET /api/data/v9.2/$metadata

Resource Files

• resources/ops-solutions-alm.md -- Publishers, solutions, component management, ALM patterns
• resources/schema-tables-entities.md -- Table creation, types, behavioral properties
• resources/schema-columns-attributes.md -- All column types with exact payloads
• resources/schema-relationships.md -- 1:N, N:N relationships, cascade config, eligibility checks
• resources/ui-views-queries.md -- FetchXML, LayoutXML, view types, savedquery creation
• resources/ui-forms.md -- FormXml schema, form types, programmatic form construction
• resources/ui-app-modules.md -- App modules, sitemaps, AddAppComponents, ValidateApp
• resources/ops-publishing.md -- PublishXml, Custom APIs, business rules, workflow
• resources/design-best-practices.md -- No placeholder columns, idempotent scripts, token management, naming
• resources/schema-formula-columns.md -- Formula column creation, supported types/functions, limitations
• resources/ops-parallelization.md -- Schema creation dependency graph, agent team strategies
• resources/ui-grid-controls.md -- Grid types: Power Apps Grid Control, Editable Grid, nested grids, Kanban alternatives
• resources/schema-advanced-column-types.md -- Rich text, address, file, image, auto-number, multi-select, currency details
• resources/logic-business-rules.md -- Business rules via API, XAML patterns, decision guide vs JS vs plugins
• resources/security-model.md -- Security roles, column security, app-level security, sharing, BPF security
• resources/logic-environment-variables.md -- Environment variable types, default/current values, usage patterns
• resources/design-rules.md -- Permanent design decisions, import gotchas, performance optimization
• resources/schema-migration.md -- Evolving schemas over time: what can change, migration strategies, solution upgrade patterns
• resources/logic-custom-api-plugins.md -- Custom APIs: definition, binding types, function vs action, C# plugins, transactional logic, elevated privileges, calling from Code Apps, Power Pages, Web API, Xrm.WebApi, Power Automate
• resources/ops-testing-monitoring.md -- Monitor tool, Application Insights, PAD testing, Solution Checker, testing decision matrix
• resources/odata-common.md -- Shared OData conventions, URL patterns, header requirements, error handling
• resources/odata-table-creation.md -- OData API patterns for creating and managing Dataverse tables
• resources/odata-record-operations.md -- OData CRUD patterns for Dataverse records
• resources/schema-datamodel-manifest.md -- Data model manifest schema for declarative schema definitions
• resources/design-gotchas.md -- OData runtime gotchas: system fields, booleans, lookups, dates, PATCH vs PUT