Skip to content

PranavNagrecha/AwesomeSalesforceSkills / skills/admin/data-model-documentation

data-model-documentation

Verified

Use 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.

references/well-architected.md

View on GitHub
# Well-Architected Notes — Data Model Documentation

## Relevant Pillars

- **Operational Excellence** — The primary pillar for this skill. An undocumented data model creates operational risk: integrations break on renamed or repurposed fields, new admins make incorrect changes, and audits fail when field ownership cannot be demonstrated. Keeping a current, accurate field inventory and ER diagram is a core operational excellence practice.
- **Security** — FLS documentation is part of a security review. Without documented field-level permissions, you cannot confirm that sensitive fields (SSNs, payment references, health data) are restricted to the correct profiles and permission sets. The security architecture review skill depends on accurate FLS documentation.
- **Reliability** — Integration reliability depends on stable, well-documented field contracts. When a field's purpose is documented (external ID, integration sync key, deprecated legacy field), downstream systems can make appropriate decisions about consuming or ignoring it. Undocumented fields are changed or deleted without awareness of downstream impact.

## Architectural Tradeoffs

**Complete vs. scoped documentation:** Documenting every field in a large org (thousands of custom fields) is a multi-week project. Scoping documentation to the objects used by a specific integration, process, or team delivers value faster. The tradeoff is that out-of-scope objects remain a risk. Best practice is to start with the objects touched by active integrations and high-risk processes, then expand coverage iteratively.

**Living documentation vs. point-in-time snapshot:** A spreadsheet captured today will drift from the real schema within weeks as admins add and rename fields. Documentation stored as version-controlled metadata (via SFDX source format in Git) stays current because schema changes produce diffs. The tradeoff is that this requires a Git-based development workflow.

## Anti-Patterns

1. **Documentation that only covers custom objects** — Standard objects like Account and Contact are modified heavily in most orgs. Custom fields added to standard objects carry the same documentation obligation as fields on custom objects. Omitting them leaves integration and audit gaps.
2. **ER diagrams built without checking for polymorphic lookups** — Diagrams produced from Schema Builder alone miss polymorphic relationships (Task WhoId/WhatId). These are among the most commonly misunderstood relationships in the Salesforce data model. Diagrams that omit or misrepresent them mislead integration architects and developers.
3. **No ownership column in the field inventory** — A field inventory without a team or system owner column becomes stale immediately. Fields that were added for a project that no longer exists sit undocumented in perpetuity. Each custom field should have a documented owner who is responsible for its accuracy and who should be consulted before the field is modified.

## Official Sources Used

- Apex Reference Guide, `DescribeFieldResult` method list — https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/apexrefguide.pdf — the complete accessor list (`getReferenceTo`, `getRelationshipName`, `getRelationshipOrder`, `getInlineHelpText`, `getLength`, `isCustom`, `isCalculated`, `isNillable`, `isCascadeDelete`, `isNamePointing`, `isAccessible`, `getLocalName`) used for the field-inventory and ER-map generators, and for the fact that no `getDescription()` accessor exists (Gotchas 5, 6, 8, 9; worked-examples sections 1 and 3)
- Apex Reference Guide, `Schema.getGlobalDescribe()` and `Schema.describeSObjects()` — same PDF — the object-enumeration entry point and the "call getGlobalDescribe, then describeSObjects" pattern the inventory script follows
- Apex Developer Guide, "Describing sObjects Using Schema Methods" — https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/salesforce_apex_developer_guide.pdf — the `res.fields.getMap()` iteration idiom and the `getChildRelationships()` example that worked-examples section 1 is shaped from
- Metadata API Developer Guide, `CustomObject` and `CustomField` type entries — https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/api_meta.pdf — the `description`, `inlineHelpText`, `businessOwnerUser`, `businessOwnerGroup`, `businessStatus`, `securityClassification`, `complianceGroup`, `referenceTo`, `relationshipName` and `formula` elements that only the retrieve path exposes (worked-examples section 4; the checker's allowed value sets)
- Metadata API Developer Guide, "Sample package.xml Manifest Files" (Standard Objects / All Custom Objects) — same PDF — the wildcard-excludes-standard-objects behaviour and the non-customisable-standard-fields exclusion behind Gotcha 11, plus the Profile/PermissionSet co-retrieval note used for FLS snapshots
- Object Reference for the Salesforce Platform, "Compound Field Considerations and Limitations" — https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/object_reference.pdf — geolocation counting as three custom fields, compound fields being API-only, their absence from Schema Builder and dashboards, the Data Loader export error, and the `isFilterable()` misreport for address fields (Gotcha 7); also the standard-object field tables used to fill the gap Gotcha 1 describes
- REST API Developer Guide, "sObject Describe" and "Get Object Metadata Changes" — https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/api_rest.pdf — the `/services/data/vXX.X/sobjects/<sObject>/describe/` resource and the `If-Modified-Since` → `304 Not Modified` (empty body) drift-detection behaviour used by worked-examples section 2
- Salesforce App Limits Cheat Sheet, SOAP API Call Limits — https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/salesforce_app_limits_cheatsheet.pdf — `describeSObjects()` returns a maximum of 100 objects, which is why the inventory script batches its object list
- `skills/security/data-classification-labels/SKILL.md` — owns the `SecurityClassification` / `ComplianceGroup` / `BusinessOwnerId` / `BusinessStatus` value sets and their governance; this skill consumes them as dictionary columns rather than restating them
- `skills/devops/metadata-diff-between-sandboxes/SKILL.md` — owns interpretation of a two-org delta (which side is authoritative, destructive-changes manifests); worked-examples section 6 stops at producing two comparable snapshots
- `agents/data-model-reviewer/AGENT.md` (Mandatory Reads item 22) and `agents/field-impact-analyzer/AGENT.md` (Step 1, FieldDefinition projection) — the two consumers of the artefacts this skill produces, and the source for the Tooling `FieldDefinition` filter and column constraints in Gotcha 10
- Salesforce Well-Architected Overview — https://architect.salesforce.com/docs/architect/well-architected/guide/overview.html — used for Operational Excellence pillar framing and documentation as a quality practice
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall