scan returns an ordered list of findings. Each finding identifies what was
detected, the exact source text, its location, and the detector that produced
the result.
Finding fields
Rule-based built-in detectors currently omit confidence.
Range semantics
Every range is:- zero-based;
- end-exclusive;
- explicitly named for its coordinate system;
- relative to the exact input text, without implicit Unicode normalization.
👋 jane@example.com, the email begins after an emoji and a space.
The same span has different offsets in each coordinate system:
JavaScript strings use UTF-16 indexing, so Node.js and browser/WASM expose a
range that works directly with
String.prototype.slice:
Supplied findings
transform accepts caller-supplied findings but validates them before changing
text. The entire request fails when a finding is empty, reversed, out of bounds,
misaligned with a character boundary, inconsistent across coordinate systems,
or does not select its declared matched_text.
JavaScript callers do not need to provide the derived utf16Range field when
supplying a finding to transform.
Duplicates and overlaps
Exact duplicate findings collapse into one result before transformation. Overlapping findings are resolved deterministically using structural span, length, confidence when both values are present, source position, entity type, and detector provenance. Selected transformations are returned in source document order.Missing confidence
Omitted confidence means unknown; Core does not assign it a score of zero. Comparing confidence only when both values are present can produce conflicting preferences across three or more overlapping findings. Core preserves its existing pairwise selection behavior in these cases rather than changing which text gets protected through sorting. When overlaps exist and an equal-length group mixes scored and unscored findings, overlap selection uses a compatibility fallback that can take quadratic time. Length here means Unicode code points. Disjoint findings and findings produced exclusively by the built-in detectors, including structured PERSON, use the faster selection path.Structured findings
scan_structured / scanStructured returns located findings with path and
finding fields. The path is an RFC 6901 JSON Pointer. Every range in the nested
finding addresses the decoded string value at that path, not serialized JSON.
Structured transformation/restoration records follow the same field-local rule
for source and output strings. See person-field discovery.