A tidier CMA format for focal points

Focal points are now non-localized: every asset has a single focal point, shared across all locales. That change is already live in every project and asks nothing of you. (If you missed it, here's the full story.)

This post is about the one part that is opt-in: the shape of default_field_metadata in the Content Management API.

By default, nothing changes for your integrations. The CMA keeps returning and accepting the existing locale-keyed shape, so your current code keeps working untouched. The only difference is that the focal point is now the same value in every locale entry: the one real value, replicated for backward compatibility.

When you want an API that reflects the new reality, opt in. With the flag on, default_field_metadata switches to a field-keyed shape: alt, title, and custom_data remain locale-keyed, but focal_point appears once at the top level. The legacy locale-keyed shape is then no longer accepted on write, so update any code that writes default_field_metadata to the new shape before you activate it.

Before opt-in migration: Current locale-keyed shape

1
{
2
  "data": {
3
    "id": "12345678",
4
    "type": "upload",
5
    "attributes": {
6
      "default_field_metadata": { // Locales first, then fields
7
        "en": { // Primary locale
8
          "alt": "English alt text",
9
          "title": "English title",
10
          "custom_data": {
11
            "english_custom_data": "hi"
12
          },
13
          "focal_point": {
14
            "x": 0.12,
15
            "y": 0.34
16
          }
17
        },
18
        "it": {
19
          "alt": "Italian alt text",
20
          "title": "Italian title",
21
          "custom_data": {
22
            "italian_custom_data": "ciao"
23
          },
24
          "focal_point": { // This is silently ignored now; overridden by primary
25
            "x": 0.56,
26
            "y": 0.78
27
          }
28
        }
29
      }
30
    }
31
  }
32
}

After opt-in migration: New field-keyed shape

1
{
2
  "data": {
3
    "id": "12345678",
4
    "type": "upload",
5
    "attributes": {
6
      "default_field_metadata": { // Fields first, then locales
7
        "alt": {
8
          "en": "English alt text",
9
          "it": "Italian alt text"
10
        },
11
        "title": {
12
          "en": "English title",
13
          "it": "Italian title"
14
        },
15
        "custom_data": {
16
          "en": {
17
            "english_custom_data": "hi"
18
          },
19
          "it": {
20
            "italian_custom_data": "ciao"
21
          }
22
        },
23
        "focal_point": { // No longer locale-specific
24
          "x": 0.12,
25
          "y": 0.34
26
        }
27
      }
28
    }
29
  }
30
}

Activating the opt-in

Existing Projects (created before 2026-06-11)

In an environment's Configuration screen (not Project settings), under Available updates, you should see a new opt-in update:

It's set per environment, and it's a one-way switch: once non_localized_focal_points is on, you can't turn it back off. If you have integrations that write default_field_metadata through the CMA, we strongly recommend enabling it first in a separate Sandbox environment, updating and verifying your integrations there, and only then activating it on your primary environment.

If you don't write this data programmatically, there's nothing to do here. The default shape continues to work, and the focal point is already consolidated across all assets.

New projects (created after 2026-06-11)

The opt-in is automatically enabled for new projects and will use the new field-keyed format.