Dataverse Schema & Data Management

Dataverse Schema & Data Management

Overview

Microsoft Dataverse exposes a rich metadata Web API that lets you define, modify, and delete schema objects — tables (entities), columns (attributes), relationships, and option sets — entirely through HTTP requests. This skill provides the knowledge needed to generate correct API payloads, design sound schemas, manage solutions, seed data, and build queries.

All operations target the Dataverse Web API v9.2 endpoint:

{environmentUrl}/api/data/v9.2/

Where {environmentUrl} is the root URL of the Power Platform environment (e.g., https://org12345.crm.dynamics.com).

Metadata API Surface

EntityDefinitions (Tables)

Tables are defined and managed through the EntityDefinitions endpoint.

AttributeMetadata (Columns)

Columns are managed as sub-resources of their parent table.

RelationshipDefinitions (Relationships)

Table Creation Quick Reference

When creating a table, the key properties are:

The PrimaryNameAttribute is a string column that is created inline with the table. You must include its full StringAttributeMetadata definition in the Attributes array of the POST body.

Minimal creation body:

{
  "@odata.type": "Microsoft.Dynamics.CRM.EntityMetadata",
  "SchemaName": "cr123_ProjectTask",
  "DisplayName": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [{ "Label": "Project Task", "LanguageCode": 1033 }]
  },
  "DisplayCollectionName": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [{ "Label": "Project Tasks", "LanguageCode": 1033 }]
  },
  "Description": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [{ "Label": "Tracks tasks within a project", "LanguageCode": 1033 }]
  },
  "OwnershipType": "UserOwned",
  "PrimaryNameAttribute": "cr123_name",
  "Attributes": [
    {
      "@odata.type": "Microsoft.Dynamics.CRM.StringAttributeMetadata",
      "SchemaName": "cr123_Name",
      "DisplayName": {
        "@odata.type": "Microsoft.Dynamics.CRM.Label",
        "LocalizedLabels": [{ "Label": "Name", "LanguageCode": 1033 }]
      },
      "IsPrimaryName": true,
      "MaxLength": 200,
      "FormatName": { "Value": "Text" },
      "RequiredLevel": { "Value": "ApplicationRequired" }
    }
  ]
}

Solution context: To create the table within a solution, add the header:

MSCRM.SolutionUniqueName: YourSolutionUniqueName

Column Type Decision Tree

Use this guide to pick the right column type:

Relationship Types Summary

One-to-Many (1:N)

• Creates a lookup column on the "many" side automatically
• Best for: parent-child hierarchies, foreign-key patterns
• Configure cascading behavior for Assign, Delete, Merge, Reparent, Share, Unshare

Many-to-Many (N:N)

• Creates an intersect table automatically
• No lookup column on either side; association/disassociation via API
• Best for: tags, categories, peer relationships
• Limited cascading options compared to 1:N

Trade-off: Prefer 1:N when one side clearly "owns" the relationship. Use N:N when both sides are equal peers and no additional attributes are needed on the junction. If you need attributes on the junction, create a custom intersect table with two 1:N relationships instead of using native N:N.

Publisher Prefix Conventions

Every schema object in Dataverse must include the publisher prefix:

• SchemaName format: prefix_EntityName, e.g., cr123_ProjectTask
• Logical name (auto-generated): all-lowercase version, e.g., cr123_projecttask
• The prefix is set on the Publisher record associated with the solution
• Common prefixes: 2-5 lowercase letters/numbers (avoid new_ as it is the default)

Rule: Always apply the publisher prefix to every SchemaName for tables, columns, relationships, and option sets. Never create schema objects without the correct prefix.

Naming Conventions

Enforce these conventions across all generated schema:

• No spaces in schema names (use PascalCase)
• Descriptions should be meaningful and complete sentences
• Display names should be user-friendly with proper casing and spaces

Solution-Aware Development

Default behavior: Always work within a solution context.

When generating API calls:

1. Ask for (or assume) the solution unique name
2. Include the MSCRM.SolutionUniqueName header on all create operations
3. For existing components, use AddSolutionComponent action to add them to the solution
4. Track which components are in the solution for export

Solution-aware operations ensure components are properly packaged for deployment across environments (dev, test, production).

Dataverse Limits

Be aware of these platform limits:

Reference Files

Example Files