Summary

XContentParser.getTokenLocation() returns an XContentLocation(lineNumber, columnNumber). The underlying Jackson JsonParser provides byte offsets via JsonLocation.getByteOffset(), but JsonXContentParser discards this information when wrapping the Jackson location. Exposing byte offsets would enable zero-copy extraction of sub-structures (objects/arrays) from the source byte array.

Motivation

The JSON_EXTRACT ES|QL function (#142375) extracts values from JSON strings. When the extracted value is an object or array, it currently uses XContentBuilder.copyCurrentStructure(parser) to serialize the sub-structure back to JSON — walking every token and rebuilding the string from scratch, even though the original bytes are already valid JSON in the source array.

With byte offsets, extraction becomes a direct array slice:

long start = parser.getTokenLocation().byteOffset();
parser.skipChildren();
long end = parser.getCurrentLocation().byteOffset();
builder.appendBytesRef(new BytesRef(bytes, offset + (int) start, (int) (end - start)));

This eliminates all intermediate parsing, string allocation, and JSON escaping for the sub-structure.

Proposed API Change

XContentLocation — add byteOffset with a backward-compatible constructor:

public record XContentLocation(int lineNumber, int columnNumber, long byteOffset) {
    public XContentLocation(int lineNumber, int columnNumber) {
        this(lineNumber, columnNumber, -1L);
    }
}

XContentParser — add getCurrentLocation() (the other method already exists):

XContentLocation getTokenLocation();    // already exists — starts populating byteOffset
XContentLocation getCurrentLocation();  // new — position just past the last consumed byte

Implementation Impact

The XContentParser hierarchy has 19 implementations. The change is concentrated in one place.

Leaf implementations (5):

Decorators (13): All transparent — delegate through FilterXContentParser.delegate(). Zero changes needed for 11 of 13. The two with overrides:

Test-only (1): ParameterizableYamlXContentParser — delegates, transparent.

Byte Slicing Feasibility by Format

Not all content types support raw byte slicing even with offsets available:

Consumers must check the content type before slicing. JSON and CBOR are safe; SMILE and YAML require the XContentBuilder.copyCurrentStructure fallback.