[00] Subset Fill, For developers
How Subset Fill works
Last updated
How Subset Fill turns an ACF Flexible Content field into a strict JSON Schema, and checks every value the model returns against your pasted text.
This page explains what Subset Fill does between Build from content and the rows appearing in the field: how it turns your Flexible Content field into a schema, how it splits and sends the content, and how it checks the answer word for word. The hooks named here are documented in full in the developer reference.
From pasted content to rows
A build is a series of requests to the REST route POST /sfcb/v1/build, one per part of the content. The user needs edit_post on the post being edited. Each request goes through the same steps:
Mapper::plan()reads the pasted HTML or plain text into blocks, builds the schema from the field and splits the blocks into chunks. It calls no provider.Mapper::map_chunk()sends one chunk to the provider chosen under Subset → Fill, with the schema as a strict structured-output format.- The rows that come back pass through the
sfcb_builder_resultfilter, then throughValidatorandSanitizer. - The response holds every row so far, with the flags, dropped rows and unplaced passages. The browser sends the rows back with the next chunk, and they’re checked again.
Long content is split at headings first, then between blocks, and inside a block only when one block is too long. Each chunk holds at most 1,500 words, which you can change with sfcb_chunk_words (the minimum is 100). A build takes up to 512,000 bytes of content (sfcb_max_content_bytes), and each user can make 60 build requests an hour (sfcb_rate_limit).
Nothing is saved on the server. When the last chunk is done, sfcb_builder_completed fires and the editor script adds the rows to the field, unsaved. The post changes only when someone clicks Update, and Undo build puts the field back as it was.
wp subset content-builder map runs the same plan, provider call and checks from a shell, and prints the rows as JSON without saving them. See WP-CLI in the developer reference.
The schema reader
SchemaBuilder::build() takes the Flexible Content field as acf_get_field() returns it and produces a JSON Schema with one property, rows. Each item of rows is an anyOf with one object per layout. A layout object has a layout property that’s an enum of the layout’s name, and a fields property with one entry per sub-field it can fill.
Every object is closed (additionalProperties false) and lists all its properties as required, because the strict structured-output modes of the providers expect that. Every value is nullable, so the model can leave a field empty when your content has nothing for it.
What the model is told about each field and layout
A field’s description is built from its label, its instructions with tags stripped, the handler’s own note, and, for a required field, an instruction to leave it null when the source has no matching text. A layout’s description combines its label, its Builder description (sfcb_description) and its limits.
The limits come from ACF’s own min and max for the layout, and from Builder max per page (sfcb_max) when that’s stricter than ACF’s max. They’re written as “Use exactly once”, “Use at least 2 times” or “Use at most 3 times”. Builder position (sfcb_position) adds “Place at the start” or “Place at the end”. The field’s own min and max rows become minItems and maxItems on rows.
Supported field types
Each ACF field type is read by a handler that implements FieldHandler. HandlerRegistry::defaults() registers these:
| Field type | Value in the schema |
|---|---|
text, textarea, email, url | A string, limited by the field’s character limit when it has one. |
select, radio, checkbox, button_group | One of the field’s choices, or a list of them for checkboxes and multi-selects. |
wysiwyg | An HTML string. |
number | A number. |
true_false | A boolean. |
link | An object with url and title. |
image | The src of an image in the source. |
group | An object of its sub-fields. |
repeater | A list of objects of its sub-fields, with the repeater’s min and max. |
Pro adds handlers for post_object, page_link, relationship, taxonomy, nested flexible_content and clone. Nested fields are capped by sfcb_pro_max_schema_depth (default 10 object levels) and sfcb_pro_max_nested_flexible (default 6 per build).
Unsupported and skipped fields
A sub-field is left out of the schema when no handler is registered for its type, or when its handler returns an empty schema (for example, past a depth limit). It’s listed in the response’s unsupported array with its key, name, label, type and path, and the editor marks it Fill manually (not supported yet).
A sub-field whose Content builder setting is Always leave for a person (sfcb_fill_mode set to skip) is left out too, listed in skipped, and marked Left for you.
Changing the schema
To support another field type, or replace a built-in handler, filter sfcb_builder_field_handlers. It receives the handlers keyed by ACF field type, and only string keys with a FieldHandler value are kept.
add_filter( 'sfcb_builder_field_handlers', function ( array $handlers ): array {
$handlers['color_picker'] = new My_Color_Handler();
return $handlers;
} );
To change the finished schema, filter sfcb_builder_schema. The same schema validates the answer, so it has to stay a valid strict-mode schema. See Change the schema and Add a field type.
The verbatim guard
The system prompt tells the model to copy text exactly, place each passage once and set a field to null when nothing matches. You can add to the per-chunk prompt with sfcb_builder_prompt, but the system prompt is fixed. The prompt is a request. Validator is what enforces it, on every row, before anything reaches the editor.
How text is compared
SourceIndex holds a normalised copy of the whole source. Text::normalize() strips markup and entities, collapses whitespace, and treats typographic variants as the same character: curly and straight quotes, guillemets, en and em dashes and hyphens, and an ellipsis and three full stops. Case and spelling aren’t normalised, so “Contact us” and “contact us” are different text.
A plain text value is kept if its normalised form appears anywhere in the normalised source. URLs and email addresses must match a link href, an image src or the text of the source. A number must appear in the source, with thousands separators ignored. Choices must be one of the field’s options, and numbers must fit the field’s range.
An HTML value is checked in pieces:
- Comments, and elements that hide text such as
script,styleandform, are removed with their contents. Only the tags and attributes a source can have are kept. - Images whose
srcisn’t in the source are removed. Alt text is kept only if it’s in the source. - Links to addresses that aren’t in the source are unwrapped, so the text stays and the link goes.
- The HTML is split after each paragraph, list item, heading, quote and definition. A piece stays if its text is in the source, or if every sentence in it is.
What happens on a mismatch
The plugin doesn’t ask the model again. A value that fails is cleared to null and flagged with a reason from ValidationResult: invented, invalid, too_long or out_of_range. An HTML value that lost some pieces keeps the rest and is flagged partly_invented, which the editor shows as “Some of this text wasn’t in your content and was removed. Check it.”
Whole rows are dropped when they name a layout the field doesn’t have (unknown_layout), or when they’d go over the field’s max rows or a layout’s max (over_limit). Dropped rows are counted in the summary bar.
After the last chunk, Validator lists the source sentences that weren’t placed in any kept value, grouped into runs within a paragraph, along with image sources that weren’t used. These are the passages behind Show leftovers, in your original wording.
Images
An image value that passes the source check goes to Sanitizer, which looks for the image in the Media Library. Fill never downloads images. If there’s no match, the field is flagged not_in_library. If ACF’s own attachment checks reject the match (file type, dimensions or size), it’s flagged image_not_allowed with ACF’s message.
Filters can’t skip the check
sfcb_builder_result sees the model’s rows before validation, so whatever it returns is still checked. sfcb_build_response runs after validation. If a callback changes rows there, the changed rows are validated and sanitised again before the response goes out. Values of a field type the builder doesn’t know pass through sfcb_sanitize_value, which leaves the field empty unless a callback returns a value.