PranavNagrecha/AwesomeSalesforceSkills / skills/admin/data-model-documentation
data-model-documentation
VerifiedUse when a BA or admin needs to document the Salesforce data model: creating field inventories, object relationship maps, ER diagrams, or analyzing field usage across objects. Triggers: 'data dictionary', 'document our data model', 'object relationship map', 'field inventory', 'ER diagram for Salesforce'. NOT for designing the model or choosing lookup vs master-detail — use data/data-model-design-patterns. NOT for generating the Mermaid or PlantUML diagram — use architect/salesforce-erd-and-diagramming. More trigger keywords: field inventory CSV, describe API, getGlobalDescribe, DescribeFieldResult, sObject describe, schema snapshot, schema drift, blank field descriptions, undocumented fields, field ownership, data dictionary review cadence.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 23.7 KB |
| references/examples.md | markdown | 6.4 KB |
| references/gotchas.md | markdown | 15.4 KB |
| references/llm-anti-patterns.md | markdown | 7.0 KB |
| references/well-architected.md | markdown | 6.9 KB |
| references/worked-examples.md | markdown | 21.9 KB |
| scripts/check_data_model_documentation.pyexecutable | script | 16.3 KB |
| templates/data-dictionary.yaml | config | 2.0 KB |
| templates/data-model-documentation-template.md | markdown | 3.3 KB |
references/examples.md
View on GitHub# Examples — Data Model Documentation
## Example 1: Field Inventory for a Service Cloud Onboarding
**Context:** A new admin joins an org that has been running Service Cloud for three years. No data dictionary exists. The team needs to document the Case and custom `Service_Contract__c` objects before a planned integration project begins.
**Problem:** The admin opens Object Manager and sees 85 fields on Case and 42 on `Service_Contract__c`. Most custom fields have blank Descriptions. Without documentation, the integration team cannot safely map fields without risking misuse (e.g., treating a legacy picklist as a current status field).
**Solution:**
1. Run an SFDX retrieve targeting both objects:
```bash
sf project retrieve start --metadata "CustomObject:Case,CustomObject:Service_Contract__c"
```
2. In the retrieved `objects/Case/fields/` folder, scan each `.field-meta.xml` file for `<description>` tags. Fields with empty or absent tags are undocumented.
3. Build a spreadsheet from the XML: extract `<fullName>`, `<label>`, `<type>`, `<required>`, `<externalId>`, `<description>`, and `<referenceTo>` for lookup fields.
4. Share the spreadsheet with the business team and ask them to fill in blank Descriptions. This becomes the source-of-truth data dictionary.
5. After descriptions are populated, update the field metadata in the repo and deploy.
**The joined row set** — describe supplies columns 3–7, the retrieve supplies columns 8–10. Neither
source alone fills the table, which is why step 3 is a join rather than an export:
```csv
object,apiName,type,required,externalId,isFormula,relationshipName,description,businessStatus,securityClassification
Case,ERP_Ticket_Ref__c,STRING,false,true,false,,"Ticket id in the ITSM tool. Upsert key for the inbound sync.",Active,Internal
Case,Legacy_Priority__c,PICKLIST,false,false,false,,,Hidden,Internal
Case,Contract__c,REFERENCE,false,false,false,Contract,"Contract the case is worked under. Drives milestone selection.",Active,Internal
Service_Contract__c,Account__c,REFERENCE,true,false,false,Account,"Master-detail parent. Cascade delete.",Active,Internal
Service_Contract__c,Days_Remaining__c,DOUBLE,false,false,true,,,Active,Internal
```
Read the two empty `description` cells as the work order: `Legacy_Priority__c` is already
`businessStatus: Hidden`, so it needs a deprecation note rather than a purpose; `Days_Remaining__c` is a
formula (`isFormula` true), so its description should carry the business rule the formula encodes, because
the formula text itself is not visible to anyone reading the org through the API.
**Why it works:** The Metadata API returns every custom field property in a machine-readable format. Version-controlling the updated metadata means description changes are tracked over time, and future drift can be detected with a git diff.
---
## Example 2: ER Diagram for a Sales Process Workshop
**Context:** A BA is facilitating a sales process redesign workshop. Stakeholders need to understand how Lead, Contact, Account, Opportunity, and `Quote__c` relate to each other before the team can map their new process to the system.
**Problem:** Non-technical stakeholders do not understand Salesforce's data model. Without a clear diagram, discussions spiral into confusion about where data lives and who owns it.
**Solution:**
1. Open Setup → Object Manager → Schema Builder.
2. Clear all objects. Add: Lead, Contact, Account, Opportunity, Quote__c, OpportunityLineItem, Product2, Pricebook2.
3. Rearrange objects so the flow reads left to right: Lead → (converted to) → Contact/Account → Opportunity → OpportunityLineItem → Product2.
4. Toggle "Show Elements → Field Names" on for the relationship fields only (WhoId, AccountId, etc.).
5. Export via screenshot. Annotate in a drawing tool: label each arrow with "Lookup" or "Master-Detail", note that Lead conversion creates Contact + Account + Opportunity.
6. Present the diagram in the workshop. Note that the Lead-to-Opportunity conversion is a Salesforce process, not a direct relationship field.
**The relationship rows the annotations come from** — extracted before the workshop, so the arrows
in the diagram are asserted from metadata rather than from memory:
| Child object | Field API name | referenceTo | relationshipName | Type | Cascade delete |
|---|---|---|---|---|---|
| Opportunity | AccountId | Account | Account | Lookup | No |
| Opportunity | ContractId | Contract | Contract | Lookup | No |
| OpportunityLineItem | OpportunityId | Opportunity | Opportunity | Master-Detail | Yes |
| OpportunityLineItem | PricebookEntryId | PricebookEntry | PricebookEntry | Lookup | No |
| Quote__c | Opportunity__c | Opportunity | Opportunity | Lookup | No |
| Task | WhoId | Contact, Lead | Who | Polymorphic lookup | No |
| Task | WhatId | Account, Opportunity, Case, Contract, ... | What | Polymorphic lookup | No |
The two `Task` rows carry more than one value in `referenceTo`, which is the machine-readable signal that
they need a note annotation rather than an arrow. Lead conversion has no row at all — it is a platform
process, not a relationship field, which is why step 6 states it separately.
**Why it works:** Schema Builder visualizes the physical Salesforce relationship model without requiring any custom tooling. Annotating conversion processes (which are not relationship fields) separately prevents the diagram from being misleading about how data moves.
---
## Anti-Pattern: Documenting Only Custom Objects
**What practitioners do:** When asked to "document the data model," admins sometimes produce documentation only for custom objects, skipping standard objects like Account, Contact, and Case because "everyone knows what those are."
**What goes wrong:** Integration projects and data migration plans break when custom fields on standard objects are undocumented. A custom field `Account.ERP_Customer_ID__c` used as the external ID for sync is functionally critical, but it lives on a standard object and gets skipped. New team members and integration partners have no idea the field exists or what it contains.
**Correct approach:** Include all custom fields on standard objects in the field inventory. Standard objects are not self-documenting — their custom fields need exactly the same treatment as fields on custom objects. Use the Metadata API retrieve for `CustomObject:Account`, `CustomObject:Contact`, etc. to extract just the custom additions without pulling in standard field definitions that are already in the Object Reference.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |