Lab 09: AI metadata

At a glance

Time

About 35 minutes

Level

intermediate

Platforms

Windows 11, macOS (file mode, no Desktop)

Copilot surfaces

VS Code, Power BI Desktop

You'll use

skill, prompt-file, instructions

Starts from

lab08-complete: Adds relationships, the marked date table, Fill Type, and the core measures.

Ends at

lab09-complete: Adds AI metadata: Q&A on, default labels, and the fabric/ai-prep drafts.

Last verified

Not yet run end to end on Windows 11

Works on macOS

Nobody has run this lab end to end on Windows 11 yet. The steps follow the current docs for each tool, but menu labels may differ. The verify command at the end is the source of truth, and feedback is welcome.

Why this matters

Copilot, Q&A, and Fabric data agents don’t only read table names. They also need business rules that don’t fit cleanly in a measure description. Prep data for AI gives you a place to define those rules, narrow the schema, add synonyms, and map verified answers to approved visuals. In this repo, the Power BI-managed files for those features are treated as preview output, so you draft the content as plain text first and apply it later in Power BI Desktop or the Power BI service.

Concepts

• Prep data for AI: a Power BI authoring experience for AI instructions, AI data schemas, and verified answers. Microsoft Learn marks the experience as preview, and the exact Desktop and service UI can move between monthly releases.
• AI instructions: model-level business guidance. This is where you define latest month, previous period, refill thresholds, and processing time. See AI readiness.
• AI data schema: the subset of model objects that AI tools should use for question answering. It reduces noisy choices.
• Synonyms: alternate phrases on tables, columns, and measures. In this lab they stay in fabric/ai-prep/synonyms.yaml until a person applies them in Power BI.
• Verified answers: reviewed answer candidates that map a business question to a visual and trigger phrases.

Preview disclaimer

The Microsoft Learn article Prepare Your Data for AI to Improve Copilot Results says authors can now use Prep data for AI in both Power BI Desktop and the Power BI service. It is still labeled preview. These labs keep drafts in fabric/ai-prep/ because preview file formats can change.

Before you begin

• You finished Lab 08. The model has relationships, a marked Date table, the 12 core measures, and Fill Type.
• evaluation/runs/local-baseline.json exists from Lab 05, and out/assessment.md exists from Lab 06.
• You are on a feature branch, usually feature/ai-ready-names.
• Power BI Desktop can be closed. The required work in this lab is text-first and works on macOS file mode.

Skipped a lab or want a clean start?

Restore the lab08-complete checkpoint (Adds relationships, the marked date table, Fill Type, and the core measures). The script refuses to run if you have uncommitted changes, creates a new lab/lab08-complete-... branch, and restores only fabric/ and lab/samples/. Close Power BI Desktop first.

pwsh ./scripts/lab/Restore-LabCheckpoint.ps1 -Checkpoint lab08-complete

It needs the upstream remote from Lab 01, step 3.

Steps

Step 1. Read the AI prep contract

Open these files in VS Code before you run the agent:

1. Open Quick Open: Ctrl+P (macOS: Cmd+P), or Go > Go to File.
2. Open .github/skills/prep-data-for-ai/SKILL.md.
3. Open .github/prompts/write-ai-prep-drafts.prompt.md.
4. Open rules/required-model-objects.yaml.

The skill explains why the repo drafts the content instead of writing Desktop’s preview folder directly:

.github/skills/prep-data-for-ai/SKILL.md (lines 7-16)

Power BI Copilot and Fabric data agents read a semantic model's metadata plus three kinds of AI prep: **AI instructions**, an **AI data schema** (which objects AI may use), and **verified answers**. Power BI's supported way to apply them is the Prep data for AI dialog in Power BI Desktop, which writes its own files under `ContosoPharmacy.SemanticModel/Copilot/`.

So this skill writes **drafts** in `fabric/ai-prep/` that a person reviews in the pull request and then applies in Desktop.

## Hard rules

- Write only in `fabric/ai-prep/`. Never create or edit anything under `*.SemanticModel/Copilot/`. The repo's hooks deny it.
- Every name you write must exist in the model. Read the TMDL (or use Power BI Modeling MCP `model_operations`) first; don't work from memory.
- Business questions come from `pwsh ./scripts/Get-BusinessQuestions.ps1`. Don't open `evaluation/expected/`.
- Keep `ai-instructions.md` under 10,000 characters. Aim for 2,000 to 3,000; shorter instructions are followed more reliably.

