Introduces a new LogicalType: FILE

LogicalTypes.md

@@ -635,7 +635,133 @@ The type has two type parameters:
 
 The sort order used for `GEOGRAPHY` is undefined. When writing data, no min/max
 statistics should be saved for this type and if such non-compliant statistics
-are found during reading, they must be ignored. 
+are found during reading, they must be ignored.
+
+### FILE
+
+`FILE` annotates a group that represents a reference to a range of bytes, which may
+be stored inline in the value, elsewhere within this file, or in an external file. It
+is intended for use cases such as storing file inventories, manifests, and unstructured
+data references (e.g., images or audio files stored in object storage).
+
+The annotated group may contain the following fields, identified by name. Field IDs
+may also be used for projection. All fields are optional:
+
+| Field          | Type       | Required |
+|----------------|------------|----------|
+| `path`         | STRING     | No       |
+| `offset`       | INT64      | No       |
+| `size`         | INT64      | No       |
+| `content_type` | STRING     | No       |
+| `checksum`     | STRING     | No       |
+| `inline`       | BYTE_ARRAY | No       |
+
+A value resolves to bytes determined by `inline` / `path` / `offset` / `size`;
+`content_type` and `checksum` are metadata describing whatever is resolved.
+
+#### Fields
+
+##### path
+
+An opaque path string to an external file (e.g., `s3://bucket/file.jpg`). No special
+encoding (e.g., URI encoding) is applied on top of the user provided data. If `path` is absent,
+the value refers to this file (a self-reference).
+
+##### offset
+
+A byte offset indicating the start of the byte range within the referenced data.
+If not provided, readers must treat the value as 0.
+If provided and non-zero, readers must seek to this offset to retrieve the referenced data.
+
+##### size
+
+The byte length of the referenced data. Must be zero or a positive integer if provided.
+A value of 0 indicates empty referenced data. If not provided, the range runs to the end
+of the referenced data.
+
+##### content_type
+
+The media type (MIME type) of the resolved bytes (e.g., `image/png`).
+
+##### checksum
+
+A self-describing integrity token for the resolved bytes, of the form
+`<algorithm>:base64(<digest bytes>)`. It generalizes the storage-system eTag. The
+recognized algorithms are:
+
+| Algorithm | Notes                                                          |
+|-----------|----------------------------------------------------------------|
+| `ETAG`    | the object-store eTag — equality-only, not recomputable        |
+| `MD5`     | the usual S3/HTTP eTag and Content-MD5                         |
+| `CRC32`   | Parquet's page-checksum algorithm (gzip/zlib)                 |
+| `CRC32C`  | common in object stores, hardware-accelerated                  |
+| `SHA-256` | e.g. S3 additional checksums                                  |
+
+`checksum` applies to the resolved bytes, except for `ETAG`, which is the
+object-store eTag for the whole file referenced by `path`.
+
+##### inline
+
+The referenced bytes stored inline in the value. If `inline` is set, it supplies the
+bytes and any locator fields (`path`, `offset`, `size`) that are present are provenance
+only.
+
+#### Resolution
+
+A value resolves to bytes based on which of `inline`, `path`, `offset`, and `size` are
+set:
+
+| `inline` | `path` | `offset` | `size` | Resolves to                                  |
+|----------|--------|----------|--------|----------------------------------------------|
+| set      | –      | –        | –      | the inline bytes                             |
+| –        | set    | –        | –      | whole external file at `path`                |
+| –        | set    | set      | –      | external `path`, `[offset, EOF)`             |
+| –        | set    | –        | set    | external `path`, `[0, size)`                 |
+| –        | set    | set      | set    | external `path`, `[offset, offset + size)`   |
+| –        | –      | set      | –      | this file, `[offset, EOF)` (self-reference)  |
+| –        | –      | –        | set    | this file, `[0, size)` (self-reference)      |
+| –        | –      | set      | set    | this file, `[offset, offset + size)` (self-reference) |
+| –        | –      | –        | –      | nothing — invalid                            |
+
+A self-reference typically points within the same Parquet file using `offset` and
+`size`; the bytes are written between column chunks and are not otherwise referenced by
+the footer. A self-reference is the absence of `path`, never an absolute path back to
+the current file, so a file containing self-references is renamed or relocated as a
+single unit.
+
+The referenced bytes are compressed with the same `CompressionCodec` as the one
+specified for the `inline` column.
+
+#### Validation
+
+* A value must resolve to some referenced data. If none of `inline`, `path`, `offset`, or
+  `size` is set, the value does not resolve and is invalid; use column nullability to
+  represent a null value.
+* If `inline` is set, it supplies the bytes; producers may instead treat `inline` and the
+  locator fields as mutually exclusive.
+* Field names within a `FILE`-annotated group must not be renamed.
+* Additional metadata about the file (e.g., modification timestamp) should
+  be stored adjacent to this struct by engines or table formats, not inside it.
+
+Statistics may be collected for the individual fields of a `FILE`-annotated group
+according to the sort order of each field's logical type.
+
+This is an example `FILE`-annotated group in Parquet:
+
+```
+optional group my_file (FILE) {
+  optional binary path (STRING);
+  optional int64 offset;
+  optional int64 size;
+  optional binary content_type (STRING);
+  optional binary checksum (STRING);
+  optional binary inline;
+}
+```
+
+*Compatibility*
+
+`FILE` has no corresponding `ConvertedType`.
 
 ## Nested Types
 

src/main/thrift/parquet.thrift

@@ -468,6 +468,33 @@ struct GeographyType {
   2: optional EdgeInterpolationAlgorithm algorithm;
 }
 
+/**
+ * File logical type annotation
+ *
+ * Annotates a group that represents a reference to a file, or to a range of
+ * bytes that may be stored inline, elsewhere in this file, or in an external
+ * file. All fields are optional and are identified by name:
+ *   - path (STRING): an opaque location string (e.g. s3://bucket/file.jpg);
+ *     if absent, the value refers to this file (self-reference)
+ *   - offset (INT64): start of the byte range; if absent, treated as 0
+ *   - size (INT64): byte length of the referenced data; if absent, the range runs to
+ *     the end of the referenced data
+ *   - content_type (STRING): media type (MIME) of the resolved bytes
+ *   - checksum (STRING): an algorithm-tagged integrity token for the resolved
+ *     bytes, of the form "<algorithm>:base64(<digest>)"
+ *   - inline (BYTE_ARRAY): the referenced bytes stored inline in the value
+ *
+ * A value resolves to bytes determined by inline / path / offset / size; if
+ * inline is set it supplies the bytes and any locator fields are provenance
+ * only. A value with none of inline, path, offset, or size set does not
+ * resolve to any referenced data and is invalid (use column nullability for nulls).
+ * content_type and checksum are metadata describing whichever bytes resolve.
+ *
+ * See LogicalTypes.md for details.
+ */
+struct FileType {
+}
+
 /**
  * LogicalType annotations to replace ConvertedType.
  *
@@ -501,6 +528,7 @@ union LogicalType {
   16: VariantType VARIANT     // no compatible ConvertedType
   17: GeometryType GEOMETRY   // no compatible ConvertedType
   18: GeographyType GEOGRAPHY // no compatible ConvertedType
+  19: FileType FILE           // no compatible ConvertedType
 }
 
 /**