diff --git a/format/spec.md b/format/spec.md
index 9d8157ae302d..3c96949bb7f2 100644
--- a/format/spec.md
+++ b/format/spec.md
@@ -182,6 +182,21 @@ A **`list`** is a collection of values with some element type. The element field
A **`map`** is a collection of key-value pairs with a key type and a value type. Both the key field and value field each have an integer id that is unique in the table schema. Map keys are required and map values can be either optional or required. Both map keys and map values may be any type, including nested types.
+#### Semi-structured Types
+
+A **`variant`** is a value that stores semi-structured data. The structure and data types in a variant are not necessarily consistent across rows in a table or data file. The variant type and binary encoding are defined in the [Parquet project](https://github.com/apache/parquet-format/blob/4f208158dba80ff4bff4afaa4441d7270103dff6/VariantEncoding.md). Support for Variant is added in Iceberg v3.
+
+Variants are similar to JSON with a wider set of primitive values including date, timestamp, timestamptz, binary, and floating points.
+
+Variant values may contain nested types:
+1. An array is an ordered collection of variant values.
+2. An object is a collection of fields that are a string key and a variant value.
+
+As a semi-structured type, there are important differences between variant and Iceberg's other types:
+1. Variant arrays are similar to lists, but may contain any variant value rather than a fixed element type.
+2. Variant objects are similar to structs, but may contain variable fields identified by name and field values may be any variant value rather than a fixed field type.
+3. Variant primitives are narrower than Iceberg's primitive types: time, timestamp_ns, timestamptz_ns, uuid, and fixed(L) are not supported.
+
#### Primitive Types
Supported primitive types are defined in the table below. Primitive types added after v1 have an "added by" version that is the first spec version in which the type is allowed. For example, nanosecond-precision timestamps are part of the v3 spec; using v3 types in v1 or v2 tables can break forward compatibility.
@@ -449,7 +464,7 @@ Partition field IDs must be reused if an existing partition spec contains an equ
| Transform name | Description | Source types | Result type |
|-------------------|--------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|-------------|
-| **`identity`** | Source value, unmodified | Any | Source type |
+| **`identity`** | Source value, unmodified | Any except for `variant` | Source type |
| **`bucket[N]`** | Hash of value, mod `N` (see below) | `int`, `long`, `decimal`, `date`, `time`, `timestamp`, `timestamptz`, `timestamp_ns`, `timestamptz_ns`, `string`, `uuid`, `fixed`, `binary` | `int` |
| **`truncate[W]`** | Value truncated to width `W` (see below) | `int`, `long`, `decimal`, `string`, `binary` | Source type |
| **`year`** | Extract a date or timestamp year, as years from 1970 | `date`, `timestamp`, `timestamptz`, `timestamp_ns`, `timestamptz_ns` | `int` |
@@ -1154,6 +1169,7 @@ Maps with non-string keys must use an array representation with the `map` logica
|**`struct`**|`record`||
|**`list`**|`array`||
|**`map`**|`array` of key-value records, or `map` when keys are strings (optional).|Array storage must use logical type name `map` and must store elements that are 2-field records. The first field is a non-null key and the second field is the value.|
+|**`variant`**|`record` with `metadata` and `value` fields. `metadata` and `value` must not be assigned field IDs. |Shredding is not supported in Avro.|
Notes:
@@ -1208,6 +1224,7 @@ Lists must use the [3-level representation](https://github.com/apache/parquet-fo
| **`struct`** | `group` | | |
| **`list`** | `3-level list` | `LIST` | See Parquet docs for 3-level representation. |
| **`map`** | `3-level map` | `MAP` | See Parquet docs for 3-level representation. |
+| **`variant`** | `group` with `metadata` and `value` fields. `metadata` and `value` must not be assigned field IDs.| `VARIANT` | See Parquet docs for Variant encoding and Variant shredding encoding. |
When reading an `unknown` column, any corresponding column must be ignored and replaced with `null` values.
@@ -1239,6 +1256,7 @@ When reading an `unknown` column, any corresponding column must be ignored and r
| **`struct`** | `struct` | | |
| **`list`** | `array` | | |
| **`map`** | `map` | | |
+| **`variant`** | `struct` with `metadata` and `value` fields. `metadata` and `value` must not be assigned field IDs. | `iceberg.struct-type`=`VARIANT` | Shredding is not supported in ORC. |
Notes:
@@ -1285,6 +1303,8 @@ The types below are not currently valid for bucketing, and so are not hashed. Ho
| **`float`** | `hashLong(doubleToLongBits(double(v))` [5]| `1.0F` ￫ `-142385009`, `0.0F` ￫ `1669671676`, `-0.0F` ￫ `1669671676` |
| **`double`** | `hashLong(doubleToLongBits(v))` [5]| `1.0D` ￫ `-142385009`, `0.0D` ￫ `1669671676`, `-0.0D` ￫ `1669671676` |
+A 32-bit hash is not defined for `variant` because there are multiple representations for equivalent values.
+
Notes:
1. Integer and long hash results must be identical for all integer values. This ensures that schema evolution does not change bucket partition values if integer types are promoted.
@@ -1331,6 +1351,7 @@ Types are serialized according to this table:
|**`struct`**|`JSON object: {`
`"type": "struct",`
`"fields": [ {`
`"id": ,`
`"name": ,`
`"required": ,`
`"type": ,`
`"doc": ,`
`"initial-default": ,`
`"write-default": `
`}, ...`
`] }`|`{`
`"type": "struct",`
`"fields": [ {`
`"id": 1,`
`"name": "id",`
`"required": true,`
`"type": "uuid",`
`"initial-default": "0db3e2a8-9d1d-42b9-aa7b-74ebe558dceb",`
`"write-default": "ec5911be-b0a7-458c-8438-c9a3e53cffae"`
`}, {`
`"id": 2,`
`"name": "data",`
`"required": false,`
`"type": {`
`"type": "list",`
`...`
`}`
`} ]`
`}`|
|**`list`**|`JSON object: {`
`"type": "list",`
`"element-id": ,`
`"element-required": `
`"element": `
`}`|`{`
`"type": "list",`
`"element-id": 3,`
`"element-required": true,`
`"element": "string"`
`}`|
|**`map`**|`JSON object: {`
`"type": "map",`
`"key-id": ,`
`"key": ,`
`"value-id": ,`
`"value-required": `
`"value": `
`}`|`{`
`"type": "map",`
`"key-id": 4,`
`"key": "string",`
`"value-id": 5,`
`"value-required": false,`
`"value": "double"`
`}`|
+| **`variant`**| `JSON string: "variant"`|`"variant"`|
Note that default values are serialized using the JSON single-value serialization in [Appendix D](#appendix-d-single-value-serialization).
@@ -1480,6 +1501,7 @@ This serialization scheme is for storing single values as individual binary valu
| **`struct`** | Not supported |
| **`list`** | Not supported |
| **`map`** | Not supported |
+| **`variant`** | Not supported |
### JSON single-value serialization
@@ -1508,6 +1530,7 @@ This serialization scheme is for storing single values as individual binary valu
| **`map`** | **`JSON object of key and value arrays`** | `{ "keys": ["a", "b"], "values": [1, 2] }` | Stores arrays of keys and values; individual keys and values are serialized using this JSON single-value format |
+
## Appendix E: Format version changes
### Version 3
@@ -1517,7 +1540,7 @@ Default values are added to struct fields in v3.
* The `write-default` is a forward-compatible change because it is only used at write time. Old writers will fail because the field is missing.
* Tables with `initial-default` will be read correctly by older readers if `initial-default` is always null for optional fields. Otherwise, old readers will default optional columns with null. Old readers will fail to read required fields which are populated by `initial-default` because that default is not supported.
-Types `unknown`, `timestamp_ns`, and `timestamptz_ns` are added in v3.
+Types `variant`, `unknown`, `timestamp_ns`, and `timestamptz_ns` are added in v3.
All readers are required to read tables with unknown partition transforms, ignoring the unsupported partition fields when filtering.