View .github/skills/prep-data-for-ai/SKILL.md on GitHub

The prompt names the five files and the two model flags:

.github/prompts/write-ai-prep-drafts.prompt.md (lines 6-14)

Draft the Prep data for AI files for the Contoso Pharmacy model. Use the `prep-data-for-ai` skill and follow its hard rules.

1. Read the current model so every name you write exists.
2. Get the business questions with `pwsh ./scripts/Get-BusinessQuestions.ps1`.
3. Write the five files in `fabric/ai-prep/`: `README.md`, `ai-instructions.md`, `ai-data-schema.yaml`, `synonyms.yaml`, `verified-answers.yaml`.
4. Set `"qnaEnabled": true` in `definition.pbism`, and `isDefaultLabel` on `'Store'[Store Name]` and `'Medication'[Medication Name]`.
5. Run `pwsh ./scripts/lab/Test-LabProgress.ps1 -Lab 09` and fix anything it reports.

Don't create or edit anything under `ContosoPharmacy.SemanticModel/Copilot/`. End with the Desktop steps a person follows to apply the drafts.

View .github/prompts/write-ai-prep-drafts.prompt.md on GitHub

You should see: the skill says to write only in fabric/ai-prep/, never in ContosoPharmacy.SemanticModel/Copilot/. The rules file says rule C14 expects Q&A enabled plus default labels on Store Name and Medication Name.

I finished step 1

Step 2. Draft the five AI prep files

Run the prompt with the model-improver agent.

1. Open Copilot Chat: Ctrl+Alt+I (macOS: Ctrl+Cmd+I), or View > Chat.
2. Pick model-improver from the agent dropdown.
3. Type /write-ai-prep-drafts and press Enter.
4. Approve read, edit, and validation commands after you inspect them.

The prompt writes exactly these files:

rules/required-model-objects.yaml (lines 40-51)

ai_prep:
  folder: fabric/ai-prep
  files: [README.md, ai-instructions.md, ai-data-schema.yaml, synonyms.yaml, verified-answers.yaml]
  instructions_max_chars: 10000
  instructions_must_mention: [December 2025, previous month, Refill Rate Index vs Chain, "1.25", Avg Processing Time (min), Therapeutic Category]
  synonyms_required_for:
    - "Prescription Fill[Prescriptions Filled]"
    - "Prescription Fill[Avg Processing Time (min)]"
    - "Medication[Therapeutic Category]"
    - "Store[Region]"
  min_verified_answers: 5
  qna_enabled: true

View rules/required-model-objects.yaml on GitHub

You should see: a new fabric/ai-prep/ folder with README.md, ai-instructions.md, ai-data-schema.yaml, synonyms.yaml, and verified-answers.yaml. You should not see a new ContosoPharmacy.SemanticModel/Copilot/ folder.

What varies between runs

Copilot's wording, the order it works in, and the exact DAX or TMDL it writes will differ from what you see here and from your neighbor's run. That's expected.

The agent may draft short files first, run the lab check, then fill gaps reported by the check.

These must match:

• The folder is fabric/ai-prep
• All five draft files exist
• No Copilot folder is created under the semantic model

I finished step 2

Step 3. Review the AI instructions

Open fabric/ai-prep/ai-instructions.md and check the rules that make ambiguous questions answerable.

1. Open Quick Open: Ctrl+P (macOS: Cmd+P), or Go > Go to File.
2. Open fabric/ai-prep/ai-instructions.md.
3. Confirm it is under 10,000 characters. In VS Code, use Ctrl+Shift+P (macOS: Cmd+Shift+P) > File: Save As only if you need to copy it elsewhere. Otherwise, use the status bar character count if your version shows it, or run the command below.

Windows

(Get-Content -Raw fabric/ai-prep/ai-instructions.md).Length

macOS

python3 - <<'PY'
from pathlib import Path
print(len(Path('fabric/ai-prep/ai-instructions.md').read_text(encoding='utf-8')))
PY

The skill names the required definitions:

.github/skills/prep-data-for-ai/SKILL.md (lines 30-40)

## What the AI instructions must settle

These are the ambiguities that make baseline answers wrong. Settle each one in a sentence:

1. **The latest period.** The data runs January 2024 to December 2025, so the latest complete month is December 2025 and the latest quarter is 2025-Q4.
2. **"Previous period"** means the previous month unless the user says otherwise. Name the measures: `[MoM Change]`, `[MoM %]`, and `[YoY %]`.
3. **Metric routing.** "Prescriptions filled", "fills", and "scripts" mean `[Prescriptions Filled]`. Processing time means `[Avg Processing Time (min)]` (an average; never sum minutes).
4. **"Unusually high refill activity"** means `[Refill Rate Index vs Chain]` of 1.25 or more, for the latest quarter unless a period is named.
5. **Medication category** means `'Medication'[Therapeutic Category]`.
6. **Time grouping** uses the `Date` table (`'Date'[Year Month]`), never the fact table's own date column.
7. **Presentation.** Show stores by Store Name, and state the period in every answer.

View .github/skills/prep-data-for-ai/SKILL.md on GitHub

You should see: sentences that define December 2025 as the latest complete month, previous period as the previous month by default, unusually high refill activity as [Refill Rate Index vs Chain] of 1.25 or more, and processing time as [Avg Processing Time (min)].

I finished step 3

Step 4. Review synonyms where the skill says they go

Synonyms stay in the draft file for review. They do not go into a Copilot/ folder in this lab.

1. Open fabric/ai-prep/synonyms.yaml.
2. Check the tables, columns, and measures maps.
3. Confirm the required keys from the skill are present.

.github/skills/prep-data-for-ai/references/formats.md (lines 42-59)

## synonyms.yaml

Three maps. Table keys are table names. Column and measure keys are `Table[Object]`, without quotes. Values are lists of lowercase phrases people actually use.

```yaml
tables:
  Store: [pharmacy, location, branch]
columns:
  Store[Region]: [area, territory]
  Medication[Therapeutic Category]: [drug category, medication category, therapeutic class]
measures:
  Prescription Fill[Prescriptions Filled]: [fills, prescription volume, scripts filled]
  Prescription Fill[Avg Processing Time (min)]: [processing time, turnaround time, wait time]
```

The lab check requires at least these four keys: `Prescription Fill[Prescriptions Filled]`, `Prescription Fill[Avg Processing Time (min)]`, `Medication[Therapeutic Category]`, and `Store[Region]`.

Avoid a synonym that could mean two objects. "Volume" alone is ambiguous between fills and refills, so prefer "prescription volume".

View .github/skills/prep-data-for-ai/references/formats.md on GitHub

You should see: synonyms for Prescription Fill[Prescriptions Filled], Prescription Fill[Avg Processing Time (min)], Medication[Therapeutic Category], and Store[Region]. Phrases should be business terms like “scripts filled”, “turnaround time”, “drug category”, and “territory”.

I finished step 4

Step 5. Review verified answer candidates

Verified answers connect important phrases to approved visuals. The drafts are reviewable YAML because a human still applies them in Power BI.

1. Open fabric/ai-prep/verified-answers.yaml.
2. Confirm it has one candidate for each question ID, Q01 to Q05.
3. For each candidate, check that visual names the visual to build and phrases contains the original question plus at least one paraphrase.

.github/skills/prep-data-for-ai/references/formats.md (lines 61-74)

## verified-answers.yaml

One candidate per business question. `visual` describes what the person builds in the report; `phrases` are the trigger phrases they add when setting up the verified answer. Include the original question and at least one paraphrase.

```yaml
candidates:
  - question_id: Q03
    visual: Table, 'Store'[Store Name] and [Avg Processing Time (min)], sorted descending
    phrases:
      - What was the average prescription processing time by store?
      - Which stores are slowest to process prescriptions?
```

Get question IDs and wording from `pwsh ./scripts/Get-BusinessQuestions.ps1`.

View .github/skills/prep-data-for-ai/references/formats.md on GitHub

You should see: at least five candidates with phrases. Each question from pwsh ./scripts/Get-BusinessQuestions.ps1 has a candidate.

I finished step 5

Step 6. Confirm Q&A and default labels

