dataverse-schema-generator

name

dataverse-schema-generator

description

Automatically generates comprehensive markdown schema documentation for Dataverse solutions imported in the dataversesolutions folder. Parses Entity.xml and OptionSet XML files to create structured documentation with entity details, field tables, option sets, relationships, and Business Central integration notes. Use when the user requests to generate, create, or update schema documentation for Dataverse solutions, or mentions documenting imported solutions, entity schemas, or field structures. Trigger phrases include "generate schema documentation", "document the [solution] schema", "create schema docs for [solution]", or when working with imported Dataverse solutions that need documentation for AL development or team reference.

Dataverse Schema Documentation Generator

Overview

Generates comprehensive schema documentation for Dataverse solutions by parsing XML metadata from extracted solution folders. Creates standardized markdown documentation following the CustomerCentricSolution-Schema.md template structure.

Quick Start

Basic usage:

cd .github\skills\dataverse-schema-generator
.\Generate-Schema-Documentation.ps1 -SolutionName "CustomerCentricSolution"

With custom parameters:

.\Generate-Schema-Documentation.ps1 `
    -SolutionName "MySolution" `
    -Prefix "ms_" `
    -Overview "Custom solution description"

Output location: dataversesolutions/Documentation/{SolutionName}-Schema.md

Prerequisites

Required folder structure:

• Solution extracted in dataversesolutions/{SolutionName}/
• Entities/ folder with Entity.xml files in entity subfolders
• Optional: OptionSets/ folder with global option set XML files

Core Workflow

The script performs these steps automatically:

1. Solution Selection

   • If no solution name provided, prompts user to select from available solutions
   • Validates solution folder exists and contains Entities folder

2. Parse Entity Metadata

   • Reads all Entity.xml files from solution
   • Extracts: logical name, display name, description, primary key
   • Parses all fields: name, type, length, required level, descriptions
   • Identifies custom fields (with solution prefix) vs standard fields

3. Parse Option Sets

   • Reads global option set XML files
   • Extracts option values and labels
   • Links to fields using the option sets

4. Detect Solution Prefix

   • Auto-detects common prefix from custom entity names
   • User can override with -Prefix parameter

5. Generate Markdown Documentation

   • Creates structured documentation with:
     • Header (prefix, version, date)
     • Table of contents
     • Custom entities section with field tables
     • Extended standard entities
     • Global option sets
     • Component summary
     • Integration notes for BC development

6. Save Output

   • Writes to dataversesolutions/Documentation/{SolutionName}-Schema.md
   • Reports summary statistics

Script Reference

The skill uses Generate-Schema-Documentation.ps1 with these key functions:

• Parse-EntityXml: Parses Entity.xml files to extract metadata
• Parse-OptionSetXml: Parses option set XML files
• Get-SolutionPrefix: Auto-detects solution prefix from entity names
• Generate-EntitySection: Creates markdown tables for entities
• Generate-OptionSetSection: Creates markdown for option sets
• Format-FieldType: Converts Dataverse types to readable names
• Format-RequiredLevel: Converts requirement levels to friendly text

Script parameters:

-SolutionName <string>     # Solution folder name (required or interactive)
-OutputPath <string>       # Custom output file path (optional)
-Prefix <string>           # Solution prefix override (optional)
-Overview <string>         # Custom solution description (optional)

For detailed script implementation, see Generate-Schema-Documentation.ps1 in this folder.

Generated Documentation Structure

The output markdown file includes:

1. Header Section

   • Solution name, prefix, version, last updated date
   • Overview text (auto-generated or user-provided)

2. Table of Contents

   • Links to all major sections
   • Custom entities list
   • Extended entities list
   • Global option sets list

3. Custom Entities

   • Each entity gets a numbered section with:
     • Logical name, display name, description
     • Primary key field
     • Custom fields table (name, type, display name, max length, required, description)
     • Standard fields list (if applicable)
     • Key characteristics

4. Extended Standard Entities

   • Shows custom fields added to standard Dataverse entities (Account, Contact, etc.)
   • Same field table format as custom entities

5. Global Option Sets

   • Name, display name, description
   • Option values table with value and label
   • Usage information

6. Supporting Sections

   • Field naming conventions
   • Solution components summary table
   • Integration notes for Business Central
   • Version history
   • Additional resources (file locations)

Example output: See dataversesolutions/Documentation/CustomerCentricSolution-Schema.md

Usage Examples

Interactive Mode

.\Generate-Schema-Documentation.ps1
# Prompts for solution selection from available options

Direct Execution

.\Generate-Schema-Documentation.ps1 -SolutionName "CustomerCentricSolution"

With Copilot

User request: "Generate schema documentation for CustomerCentricSolution"

Copilot will:

1. Navigate to skill folder
2. Execute script with solution name
3. Open generated documentation file
4. Confirm successful generation with statistics

Batch Processing

# Document all solutions
Get-ChildItem "../../../dataversesolutions" -Directory |
    Where-Object { $_.Name -notmatch "Documentation|ZIPFiles" } |
    ForEach-Object { .\Generate-Schema-Documentation.ps1 -SolutionName $_.Name }

For additional examples, see EXAMPLES.md in this folder (13 detailed scenarios).

Integration with Other Skills

Works with dataverse-solution-importer:

• After importing: automatically generate documentation
• Workflow: Import → Extract → Document

Supports bc-dataverse-entity-generator:

• Documentation provides field metadata for AL table generation
• Entity structure, types, and relationships inform code generation

Complements bc-tooltip-manager:

• Field descriptions from docs can guide tooltip creation

Error Handling

The script gracefully handles:

• Missing solution folders → Prompts for selection
• Invalid XML files → Logs warning, continues processing
• Missing metadata → Uses placeholders with warnings
• Prefix detection failure → Uses default or prompts user

Best Practices

1. Generate after import: Create docs immediately when solution is extracted
2. Version control: Commit documentation with solution files
3. Review and enhance: Add business context to auto-generated descriptions
4. Regenerate on changes: Update docs when schema changes
5. Reference before coding: Use docs when generating AL code

Additional Resources

• README.md - Quick start guide and troubleshooting
• EXAMPLES.md - 13 detailed usage scenarios
• QUICKREF.md - One-page reference with commands and tips
• WORKFLOW.md - Visual diagrams and architecture
• Generate-Schema-Documentation.ps1 - Main PowerShell script (~800 lines)

Limitations

• Processes only extracted XML files (not ZIPs directly)
• Requires standard Dataverse XML structure
• Relationship details may need manual enhancement
• Does not parse business rules or workflows
• Embedded local option sets need verification

---

This skill follows the AI Native-Instructions Architecture for systematic documentation generation.