Apex Schema Describe

Apex Schema Describe

Schema describe is one of the most-used and most-misused APIs in Apex. Schema.getGlobalDescribe() looks free — it isn't. Calling SObjectField.getDescribe() per record in a 200-record trigger multiplies a small cost into a CPU-budget problem. FLS checks against DescribeFieldResult.isAccessible() look correct — but the API surface has subtle differences between Schema.SObjectType.newSObject() describe and Schema.DescribeFieldResult describe.

This skill covers the patterns that make Schema describe fast and correct: caching, FLS checks, picklist enumeration, and the loop-cost trap.

NOT for SOQL string-binding (apex/dynamic-soql); NOT for Tooling API metadata work (apex/tooling-api).

Before Starting

• Identify the call site. One-shot at request start (cheap, any pattern works) vs in a loop (must cache).
• Identify what you need. SObjectType reference, DescribeSObjectResult, DescribeFieldResult, picklist values — each has a different API call.
• Identify whether the input is static or dynamic. Compile-time known type → use MyObj__c.SObjectType directly (no describe call). Runtime string → Schema.getGlobalDescribe().get(name).

Core Concepts

Static-vs-runtime SObjectType lookup

// Compile-time: zero describe cost
Schema.SObjectType t = Account.SObjectType;

// Runtime (string): one global-describe lookup
Schema.SObjectType t = Schema.getGlobalDescribe().get('Account');

Schema.getGlobalDescribe() is the expensive call — it materializes the entire org's SObject inventory. Cache the result if you call it more than once per transaction.

Caching describe results

public class SchemaCache {
    private static final Map<String, Schema.SObjectType> TYPES =
        Schema.getGlobalDescribe();
    private static final Map<String, Map<String, Schema.SObjectField>> FIELDS_BY_TYPE =
        new Map<String, Map<String, Schema.SObjectField>>();

    public static Schema.SObjectField field(String objName, String fieldName) {
        Map<String, Schema.SObjectField> fields = FIELDS_BY_TYPE.get(objName);
        if (fields == null) {
            Schema.SObjectType t = TYPES.get(objName);
            if (t == null) return null;
            fields = t.getDescribe().fields.getMap();
            FIELDS_BY_TYPE.put(objName, fields);
        }
        return fields.get(fieldName);
    }
}

static final ensures the global describe runs once per class load. Per-type field maps are lazy.

FLS check via DescribeFieldResult

Schema.DescribeFieldResult dfr = Account.SSN__c.getDescribe();
if (!dfr.isAccessible()) {
    throw new SecurityException('No FLS read');
}
if (!dfr.isUpdateable()) {
    throw new SecurityException('No FLS update');
}

Modern alternative — Security.stripInaccessible (preferred for DML) handles bulk records:

SObjectAccessDecision dec = Security.stripInaccessible(
    AccessType.UPDATABLE, records
);
update dec.getRecords();

Picklist value enumeration

List<Schema.PicklistEntry> entries =
    Account.Industry.getDescribe().getPicklistValues();

List<String> activeValues = new List<String>();
for (Schema.PicklistEntry pe : entries) {
    if (pe.isActive()) {
        activeValues.add(pe.getValue());  // API name; use getLabel() for display
    }
}

Inactive entries are still in the list — filter explicitly.

Common Patterns

Pattern A — Hot-path describe with class-level cache

public class FieldValidator {
    private static final Map<String, Schema.SObjectField> FIELDS =
        Account.SObjectType.getDescribe().fields.getMap();

    public static Boolean isAccessible(String fieldName) {
        Schema.SObjectField f = FIELDS.get(fieldName);
        return f != null && f.getDescribe().isAccessible();
    }
}

static final + per-type field map = describe runs once per class load.

Pattern B — Bulk FLS via stripInaccessible

public static List<Account> readAccessible(List<Account> records) {
    SObjectAccessDecision dec = Security.stripInaccessible(
        AccessType.READABLE, records
    );
    return (List<Account>) dec.getRecords();
}

Removes inaccessible field values from the records — bulk-safe, governor-cheap.

Pattern C — Dynamic SObject creation by name

public static SObject create(String objName) {
    Schema.SObjectType t = Schema.getGlobalDescribe().get(objName);
    if (t == null) throw new IllegalArgumentException(objName);
    return t.newSObject();
}

Use Schema.getGlobalDescribe().get(name) — NOT Type.forName(name). Type.forName returns System.Type, not an SObject prototype.

Decision Guidance

Recommended Workflow

1. Identify call frequency. Loop body = cache. One-shot = anywhere.
2. Use compile-time references when possible. Skip describe entirely.
3. For dynamic strings, cache Schema.getGlobalDescribe() once.
4. For FLS on bulk DML, use Security.stripInaccessible.
5. For picklist enumeration, filter isActive() explicitly.
6. Test the namespaced case if managed packages are in scope.

Review Checklist

• No Schema.getGlobalDescribe() inside loops.
• Per-type field map cached as static final when used in hot paths.
• FLS checks use Security.stripInaccessible for bulk DML.
• Picklist enumeration filters by isActive().
• Dynamic SObject creation uses Schema.getGlobalDescribe() not Type.forName.
• Managed-package SObjects include namespace prefix.

Salesforce-Specific Gotchas

1. Schema.getGlobalDescribe() is expensive. Cache. (See references/gotchas.md § 1.)
2. getDescribe() on a field in a loop multiplies cost. Cache the field map at class scope. (See references/gotchas.md § 2.)
3. Inactive picklist entries appear in getPicklistValues(). Filter. (See references/gotchas.md § 3.)
4. Type.forName returns System.Type, not SObjectType. Use Schema.getGlobalDescribe().get(). (See references/gotchas.md § 4.)
5. Managed-package fields require the namespace prefix. (See references/gotchas.md § 5.)

Output Artifacts

Related Skills

• apex/dynamic-apex — broader dynamic-Apex patterns; this skill is the schema-describe slice.
• apex/dynamic-soql — SOQL string binding (different concern: SOQL injection prevention).
• apex/apex-switch-on-sobject — when describe-driven dispatch fits a switch-on-SObject pattern.
• security/field-level-security-design — broader FLS architecture; this skill is the Apex-side enforcement.