The drafts alone don’t satisfy the model checks. The model also needs Q&A enabled and default labels for the two entity tables.

1. Open fabric/ContosoPharmacy.SemanticModel/definition.pbism.
2. Confirm settings.qnaEnabled is true.
3. Open the Store and Medication TMDL files.
4. Confirm Store Name and Medication Name have isDefaultLabel.
5. Run the lab check.

Windows

pwsh ./scripts/lab/Test-LabProgress.ps1 -Lab 09

macOS

pwsh ./scripts/lab/Test-LabProgress.ps1 -Lab 09

The rule source lists the default labels:

rules/required-model-objects.yaml (lines 36-51)

default_labels:
  Store: Store Name
  Medication: Medication Name

ai_prep:
  folder: fabric/ai-prep
  files: [README.md, ai-instructions.md, ai-data-schema.yaml, synonyms.yaml, verified-answers.yaml]
  instructions_max_chars: 10000
  instructions_must_mention: [December 2025, previous month, Refill Rate Index vs Chain, "1.25", Avg Processing Time (min), Therapeutic Category]
  synonyms_required_for:
    - "Prescription Fill[Prescriptions Filled]"
    - "Prescription Fill[Avg Processing Time (min)]"
    - "Medication[Therapeutic Category]"
    - "Store[Region]"
  min_verified_answers: 5
  qna_enabled: true

View rules/required-model-objects.yaml on GitHub

You should see: all Lab 09 checks pass, including L09-model-flags. If it fails with C14, ask model-improver to set the default labels without changing any names.

I finished step 6

Step 7. Apply the drafts in Power BI when the UI is available

Windows only Preview feature

This step is version dependent. If your Power BI Desktop build shows Prep data for AI, you can apply the drafts now. If it doesn’t, keep the drafts in the PR and apply them later in the service.

1. Open fabric\ContosoPharmacy.pbip in Power BI Desktop.
2. Select Home > Prep data for AI. If you don’t see it, select File > Options and settings > Options > Preview features and look for Prep data for AI. Restart Desktop if you enable it.
3. In the Prep data for AI dialog, paste the contents of fabric/ai-prep/ai-instructions.md into AI instructions.
4. Use the schema draft to include the recommended tables and exclude noisy fields.
5. Add synonyms in Model view > select object > Properties > Synonyms.
6. For verified answers, select the report visual, open More options (…) > Set up a verified answer, and paste the trigger phrases from verified-answers.yaml.

You should see: the Desktop dialog accepts the content, and Desktop writes its own preview files when you save. If the UI isn’t present, you still have the reviewable drafts and the model flags from step 6.

No Desktop?

Skip this step. Service-side Copilot and Fabric data agents are phase two for this lab path. See the roadmap for the tenant-connected version.

I finished step 7

Step 8. Commit the AI metadata drafts

Review only the expected files, then commit them.

Windows

git status --short
git add fabric/ai-prep fabric/ContosoPharmacy.SemanticModel
git commit -m "Add AI prep metadata drafts"

macOS

git status --short
git add fabric/ai-prep fabric/ContosoPharmacy.SemanticModel
git commit -m "Add AI prep metadata drafts"

You should see: a commit that includes fabric/ai-prep/, definition.pbism, and the two TMDL files with default labels. It should not include out/, evaluation/runs/local-*.json, or Desktop cache files.

I finished step 8

Verify your work

Run this from the repo root in a PowerShell 7 terminal (Terminal > New Terminal in VS Code):

Windows

pwsh ./scripts/lab/Test-LabProgress.ps1 -Lab 09

macOS

pwsh ./scripts/lab/Test-LabProgress.ps1 -Lab 09

Checks marked Windows only print SKIP on macOS. SKIP doesn't count as a failure.

When everything is done you should see:

Expected output

PASS  L09-ai-prep-files     fabric/ai-prep has all five draft files
PASS  L09-ai-instructions   AI instructions are under 10,000 characters and define the latest month, previous period, refill threshold, and processing time
PASS  L09-synonyms          Synonyms cover the key measures and columns
PASS  L09-verified-answers  At least 5 verified answer candidates, one per question
PASS  L09-model-flags       Q&A enabled and default labels set on Store Name and Medication Name (C14)

