Evolution of Field Changes in BC

In both Navision (Dynamics NAV) and Business Central (BC), a field is the fundamental unit of data in a table. Fields define what kind of information is stored, how it is used in business processes, and how other objects—such as pages, reports, and codeunits—interact with it. Each field also has a unique numeric identifier, known as the field number, which plays a critical role in maintaining the stability and consistency of the table schema. Numbering allows fields to be uniquely identified regardless of their names, enables references from other objects without relying on field names, and supports safe data upgrades and migrations.

In classic Navision (Dynamics NAV), developers had almost complete freedom to modify table fields. You could:

• Change the field name freely.
• Even change the field number, as long as all dependent objects—tables, pages, reports, and codeunits—were regenerated to reflect the changes.
• The only restrictions applied to certain data type changes; some types could not be modified, or required clearing existing field data.

While this approach was highly flexible, it was also risky: missing dependent objects could easily result in runtime errors.

Modern Approach in Business Central Extensions

With the introduction of AL extensions, Microsoft formalized field deprecation and removal to improve safety, maintainability, and compatibility.

1. Introduction of ObsoleteState

• Business Central 14 (2020 Release Wave 1) introduced the property ObsoleteState for tables, fields, pages, and other objects.
• Possible values:
  • Pending → the field or object is scheduled for future removal
  • Removed → the field or object is deprecated and should no longer be used
• Additional optional properties include:
  • ObsoleteTag → a label for the reason or category of obsolescence
  • ObsoleteReason → a descriptive explanation for why the field is obsolete

This allows developers to mark objects as deprecated without immediately breaking extensions.

2. Controlled Physical Removal

• Business Central 26 (2025 Release Wave 1) introduced automatic schema cleanup.
• Fields and objects marked as Removed for a sufficient period are now physically removed from the database.
• Cleanup occurs cyclically, approximately every 5 major releases, ensuring backward compatibility while keeping the schema clean.
• Developers must refactor extensions that reference removed fields before cleanup to avoid compilation or runtime issues.

Nothing speaks louder than code… and even louder than that is code that actually works :).

Table CustomTable
{
    fields
    {
        // Active field – can be used freely
        field(1; "Name"; Text[100])
        {
            // Active, no ObsoleteState
            // Data is fully accessible and should be used in new code
        }

        // Field scheduled for future removal – data still needed
        field(2; "Old Email"; Text[100])
        {
            ObsoleteState = Pending;              // Warns developers: this field will be removed in the future
            ObsoleteReason = 'Use "Primary Email" instead';
            // Data is still available and must be preserved
            // Developers should migrate usage gradually
        }

        // Field already marked as deprecated – should not be used in new code
        field(3; "Fax Number"; Text[50])
        {
            ObsoleteState = Removed;              // Field is deprecated, compiler will warn if used
            ObsoleteReason = 'Use "Mobile Phone" instead';
            // Data is still present but should not be referenced in new code
            // Migration of data to new field recommended
        }

        // Field already removed from schema – data physically deleted (after cleanup cycle)
        field(4; "Legacy ID"; Integer)
        {
            ObsoleteState = Removed;              // Already cleaned up in schema
            ObsoleteReason = 'No longer used, removed by cleanup';
            // Data no longer exists; any reference will fail compilation/runtime
        }

        // Active replacement field
        field(5; "Primary Email"; Text[100])
        {
            // Active, new field to replace deprecated ones
            // Safe to use in all new code
        }
    }
}

Table CustomTable
{
    fields
    {
        // Active field – can be used freely
        field(1; "Name"; Text[100])
        {
            // Active, no ObsoleteState
            // Data is fully accessible and should be used in new code
        }

        // Field scheduled for future removal – data still needed
        field(2; "Old Email"; Text[100])
        {
            ObsoleteState = Pending;              // Warns developers: this field will be removed in the future
            ObsoleteReason = 'Use "Primary Email" instead';
            // Data is still available and must be preserved
            // Developers should migrate usage gradually
        }

        // Field already marked as deprecated – should not be used in new code
        field(3; "Fax Number"; Text[50])
        {
            ObsoleteState = Removed;              // Field is deprecated, compiler will warn if used
            ObsoleteReason = 'Use "Mobile Phone" instead';
            // Data is still present but should not be referenced in new code
            // Migration of data to new field recommended
        }

        // Field already removed from schema – data physically deleted (after cleanup cycle)
        field(4; "Legacy ID"; Integer)
        {
            ObsoleteState = Removed;              // Already cleaned up in schema
            ObsoleteReason = 'No longer used, removed by cleanup';
            // Data no longer exists; any reference will fail compilation/runtime
        }

        // Active replacement field
        field(5; "Primary Email"; Text[100])
        {
            // Active, new field to replace deprecated ones
            // Safe to use in all new code
        }
    }
}

Timeline of Field Handling Evolution

The current approach in Business Central is safe because fields must first be deprecated using ObsoleteState, allowing dependent extensions to adjust before the field is physically removed. This controlled, cyclical cleanup ensures backward compatibility, prevents runtime errors, and maintains a clean and stable database schema.