AI readiness checklist

Checklist source

The checklist comes from rules/naming-conventions.yaml, rules/required-model-objects.yaml, and the pharmacy model conventions skill. tools/python/pharmacy_demo/conventions.py assigns issue IDs C01 to C15.

# Naming and metadata conventions for the Contoso Pharmacy semantic model.
# Read by tools/python/pharmacy_demo/conventions.py, the pharmacy-model-conventions skill,
# and the model-assessor agent. Change these rules in a pull request, not in a lab.
version: 1

names:
  # Visible tables, columns, measures, and hierarchies use business-friendly Title Case words.
  visible_object_pattern: "^[A-Z0-9][A-Za-z0-9 %()&/'.-]*$"
  forbid_underscores: true
  # Abbreviations that must be spelled out in visible names (case-insensitive whole words).
  forbidden_abbreviations: [rx, dt, nm, cd, typ, qty, rgn, mth, yr, qtr, dow, med, ther, cat, sply, proc, mins, flg, gnrc, wkend, dim, fact]
  # Allowed short forms because business users say them.
  allowed_short_forms: [ID, MoM, YoY, PM, PY, min]

descriptions:
  required_for: [table, visible_column, measure]
  max_length: 200          # Power BI Copilot reads only the first 200 characters.
  min_length: 20

columns:
  # Columns that must be hidden: surrogate keys, foreign keys, and sort helpers.
  hidden_patterns: ["(?i)[ _]key$", "(?i)^fill[ _]id$", "(?i)(?<!refill)[ _](number|num)$"]
  # Only these columns may keep a default summarization other than none.
  additive:
    "Prescription Fill":
      Quantity: sum
      Days Supply: sum
      Processing Time (min): average
  # Visible text columns that hold raw codes need a decoded, visible alternative.
  raw_code_columns:
    "Prescription Fill":
      Fill Type Code: Fill Type

measures:
  require_format_string: true
  require_display_folder: true
  display_folders: [Volume, Refills, Processing, Time Comparison]

View rules/naming-conventions.yaml on GitHub

# Objects the AI-ready model must contain. Read by conventions.py and the lab checks.
version: 1

tables: [Date, Store, Medication, Prescription Fill]

date_table:
  table: Date
  key_column: Date
  data_category: Time
  auto_date_time: false
  sort_by:
    Month: Month Number
    Year Month: Year Month Number
    Day of Week: Day of Week Number
  hierarchy:
    name: Calendar
    levels: [Year, Year Quarter, Year Month, Date]

relationships:
  - from: ["Prescription Fill", "Fill Date"]
    to: ["Date", "Date"]
  - from: ["Prescription Fill", "Store Key"]
    to: ["Store", "Store Key"]
  - from: ["Prescription Fill", "Medication Key"]
    to: ["Medication", "Medication Key"]
single_direction_only: true

measures:
  table: Prescription Fill
  required:
    Volume: [Prescriptions Filled, New Prescriptions]
    Refills: [Refills, Refill Rate, Refill Rate Index vs Chain, High Refill Activity Flag]
    Processing: [Avg Processing Time (min)]
    Time Comparison: [Prescriptions Filled PM, MoM Change, MoM %, Prescriptions Filled PY, YoY %]

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

    "C01": "Business-friendly names",
    "C02": "Descriptions present",
    "C03": "Description length",
    "C04": "Keys and helpers hidden",
    "C05": "Default summarization",
    "C06": "Raw codes decoded",
    "C07": "Required relationships",
    "C08": "Single-direction filters",
    "C09": "Marked date table",
    "C10": "Auto date/time off",
    "C11": "Sort-by columns",
    "C12": "Required measures",
    "C13": "Measure format strings and folders",
    "C14": "Default labels",
    "C15": "Q&A and AI prep drafts",

View tools/python/pharmacy_demo/conventions.py on GitHub

Run one rule

pwsh ./scripts/Test-ModelConventions.ps1 -Rule C01

Run all rules:

pwsh ./scripts/Test-ModelConventions.ps1

Rules

