v3 - Breaking changes

v3 – Breaking Changes

OpenSearch 3.x introduces a significant set of changes that may impact the compatibility of your applications, ingestion pipelines, dashboards, and plugins.

These changes are mainly related to:

• the migration to Apache Lucene 10,

• the mandatory adoption of Java 21,

• the removal of legacy mechanisms (Security Manager, deprecated APIs),

• changes in mappings,

• updates in OpenSearch Dashboards,

• and the expanded introduction of Workspaces.

---

🔗 Official OpenSearch References

• Breaking Changes: https://docs.opensearch.org/latest/breaking-changes/

• OpenSearch 3.0 – What to Expect: https://opensearch.org/blog/opensearch-3-0-what-to-expect/

• Release Notes 3.0.0: https://github.com/opensearch-project/opensearch-build/blob/main/release-notes/opensearch-release-notes-3.0.0.md

---

1. Migration to Apache Lucene 10

Reference: https://opensearch.org/blog/opensearch-3-0-what-to-expect/

OpenSearch 3.0 adopts Lucene 10, which introduces:

• internal changes to index structures,

• modifications in segment management,

• removal of older index formats,

• incompatibilities with indices created using older Lucene versions.

Impact: A full reindex may be required depending on your current version.

---

2. Mandatory Upgrade to Java 21 (JDK 21)

Reference: https://opensearch.org/blog/opensearch-3-0-what-to-expect/

OpenSearch 3.x now requires Java 21.

Impact:

• Runtime environments must be updated.

• Internal or third‑party plugins must be recompiled.

• Scripts relying on deprecated Java APIs must be updated.

---

3. Removal of the Java Security Manager

Reference: https://opensearch.org/blog/opensearch-3-0-what-to-expect/

The Java Security Manager, already deprecated, is fully removed.

Impact:

• Plugins relying on this mechanism must be rewritten.

• Some security controls must be redesigned.

---

4. Mapping Changes

Reference: https://docs.opensearch.org/latest/breaking-changes/

OpenSearch 3.x introduces several important changes to mappings, mainly due to Lucene 10 and the cleanup of legacy APIs.

---

4.1 Complete Removal of Mapping Types

Reference: https://docs.opensearch.org/latest/breaking-changes/

Mapping types (_type) are now fully removed.

Impact:

• Ingestion pipelines must no longer send a type.

• Requests using /index/type/_doc will fail.

---

4.2 Removal of Deprecated Mapping Parameters

Reference: https://docs.opensearch.org/latest/breaking-changes/

The following parameters are no longer supported:

• include_type_name

• numeric_detection

• date_detection (partially modified)

• fielddata on certain field types

• norms on non‑text fields

• index_options (simplified)

• restrictions on doc_values

Impact: Mappings containing these parameters will fail to create or update.

---

4.3 Changes to Field Types

Reference: https://docs.opensearch.org/latest/breaking-changes/

• text: stricter rules for custom analyzers

• keyword: stricter behavior for ignore_above

• date: stricter parsing for custom formats

• boolean: non‑standard values no longer accepted

• nested: reinforced structural limitations

---

4.4 Changes to Analyzers and Tokenizers

Reference: https://docs.opensearch.org/latest/breaking-changes/

With Lucene 10:

• some analyzers change behavior,

• some tokenizers are removed or renamed,

• custom analyzers must be updated for compatibility.

---

4.5 Stricter Mapping Update Rules

Reference: https://docs.opensearch.org/latest/breaking-changes/

• stricter validation rules,

• some dynamic fields can no longer be added,

• index templates must be updated.

---

5. Plugin Changes

Reference: https://opensearch.org/blog/opensearch-3-0-what-to-expect/

The core OpenSearch update introduces:

• changes in internal APIs,

• required adjustments for third‑party plugins,

• potential incompatibilities with plugins built for OpenSearch 1.x or 2.x.

Detailed impacts:

• Plugins must be recompiled with updated dependencies.

• Plugins using internal Lucene classes must be adapted.

• Security, analytics, and monitoring plugins are the most affected.

• Unmaintained plugins will no longer work.

---

6. OpenSearch Dashboards Changes (3.x)

Reference: https://docs.opensearch.org/latest/breaking-changes/

OpenSearch Dashboards 3.x introduces major updates.

---

6.1 Node.js Runtime Upgrade

Reference: https://docs.opensearch.org/latest/breaking-changes/

Dashboards 3.x requires Node.js ≥ 14.

---

6.2 Internal API Changes

Reference: https://docs.opensearch.org/latest/breaking-changes/

• stricter visualization APIs

• modified endpoints

• changes in saved object handling

---

6.3 Changes to the .opensearch_dashboards Index

Reference: https://docs.opensearch.org/latest/breaking-changes/

• automatic migration

• cleanup of deprecated fields

• stronger validation rules

---

6.4 Visualization and Plugin Compatibility

Reference: https://docs.opensearch.org/latest/breaking-changes/

• plugins built for 1.x / 2.x must be updated

• custom visualizations must be tested

• removed fields may break dashboards

---

6.5 Security Hardening

Reference: https://docs.opensearch.org/latest/breaking-changes/

• stricter CSP rules

• restrictions on inline scripts

• limitations on external iframes

---

6.6 Changes in Filters and Search

Reference: https://docs.opensearch.org/latest/breaking-changes/

• stricter filters

• explicit errors for unmapped fields

• DSL queries must be validated

---

7. Migration to Workspaces

Reference: https://docs.opensearch.org/latest/dashboards/workspaces/

Workspaces progressively replace the former Spaces.

---

7.1 What Workspaces Change

Reference: https://docs.opensearch.org/latest/dashboards/workspaces/

• stronger isolation of dashboards and visualizations

• granular permissions

• ability to associate multiple data sources

• clearer logical separation (teams, projects, environments)

---

7.2 User Impacts

Reference: https://docs.opensearch.org/latest/dashboards/workspaces/

• dashboards may be migrated to a default workspace

• shared dashboards may need reorganization

• RBAC permissions must be reviewed