# 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