Designing AI Import
Load this card when a page's values come from a document: declaring
LLMDocTrans or LLMDocField, a classifier, validation facts or blank values,
or adding a field to an importing page. Its rules are generated from the
AI design obligations,
the document transformation contract
and the LLM request contract, which own
them. The annotation inventory gives each
annotation's Rust and TypeScript spelling.
Order of work
- Decide which fields are import targets, and keep values only the person
supplies outside what an import replaces (
app.import.*,doctrans.nullable.*). - Declare the form or classifier and its arguments (
doctrans.form.*,doctrans.action.*,doctrans.args.*,doctrans.validation.*,doctrans.classifier.*). - Select the result fields and Union variants (
doctrans.field.*,doctrans.union.*,doctrans.protected.*). - Declare each selected field's blank behavior (
doctrans.blank.*). - Check List, array and categorized imports and the limits
(
doctrans.array.*,doctrans.categorized.*,doctrans.request.*,doctrans.result.*,doctrans.schema.*,doctrans.import.*,llm.*), then compile with Studio and fix every reported rule.
Rules to apply
Studio does not check these rules. Each is quoted from its owner.
AI access in every design step
Owner: app-contract.md#ai-access-in-every-design-step
app.import.printed-fields(judgment): Every field whose value is printed on that document or its attached statements is an import target, including fields in sections that appear only conditionally.app.import.records-not-targets(judgment): A value that only the person's own records hold is not an import target; its description says where to find it.app.import.classify-new-fields(judgment): A new field on an importing page is classified when it is added.app.import.preserve-person-data: Nothing an import can set may hold data only the person supplies: a composite on an import path is not Nullable, because a null result replaces it, and a Union whose variant the import chooses carries only document values, because a variant change discards the old payload; keep person-supplied values in a record the import does not select.
Request
Owner: llm-document-transformation.md#request
doctrans.nullable.domain-model(judgment): Nullable must reflect the form's actual data model. App authors must not make a destination Nullable solely to accommodate document recognition.
App Schema authoring
Owner: llm-document-transformation.md#app-schema-authoring
-
doctrans.action.per-occurrence: Each occurrence of that struct in an editable Request or SubscriptionRequest gets its own AI Import action, except that categorized layout centralizes the actions of its classifier subtree. A screen can therefore contain several independent forms, including repeated rows of one form type. Selected files are temporary editor input; they do not require a Bytes field in the App Request. When a form's row is promoted or suppressed, its action follows the row action placement rule. -
doctrans.args.instruction:Argument Meaning instructionRequired App-authored task text. Tell the model what to read, what a genuinely blank box means, and when to report an error. The Hub sends it separately from facts and result schema, with no separate instruction-size limit. -
doctrans.args.multiple-inputs(judgment):Argument Meaning accept_multiple_inputsOptional Boolean, default false. One file is the normal case. Settrueonly when a logical document may span several selected files; the Hub limit is eight. -
doctrans.field.allow-empty-default: TheallowEmptydefault istruefor a non-Nullable Number andfalsefor String, Boolean, and Enumeration. -
doctrans.field.recursive-selection: Within each selected Table, including a List item Table, marking one or more direct children selects only those children for that Table's result object. If none of that Table's direct children is marked, all its unprotected children are selected. Mark each intermediate composite whose descendants are selected. A nested scalar marker also sets its blank rule. -
doctrans.union.variant-choice: A selected Union imports its variant choice, and a variant's payload fields only when they are marked. The all-children default above does not apply to Union payloads: a variant's payload usually holds facts the chosen option leads to, not values printed on the document. -
doctrans.union.marked-variants: Marking one or more direct variants of a selected Union limits its result schema to those variants; with no marked variant, all unprotected variants remain available, subject to ordinary choice constraints. Marked variants must be capable of producing a result. -
doctrans.union.single-value-payload: A single non-Table value, such as a Rust tuple variantAllocated(i64), has no field to mark; that value is the variant's one payload field, named by the variant, and it is always marked. A Nil (unit) variant has no payload field. -
doctrans.protected.output-exclusion: Hidden, Fixed and Secret fields are excluded from LLM output, including their complete subtrees; together they are protected content. -
doctrans.result.schema-limits: This feature adds no arbitrary Table depth, List length, or integer-width restriction; actual schema and wire limits apply, including the 64 KiB output-schema limit. A configured provider that rejects a schema returns a normal request error. -
doctrans.validation.hidden-facts: The selected validation Table may be Hidden and may receive its value through normal Request construction, CopyFrom, or EditRequest. Its children may be complete typed values using the same recursive JSON projection below. An absent or incomplete required value blocks the action. Declared Nullable facts retain their null meaning. -
doctrans.validation.fact-names: Fact names need no relationship to result names: the W2 example verifiesyearwithout returningyear. The model checks those facts against the document; the Hub does not independently verify them.
Blank values and output types
Owner: llm-document-transformation.md#blank-values-and-output-types
doctrans.blank.number-string: A non-Nullable Number normally uses a JSON string result because the form's box might be blank even though the App's data field is required. The model returns printed numeric text for a legible amount and exact""for a clearly blank box. The client strictly converts nonempty text to the destination Number type. Exact""applies the field's effective, typed SchemaDefault. Thustips: numberwith@LibertasDefault(0)stays required and stores zero for a blank tips box. The schema sent to the model does not contain a JSON Schemadefaultkeyword or expose the App's Default value.doctrans.blank.string-nonempty: A String with defaultallowEmpty=falserequires a nonempty result.doctrans.blank.enumeration-names: An Enumeration uses a JSON string for the printed codes described in the conversion table. The client maps an exact offered code to its declaredFixedinteger value, or to its ordinal when noFixedis declared. The model never invents a code from its meaning or supplies an arbitrary integer. ExplicitallowEmpty=truealso permits exact""and applies the effective Enumeration Default.doctrans.blank.no-invented-default(judgment): If a Number has no meaningful Default, an App author may setallowEmpty=falseonly when the form establishes that its box cannot be blank; its output then uses JSONintegerornumberas appropriate and a blank box is an error. Otherwise, leave that field out of automatic extraction until its blank semantics are known. Do not invent a zero Default for this purpose.doctrans.authoring.nullable-domain-choice: Nullable remains a domain-model choice, never a document-recognition trick. CodeBots must not make a field Nullable solely to support this action.doctrans.nullable.null-clears: A truly Nullable result permits JSONnullfor a genuinely blank value;nullclears the destination. A non-null Nullable Table uses its selected child object shape; a non-null Nullable List uses its selected item shape. A Nullable Number uses JSON string or null and converts its non-null numeric text strictly. Nullable Enumeration uses an offered printed code or null.
Declared blank value
Owner: llm-document-transformation.md#declared-blank-value
doctrans.blank.declared-value:LLMDocField(blank=VALUE)declares the value that an exact""result applies when the field's box is blank on the document.VALUEis spelled exactly like aDefaultliteral for that field:$nullon a Nullable field, a number literal on a Number, a quoted string, an Enumeration member name, or a Union variant name, with$NAMEconstant references wherever Default allows them. For example,blank=$nullclears a Nullable field when its box is blank,blank=0stores zero, andblank=ShortTermon a Union chooses that variant. The portableLLMDocFieldattribute value isblank:followed by the literal in its portable Default encoding, such asblank:$null,blank:0, orblank:ShortTerm; the other portable values areautofor the bare marker,true, andfalse.doctrans.blank.default-shorthand:allowEmpty=trueremains the shorthand for a blank that applies the field's SchemaDefault. A field with neither keeps the rules above. Studio rejects an invalidblankat the marker's source location.doctrans.blank.optional-text: For ordinary optional text whose domain meaning is “blank when not supplied,” use a non-Nullable String with an empty Schema Default and explicitallowEmpty=true. In Rust, combine#[libertas_default("")]with#[libertas_llm_doc_field(allow_empty = true)]; the bare field marker still defaults tofalsefor String. Permit length zero in its size bounds. Describe the manual answer as “Leave it empty if absent” and tell the model to return exact""for genuinely missing text. Reserve JSONnullfor truly Nullable destinations.doctrans.blank.unreadable-is-error(judgment): Unreadable text is an error, not evidence that the text is absent. Follow the type-selection guidance when manual input and an internal record use different representations.doctrans.import.printed-values: AI Import reads the printed document. Return code letters as printed, dates as printed, amounts as printed, and each address as one text block with its printed line breaks. Do not expand codes into their meanings, normalize dates or amounts, add an unprinted country, include a telephone number in an address, or repeat a separately selected party name in its address. Keep identifiers as text, including leading zeros. The client owns deterministic conversion to the declared stored types; App instructions identify the printed boxes rather than teach storage encodings.
Complete JSON projection and client conversion
Owner: llm-document-transformation.md#complete-json-projection-and-client-conversion
-
doctrans.schema.descriptions.authoring: Supply locating labels and domain import instructions. The model reads printed values; do not require it to interpret a code or convert to a storage representation. The platform owns schema generation and conversion. -
doctrans.conversion.nullable-domain-choice:Libertas value Model JSON and client conversion Nullable Add null to that value's JSON schema; a returned null clears the typed value. Never add Nullable merely for recognition. -
doctrans.schema.no-template: Display Template presentation, including aformatpattern, never reaches the model. -
doctrans.blank.semantic-number-defaults: Number annotations such as DateOnly, Money, TimeInterval, EnumSource, and Bitflags keep the Number default ofallowEmpty=true; their typed Default is applied locally for exact"". Other semantic scalar types default toallowEmpty=falseand may explicitly enable it with a meaningful Default.
Array import
Owner: llm-document-transformation.md#array-import
doctrans.array.inside-list: When the annotated struct occurrence lies anywhere inside an editable List item, directly or through nested Tables and Union payloads, its AI Import action imports an array. The struct type of the occurrence the action is on decides what is imported: only forms of that type.doctrans.array.duplicate-instruction(judgment): The App'sinstructionnames what a duplicate looks like for its form (for example a tax form's Copy B, Copy C and Copy 2 printed on one page); the client's appended text stays generic.doctrans.array.single-outside-list: A struct occurrence outside any List, or inside a List whose membership is ReadOnly, keeps the single import.
Declared duplicate identities
Owner: llm-document-transformation.md#declared-duplicate-identities
doctrans.duplicate-identity.equality: Within the same form and struct position, converted identity values compare as an ordered typed tuple, without text normalization. A whole List compares its complete ordered value, including length and every typed item; a whole Union compares its selected variant and complete typed payload. Changing an item, its order, a variant or its payload makes that component unequal. Null is a value; a null containing Table supplies null for its selected descendant. An unanswered local identity value does not equal a supplied null answer. An appended form whose tuple equals an existing item's or an earlier imported form's is one duplicate, even when other imported values differ. Keep the existing or first imported paper unchanged and include the skipped copy in the review's duplicate count. Without a declaration, retain exact imported-value equality. The first result of an array import still replaces its current occurrence; all further elements and categorized imports use this duplicate rule.
Categorized import
Owner: llm-document-transformation.md#categorized-import
doctrans.classifier.definition: Classifier rule. AnLLMDocTransTable is a classifier if and only if all its variants areLLMDocTransstructs. Its variants are its import positions: each selected field, each selected List's item, and, in an item Table, its one marked form or each variant of its one marked Union (the item's other fields, such as an owner, keep their normal initialization). A variant may itself be a classifier, so classifiers nest, typically one root classifier with one classifier per category. Every otherLLMDocTransTable is a form, with the meaning described above; anLLMDocTransa form encloses keeps only its own action.doctrans.classifier.no-marked-child: Selection is the ordinary rule above (the marked direct children, or all unprotected children when none is marked); a form's requirement to mark at least one direct child does not apply to a classifier.doctrans.classifier.instruction(judgment): Arguments. On a classifier,instruction(required) says what counts as one document, what to leave out, and how to recognize duplicate copies; the client appends the generic classification text below.doc_typefilters the selectable files as for a form.doctrans.classifier.file-selection: A classifier always accepts several files;doctrans.classifier.form-arguments: Each form keeps its ownvalidation, used when its kind is imported; itsdoc_typeandaccept_multiple_inputsgovern only its own action.doctrans.classifier.kind-constraints: A kind is offered only while the Union's ordinary choice constraints (Hidden, Fixed,ConstrainedBy) permit it for a new item at its position. A kind inside a List is a list kind, and the nearest List enclosing it is its category List. A form that is a classifier's variant itself, outside any List, is a single-document kind, such as a passport or a birth certificate: the Request holds one occurrence of it.doctrans.classifier.kind-names(judgment): A kind is named for the model by its variant's (or, for a one-kind List, its struct's) localized display name and description, with the display names of the classifiers between the importing classifier and the kind. Write them to say exactly what the document is, such as "Form 1099-S for the sale of your main home". The root classifier offers every leaf kind; a category classifier offers its own.doctrans.categorized.apply.authoring: Rely on the normal import apply and review flow; importing changes the editor without submitting the App request.
Rules Studio enforces
Studio checks these rules and reports errors or warnings as their owners specify. The owner holds the full rule.
App Schema authoring
Owner: llm-document-transformation.md#app-schema-authoring
doctrans.form.declaration: LLMDocTrans goes on a named Table struct, a form whose direct result children carry LLMDocFielddoctrans.validation.every-occurrence: The validation path resolves to a Table in every editable occurrence; calculation-only and protected occurrences need no unused factdoctrans.args.doc-type: The doc_type filter intersected with PDF, PNG, JPEG and WebP must not be emptydoctrans.args.form-date-order: form_date_order is MonthDayYear or DayMonthYear on a form declaration; a form with no DateOnly result field draws a warningdoctrans.field.selection: LLMDocField marks a direct result child or a descendant of a selected compositedoctrans.form.mark-a-child: At least one direct child of an annotated form root Table must carry LLMDocFielddoctrans.protected.hidden-fixed-excluded: LLMDocField directly on Hidden, Fixed or Secret content is invaliddoctrans.protected.composite-omitted: LLM output omits composites containing only protected content; marking one directly is invaliddoctrans.validation.no-secret: An LLMDocTrans validation Table contains no Secret value
Blank values and output types
Owner: llm-document-transformation.md#blank-values-and-output-types
doctrans.blank.allow-empty-requires-default: allowEmpty=true requires a real Schema Default on a non-Nullable scalar represented as a JSON stringdoctrans.blank.allow-empty-hosts: Boolean rejects allowEmpty=true; Table, List and Nil do not use allowEmpty; a Union permits true only with a Default variantdoctrans.blank.endpoint: Endpoint results cannot enable allowEmpty=truedoctrans.nullable.no-allow-empty: allowEmpty is inapplicable to Nullable fields; blank remains applicable
Declared blank value
Owner: llm-document-transformation.md#declared-blank-value
doctrans.blank.valid-values: blank needs a selected scalar, Enumeration or Union field and a value valid for it; Bytes and identities take only $nulldoctrans.blank.not-with-allow-empty: blank cannot combine with allowEmpty
Declared form codes
Owner: llm-document-transformation.md#declared-form-codes
doctrans.form-code.declaration: FormCode is a nonempty code on an Enumeration member, Union variant or nonzero Bitflags flag, unique among its siblings
Declared duplicate identities
Owner: llm-document-transformation.md#declared-duplicate-identities
doctrans.duplicate-identity.paths: A form's duplicate_identity names distinct imported scalar or whole List/Union values through self-relative Table paths
Categorized import
Owner: llm-document-transformation.md#categorized-import
doctrans.classifier.multiple-files: A classifier takes no validation path or accept_multiple_inputs = truedoctrans.classifier.item-shapes: A List under a classifier holds a Union of forms, a Table with one marked Union or form, or a formdoctrans.classifier.placement: A classifier is used in an editable Request or SubscriptionRequest and has at least one kinddoctrans.classifier.readonly-list-and-single-kinds: Studio refuses a ReadOnly classifier List and warns when a single-document kind encloses import declarations
Document duplicate identity metadata
Owner: schema.md#document-duplicate-identity-metadata
attr.llmdoctrans.config-shape: LLMDocTrans config has four ordinary keys, an optional duplicate_identity string and an optional form_date_order string