Lab 09: 5 of 5 checks passed.

Each FAIL line prints a hint and a link back to the step on this page that fixes it. The command exits with code 0 when every required check passes.

Check	What it looks at	If it fails
L09-ai-prep-files	fabric/ai-prep has all five draft files	Run /write-ai-prep-drafts. Go to step 2
L09-ai-instructions	AI instructions are under 10,000 characters and define the latest month, previous period, refill threshold, and processing time	Edit fabric/ai-prep/ai-instructions.md; the check output lists what's missing. Go to step 3
L09-synonyms	Synonyms cover the key measures and columns	Add the missing keys to fabric/ai-prep/synonyms.yaml. Go to step 4
L09-verified-answers	At least 5 verified answer candidates, one per question	Add candidates to fabric/ai-prep/verified-answers.yaml. Go to step 5
L09-model-flags	Q&A enabled and default labels set on Store Name and Medication Name (C14)	Set qnaEnabled in definition.pbism and isDefaultLabel on the two name columns. Go to step 6

Troubleshooting

The agent created a semantic model Copilot folder

Reject that change. Run git restore -- fabric/ContosoPharmacy.SemanticModel/Copilot if the folder exists, then rerun /write-ai-prep-drafts and remind the agent: “Draft only in fabric/ai-prep. Do not create or edit the Desktop-managed Copilot folder.” The hook is designed to deny that edit in CLI and cloud agent, but VS Code agent behavior can vary by version.

The instructions check says a required term is missing

Open fabric/ai-prep/ai-instructions.md and add a short sentence for the missing concept. The check looks for the terms in rules/required-model-objects.yaml: December 2025, previous month, Refill Rate Index vs Chain, 1.25, Avg Processing Time (min), and Therapeutic Category.

The synonyms YAML doesn’t parse

YAML treats colons and brackets as structure. Keep keys unquoted only when they match the examples. If you get a parse error, quote the key, for example 'Prescription Fill[Prescriptions Filled]', and rerun pwsh ./scripts/lab/Test-LabProgress.ps1 -Lab 09.

Power BI Desktop doesn’t show Prep data for AI

The feature is preview and version dependent. Check File > Options and settings > Options > Preview features. If the option isn’t there, keep the drafts in fabric/ai-prep/ and apply them later in the Power BI service when your tenant has the feature.

Knowledge check

Where do the AI prep drafts belong in this repo?

fabric/ai-prep/, so they can be reviewed before a person applies them in Power BIContosoPharmacy.SemanticModel/Copilot/, because the agent should write Desktop preview files directlyevaluation/expected/, because the grader reads them

Show the answer

fabric/ai-prep/, so they can be reviewed before a person applies them in Power BI

The skill says drafts live in fabric/ai-prep/. Desktop or the service writes the preview Copilot files when a person applies the content.

Which statement belongs in AI instructions instead of a column description?

Processing Minutes stores the number of minutes between receipt and fill completion.Previous period means the previous month unless the user names another period.Store Name is the friendly display name for a pharmacy store.

Show the answer

Previous period means the previous month unless the user names another period.

Descriptions explain objects. AI instructions settle cross-model business rules and ambiguous wording.

What does rule C14 check?

The Date table is marked and auto date/time is off.Q&A is enabled and Store Name plus Medication Name are default labels.Every verified answer candidate has a screenshot.

Show the answer

Q&A is enabled and Store Name plus Medication Name are default labels.

The Lab 09 model flag check calls C14 after confirming qnaEnabled is true.

Recap and next

You drafted the AI metadata a Power BI author applies later: instructions, a schema, synonyms, and verified answer candidates. You also set model flags that are safe to store in TMDL now. The next lab tests whether those changes improve the business question answers.

Next: Lab 10: question-tester, after

Go further

• Add one synonym you hear in your own organization, then ask model-reviewer whether it is ambiguous.
• Shorten ai-instructions.md by 25 percent without losing the six required definitions, then rerun the Lab 09 check.
• In Desktop or the service, test one verified answer phrase and compare the returned visual with the YAML draft.

Something wrong or unclear on this page? Open a lab feedback issue. The form is prefilled with this page's name. Nothing is sent until you submit it, and please don't include screenshots of real accounts.