API Payload Classification

API payload classification finds the sensitive data in one payload and reports each one as a finding: the classifier that matched, where the value sits in the text, and what AI Data Shield did about it.

The position is a span – the offsets where the value starts and ends. The span is what lets Shield replace exactly that run of characters and leave the rest of the payload untouched.

What a Finding Reports

A finding carries no rate or score. A classifier either matched this text at this position or it did not.

Every occurrence is its own finding, so a value appearing twice produces two findings with two spans.

Shield reports every finding, including the ones it left alone. A finding Shield policy did not protect is still listed, marked as having had no action taken – so your application can tell text that held nothing sensitive from text that held something Shield was not permitted to protect.

Note

A classification report on a connected data source carries a match percentage and a Match Confidence score, both derived from a classifier’s performance across sampled rows. Neither appears on a finding, because a payload has no rows to sample.

Which Classifier Conditions Apply

A classifier contributes a finding only if a single piece of text gives its conditions something to locate. A condition that reads a column’s name, declared size, or schema location has nothing to read. A Data Length condition measures values to describe a column rather than to find one inside text. A Snowflake Native condition reads another engine’s classification of a column. None of the three can point at a value in a payload.

Condition type	On a payload
Regular expression	Applies
Google DLP	Applies
Amazon Comprehend	Applies
Column Name	Does not apply
Data Length	Does not apply
Column Size	Does not apply
Data Location	Does not apply
Snowflake Native	Does not apply
Column Content	Cannot produce a finding

A condition that does not apply is not an error – ALTR skips it, and the classifier can still match on its remaining conditions. A classifier with nothing evaluated never matches, and ALTR rejects a collection with no usable classifiers – when you add it to an application, and again on any protect call that names it.

Column Content is evaluated on a payload, but it never produces a finding on its own, because it describes the format data is in rather than the data itself. ALTR detects the format once, for the payload as a whole, and uses the result to confirm or discard what the classifier’s other conditions found. Its Match Threshold has no effect on a payload, since a payload is a single piece of text rather than a set of sampled values to take a share of.

Sampling settings are inert for the same reason: sample size, Minimum Match Threshold, and processing location all describe how ALTR reads rows out of a data source, and a payload arrives whole.

A regular expression is evaluated against the payload as a whole rather than against individual values within it.

Two further differences apply to a classifier written for a database. A negated condition never produces a finding, so a classifier whose only signal is negated counts as unusable against text. And the comparator on a regular-expression condition is not used here – every one is evaluated as a pattern match.

Where the Payload Goes

A regular expression is evaluated inside ALTR. A Google DLP or Amazon Comprehend condition sends the submitted text to that service for inspection, under ALTR’s own credentials – there are no cloud credentials of yours to configure. Classification is the only step that uses those services. Tokenizing, storing, and restoring values happen entirely inside ALTR.

Collections on a Protect Call

Each protect call runs exactly one collection – the one its client was constructed with. The classifiers in it are the complete set ALTR evaluates.

An application’s collection list is not an evaluation set. Allowed collections limits which names that application may use; it does not run several collections together.

When Two Classifiers Find the Same Value

Overlapping findings resolve to one, so a span is never protected twice. The longest span wins.

Identical spans are handled differently from overlapping ones. When two classifiers produce the exact same span, Shield keeps one finding but carries both classifiers’ tags onto it and records both names – otherwise a policy rule keyed on the losing classifier’s tag would never fire against that value. When spans overlap without being identical, the shorter finding is dropped and its tags go with it.

Size Limits

Two size limits apply to a protect call, one on the request and one on an individual value:

• A protect request carries at most 500,000 bytes of text. Split anything larger.
• A tokenized value is at most 65,536 bytes. A longer one is left in the clear and reported as having had no action taken, rather than failing the call. Masked findings have no limit, because ALTR does not store them.