Rule	Item	Why it matters for AI	How it is checked	Lab that fixes it
C01	Business-friendly names	Natural-language prompts match business words, not source abbreviations.	Visible tables, columns, measures, and hierarchies must match the title-case pattern, avoid underscores, and spell out forbidden abbreviations.	Lab 07
C02	Descriptions present	Copilot uses descriptions to understand semantics and avoid false assumptions.	Tables, visible columns, and measures require descriptions.	Lab 07
C03	Description length	Short descriptions are vague. Long descriptions can be ignored or truncated by Copilot.	Descriptions must be at least 20 characters and at most 200 characters.	Lab 07
C04	Keys and helpers hidden	Users and agents should not choose surrogate keys or sort helpers as analytical fields.	Key columns, fill IDs, and sort helpers must be hidden.	Lab 07
C05	Default summarization	Wrong summarization creates bad totals and misleading answers.	Only approved additive columns can summarize. Others use `none`.	Lab 07
C06	Raw codes decoded	AI should see business labels instead of raw system codes.	Raw code columns require a decoded visible alternative.	Lab 07
C07	Required relationships	Questions need joins across dates, stores, medications, and fills.	Required relationships from `Prescription Fill` to dimensions must exist.	Lab 07
C08	Single-direction filters	Bidirectional filters can create ambiguous paths and unstable answers.	Relationships must use single-direction filtering.	Lab 07
C09	Marked date table	Time-intelligence questions need a proper Date table.	`Date` must be marked as a date table using the Date column.	Lab 08
C10	Auto date/time off	Hidden auto date tables confuse field selection and DAX behavior.	Auto date/time must be disabled.	Lab 08
C11	Sort-by columns	Month names and day names need chronological ordering.	Month, year-month, and day-of-week columns must use configured sort columns.	Lab 08
C12	Required measures	Agents should reuse trusted measures instead of improvising calculations.	Required Volume, Refills, Processing, and Time Comparison measures must exist.	Lab 08
C13	Measure format strings and folders	Formats help agents interpret rates, counts, and money. Folders help tool navigation.	Measures require format strings and approved display folders.	Lab 08
C14	Default labels	Entity recognition works better when tables have obvious label columns.	Store and Medication need default labels.	Lab 09
C15	Q&A and AI prep drafts	Copilot needs concise instructions, synonyms, schema hints, and verified examples.	`fabric/ai-prep` must contain required files, required mentions, synonyms, verified answers, and Q&A enabled state.	Lab 09

Skill reference

The skill gives agents the business context behind the rules.

---
name: pharmacy-model-conventions
description: House conventions for the Contoso Pharmacy semantic model, covering business names, descriptions, hidden keys, summarization, display folders, required relationships and measures, and the AI-readiness checklist. Use when you assess, review, or change model names, descriptions, measures, relationships, or the date table, or when you need the standard business name for a source column.
---
# Contoso Pharmacy model conventions

These conventions make the model easy for people and for AI tools (Power BI Copilot, Fabric data agents, and coding agents) to read. They are checked by rules C01 to C15.

The rules themselves are data, not prose. Read them from:

- `rules/naming-conventions.yaml`: name pattern, forbidden abbreviations, description length, hidden-column patterns, additive columns, raw-code columns, display folders.
- `rules/required-model-objects.yaml`: required tables, relationships, date table settings, the twelve required measures by display folder, default labels, and the AI prep requirements.

## Get the current findings

Run the checker instead of reviewing by eye. It's deterministic and it's the same code the lab checks use.

```powershell
pwsh ./scripts/Test-ModelConventions.ps1            # table of findings
pwsh ./scripts/Test-ModelConventions.ps1 -Json      # for agents
pwsh ./scripts/Test-ModelConventions.ps1 -Rule C07,C08
```

On macOS or Linux, `pwsh` runs the same scripts. Every finding has a rule, severity, object, finding, and fix.

## Rules

| Rule | Title | What good looks like |
|---|---|---|
| C01 | Business-friendly names | Title Case words with spaces. No underscores or abbreviations like `rx`, `dt`, `nm`, `qty`. Use the names in [the data dictionary](references/data-dictionary.md). |
| C02 | Descriptions present | Every table, visible column, and measure has a `///` description. |
| C03 | Description length | 20 to 200 characters. Say what it is, its grain or unit, and when to use it. |
| C04 | Keys and helpers hidden | Surrogate keys, foreign keys, `Fill ID`, and sort-by number columns are hidden. |
| C05 | Default summarization | `summarizeBy: none` everywhere except `Quantity` and `Days Supply` (sum) and `Processing Time (min)` (average). |
| C06 | Raw codes decoded | `Fill Type Code` (N or R) is hidden, and a visible `Fill Type` column shows New or Refill. |

View .github/skills/pharmacy-model-conventions/SKILL.md on GitHub