Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
Current model-key correction — 8 November 2026. The preserved examples below contain historical camelCase record-type/field keys. Do not copy those keys into the current editor or API: use record type leave_request and the lowercase field keys in the current model worksheet, including request_id, employee_id, manager_id, start_date, end_date, requested_days and decision_comment. Form, rule and case input names are separate declarations; map them explicitly rather than mechanically renaming every input. The preserved body remains historical source material, not a current executable model payload.
Collection-Plan Record Member Catalog
Learn the model before writing a plan
A collection plan has two different correctness questions. Its JSON codec answers whether the grammar, variants and required fields are well formed. The member catalog/type checker answers whether those paths, source versions, cardinalities and value kinds mean something in the actual published workspace. Passing JSON parsing never answers the second question.
Start with the source catalog, record the exact type/member identities and declare every runtime source. A record type such as leave:leaveRequest comes from model/type keys; a field member such as leave:leaveRequest:field:requestId comes from that published type’s member metadata. Use returned identities rather than rebuilding them from visible names. The permission/sensitivity metadata describes the contract; it does not itself grant data or AI-disclosure access.
| Authoring decision | What to record | Why it matters |
|---|---|---|
| Which collection? | root, rootKey, rootRef and exact type reference |
Separates a named input, data source and current-item collection. |
| Which release? | sourceVersion and any supported publication pin |
Prevents a stale member from being silently rebound. |
| Can it be absent? | nullable, explicit nullPolicy |
Distinguishes an absent collection treated as empty from an error. |
| Which item? | Stable item alias and item type | Controls where terminal paths resolve. |
| Which operation? | Ordered transforms and terminal | Filtering/sorting/limiting a collection is distinct from its final COUNT/PROJECT/aggregate result. |
| Which authorization? | Owning published model and actual read/render service | A client declaration or metadata flag cannot authorize disclosure. |
For new authors, work through discovery, a count, a relationship projection and a stale-version refusal in that order. The reference below retains the exact catalog/semantic details.
Worked examples
Example DATA-COLLECTION-01 — Read a catalog without confusing metadata with records
Scenario and inputs. Nadia prepares a permitted leave model with a published leaveRequest type and opens a collection-plan authoring surface in people-ops. She needs to find fields and references, not inspect employee request values. The catalog request below deliberately has no source declarations; it is a complete catalog body and must not be mistaken for a runtime collection binding.
Procedure. 1. Authenticate as the actual builder and select the authorized workspace. 2. Send POST /api/data-models/record-member-catalog with the body. 3. Locate the returned permitted type and record its typeRef, version, member IDs, value types, cardinalities, nullability and sensitivity metadata. 4. Choose only the fields needed for the planned view. 5. Before a runtime plan is checked, add its actual source declarations rather than assuming type discovery declared them.
{
"sources": []
}
Expected result. The response is a metadata catalog with types and sources; it does not contain sample/default field values or business rows. An empty sources list means source resolution remains unknown even when a matching type exists.
Failure and recovery. A missing or ambiguous type is not permission to invent its reference or import a similarly named type from another workspace. Check published metadata and current access with the owning model author. Rebuild the catalog only after the actual source identity is established.
Sources. RecordMemberCatalogController.java, CollectionPlanTypeChecker.java.
Example DATA-COLLECTION-02 — Count a declared input collection with explicit null behavior
Scenario and inputs. A form receives an already authorized array requests containing two synthetic leave requests. Nadia wants a count of that array, not a global database total. The example is a complete collection-plan value to be embedded at a compatible property, not a complete screen or an authorization-bearing catalog response. Substitute the actual published type/version when using it.
Procedure. 1. Declare input:requests against the exact permitted leave:leaveRequest type/version in the authoring catalog. 2. Keep the plan’s source coordinates identical to that declaration. 3. Choose EMPTY only if the product meaning of a missing collection is an empty list; use the supported error behavior when absence indicates a missing mandatory input. 4. Validate the plan structurally and semantically, then embed it in its actual supported screen property. 5. Test two rows, an empty list and a missing source separately.
{
"kind": "collection-plan",
"version": 1,
"source": {
"root": "input",
"rootKey": "requests",
"rootRef": "input:requests",
"typeRef": "leave:leaveRequest",
"sourceVersion": 1,
"cardinality": "MANY",
"nullable": true,
"nullPolicy": "EMPTY",
"segments": []
},
"item": {
"id": "request",
"typeRef": "leave:leaveRequest"
},
"transforms": [],
"terminal": {
"kind": "COUNT"
}
}
Expected result. The COUNT terminal yields 2 for the two-row input and 0 for an admitted empty collection. It never proves how many requests exist outside the supplied authorized array, and it does not query a model simply because a type reference is present.
Failure and recovery. An undeclared root, stale version or incompatible item type is a semantic failure. Restore the missing actual declaration or correct the plan; do not substitute a label, current draft or empty success value to hide the mismatch.
Sources. CollectionPlanTypeChecker.java, CollectionPlanJson.java.
Example DATA-COLLECTION-03 — Follow a current row’s collection relation deliberately
Scenario and inputs. Nadia builds an employee Repeater whose current row has a governed relation to that employee’s leave requests. The outer item is one employee; the relation target is MANY leave requests. Sara is viewing only the rows admitted by the original employee source. The builder must preserve both the outer type and the child collection’s actual metadata.
Procedure. 1. Select the current-row source using its actual item alias and catalog type. 2. In the member picker, choose the published relation that resolves to the leave collection, retaining its memberRef, target type and MANY cardinality. 3. Add the supported terminal projection for the child request ID rather than pretending the relation itself is a scalar field. 4. Validate each segment and the terminal’s inferred result kind before publishing. 5. Check a current row with several children and one with no children.
Expected result. The plan resolves the declared relation from the current row and returns the selected child collection/projection under that contract. The item alias cannot resolve an unrelated sibling row or silently choose the first child.
Failure and recovery. A missing relation, scalar target where MANY is required, or unreadable member must stop the binding. Inspect the actual published relationship and correct the path; creating a same-named relation in a draft does not repair a plan pinned to another published version.
Sources. CollectionPlanV1.java, CollectionPlanTypeChecker.java.
Example DATA-COLLECTION-04 — Repair source drift instead of choosing latest automatically
Scenario and inputs. A saved plan was authored against version 1 of a leave type. Another author publishes version 2 that changes a field’s shape. Nadia later edits the screen and sees a source/member validation failure. The old field’s human label may still be identical, so a visual match alone cannot establish compatibility.
Procedure. 1. Retain the original plan and record the failing source/member reference. 2. Fetch the permitted catalog for the intended release and compare source version, member identity, kind, cardinality and nullability. 3. Decide whether the screen should keep its existing supported publication or be intentionally migrated. 4. For a migration, update the source declaration and affected member path together, validate transforms and terminal result type, then save/review/publish the screen. 5. Recheck a value that exercises the changed shape, not only an empty preview.
Expected result. A compatible supported old publication retains its original meaning. A deliberately migrated plan uses a coherent new declaration and member set; structural JSON alone is never taken as proof that the new type can satisfy the original result contract.
Failure and recovery. If the new catalog is denied or the change is incompatible, stop the migration and coordinate with the model owner. Do not swap sourceVersion to the largest number, forge a member ID from a label, or describe unavailable metadata as a known zero-row source.
Sources. RecordMemberCatalogController.java, CollectionPlanTypeChecker.java.
Detailed reference
The record member catalog is the authoritative, server-side source of the
record-type and member metadata that CollectionPlanV1 PROJECT authoring,
publish, and render rely on. It turns published data models into governed,
type-checkable member metadata, and it is the concrete Catalog that backs the
CollectionPlanTypeChecker semantic boundary.
Code: com.inflowai.platform.screen.collection.catalog.
Why it exists
A CollectionPlanV1 is a no-code, eval-free plan (filter/sort/limit +
terminal) authored against a record source. The JSON codec only proves the
plan is structurally well formed. Answering "does this member exist, is it the
right type, is the declared source version still current, and is the projected
member sensitive?" needs domain truth. The catalog supplies exactly that truth,
built from the same canonical projection the expression layer and the no-code
pickers use, so a plan authored in the Studio resolves on the server with no
reference drift.
What a member reference is
Every type and member has a stable, non-positional identity that survives display-label renames:
| Concept | Reference format | Example |
|---|---|---|
| Record type | <modelKey>:<typeKey> |
sales:order |
| Field member | <typeRef>:field:<fieldKey> |
sales:order:field:amount |
| Relation | <typeRef>:relation:<relationKey> |
sales:customer:relation:orders |
typeRef and the relation keys are derived by
DataModelTypeProvider.declare(version) — the single source of relation-naming
truth — so the catalog never re-implements those rules. CollectionPlanV1
item-path segments carry these references, and the checker looks members up by
them. The colon is a reserved delimiter: model, type, field, and relation-key
segments containing it are rejected so a crafted key cannot forge another
reference shape or member kind.
Member metadata (authoritative, never invented)
For each member the catalog records:
valueType/cardinality/targetTypeRef— the shape the type checker reasons over. Field value types are folded from the expression field type (TIMEcollapses toTEXT; every portableLISTkeepsMANY, even when its element type is unknown and therefore folds toANY).nullable— for fields,!RecordField.required(), read from the published field. To-many relations are non-null collections; a singular FK-owning edge is non-null when its published relationship is required. Inverse singular edges remain nullable because requiredness is not asserted on that endpoint.sensitivity— for fields, the realpii/classification/aiExposurefacets of the publishedRecordField.omittedFromAiProjection()reports the same PII /confidential/restrictedverdict the read-side masking rule (RecordAccessPolicy) enforces. Relations, and fields with no classification, resolve toMemberSensitivity.unspecified()— never a fabricated value.
Each type also carries:
version— the published model version the metadata was captured from.permissions—TypePermissions.viewOf(modelId): theDATA_MODEL_VIEWguard on the owning data model. This is a governance descriptor, not an access grant. The authoringRecordMemberCatalogServiceseparately requires DATA_MODEL_VIEW, filters published discovery by actual scoped VIEWER role and current workspace, and rejects unsupported nonhuman catalog actors. TheRecordMemberCatalogdata structure does not execute business reads. Record read/render services still reauthorize actual data at their boundaries.
The authoring filter is implemented by RecordMemberCatalogService.
Building and querying
// Type-only (no sources): every plan source fails closed to UNKNOWN.
RecordMemberCatalog catalog = RecordMemberCatalog.fromPublishedVersions(versions);
// Type-checking a plan requires declaring its runtime sources explicitly.
RecordMemberCatalog catalog = RecordMemberCatalog.fromPublishedVersions(versions, sources);
catalog.type("sales:order"); // RecordTypeMetadata
catalog.member("sales:order", "sales:order:field:amount"); // RecordMemberMetadata
catalog.source("input:orders"); // SourceDeclaration
Single-workspace scoping. A catalog is built for exactly one workspace. Every
supplied DataModelVersion must carry the same workspaceId; a mixed-workspace
input is rejected, so a TypePermissions descriptor can never point at a
model in another workspace. For each stable model id only the highest
published version is projected, and two models that would emit the same wire
typeRef (<modelKey>:<typeKey>) are rejected rather than one overwriting the
other — otherwise a plan authored against one model could resolve against a
homonymous type governed by a different model's permissions.
Source declarations
A plan's declared source.rootRef (e.g. input:orders) is a runtime binding,
not a type. The catalog does not infer source validity from the type catalog.
Instead, callers register explicit, immutable SourceDeclaration entries keyed by
rootRef, each carrying workspaceId, typeRef, version, and cardinality:
new SourceDeclaration("input:orders", "ws1", "sales:order", 3, Cardinality.MANY);
SourceDeclaration fails closed at construction (blank rootRef /
workspaceId / typeRef, non-positive version, or null cardinality are
rejected). CollectionPlan sources are collection-valued, so declarations must
use MANY; ONE is rejected. The catalog additionally rejects duplicate rootRefs,
declarations whose workspaceId crosses the catalog's workspace, and
declarations pointing at a typeRef the catalog does not know. A declaration's
version must exactly equal the current projected version of its type; stale or
ahead declarations are rejected before a checker adapter can be created.
Server-side type checking
catalog.asTypeCheckerCatalog() adapts the catalog to the
CollectionPlanTypeChecker.Catalog boundary; catalog.check(plan) runs the
shared checker in one call. Source resolution matches the plan's declared source
only against the SourceDeclaration registered for that exact rootRef:
VALID— a declaration exists for therootRefand itstypeRef,MANYcardinality, andversionall match the plan exactly.STALE_VERSION— therootRef/typeRefbinding matches but the declaredversiondiffers (surfaced as theSTALE_SOURCE_VERSIONissue).UNKNOWN— no declaration exists for therootRef(unknown or forged), or itstypeRef/cardinalitydoes not match (surfaced asUNKNOWN_SOURCE).
A forged or unknown rootRef is never honored even when the (typeRef, version)
pair the plan also carries is perfectly real. Member drift (a renamed or dropped
field/relation reference) surfaces as UNKNOWN_MEMBER, MEMBER_KEY_MISMATCH, and
the type/cardinality mismatch codes already produced by
CollectionPlanTypeChecker.
Current-row collections inside a Repeater
A typed Repeater establishes a lexical current-row frame for its template.
The frame is available only when the parent rows value is a strict,
record-preserving CollectionPlanV1 (COLLECT with no selector). The parent
Repeater's own properties see the outer frame; its children/template see
the new item. A nested typed Repeater shadows the outer item only inside its
template. Untyped, scalar-projected, and malformed sources clear the frame.
Inside that proven boundary the no-code source picker can offer paths such as:
Current item -> account (ONE) -> orders (MANY)
The saved plan uses source.root = item, binds rootKey and rootRef to the
exact enclosing item.id, and retains every stable relationship member
reference. Record-row controls (DataGrid, Table, and Repeater) accept only
record-preserving COLLECT with no selector. PROJECT and field-selected
COLLECT stay visibly disabled because they emit scalars without a governed
scalar-row identity/column contract. The server
enforces the same slot rule. Only ONE...ONE -> MANY source paths are eligible. A plan outside
the frame, with a mismatched item id/type, an empty path, an intermediate MANY,
or a non-MANY terminal is rejected before any record read.
The render API never treats an authored object as runtime provenance. After
document preflight, it replaces an accepted current-item plan with a
renderer-owned handoff containing the canonical plan and the catalog's exact
terminal primary-key field. Authored lookalike handoffs are rejected. The
browser evaluates only that handoff against the current lexical row; a raw or
forged plan remains non-executable. Governed rows use the declared primary key
with no id/key fallback; only legacy arrays without identity metadata retain
the bounded id then key compatibility rule.
Missing relationships honor the plan's declared nullPolicy: EMPTY produces
an empty nested control, while ERROR produces a stable, non-disclosing
evaluation error. Access revocation, unsupported exact-version adapters, and
connector/runtime faults are not converted to empty data; they surface the
sanitized COLLECTION_PLAN_SOURCE_ERROR boundary.
Persisted relationship collections are materialized by one bounded,
exact-version batch per distinct path, never an N+1 read. This applies to
DataModel.get, direct DataModel list rows, Record inputs, and RecordList
rows. Input primary keys are resolved from the published catalog; supplied
nested relationship arrays are overwritten by the governed result and cannot
bypass it. A missing or invalid primary key fails with the sanitized source
boundary rather than returning a false empty collection.
The loader distinguishes an absent nullable intermediate ONE hop from a
present path whose terminal MANY collection has zero rows. Its immutable
group result carries either PATH_NULL with the exact absent segment index, or
PRESENT with the terminal rows (which may be empty). The renderer writes
null at the proven absent alias so nullPolicy applies; it writes [] only
for a proven present-empty terminal so normal empty behavior applies. Requested
roots retain order, missing roots and duplicate ONE expansion fail closed,
and terminal rows, depth, root count, bytes, and execution time are bounded.
Version 1 deliberately permits one persisted collection boundary per lexical
row path; a second boundary is visible but disabled in authoring and is rejected
before reads by document preflight.
Deterministic numeric contract (FR-COL-007)
CollectionPlanV1 uses the same numeric rules in Java evaluation and Studio
preview. Numbers are IEEE-754 binary64 values; neither runtime applies decimal
rounding, locale conversion, string-to-number coercion, or tolerance-based
comparison.
- Numeric inputs must be finite. Integral inputs must also be within the exact
JavaScript safe-integer interval,
[-9007199254740991, 9007199254740991]. A non-finite or unsafe integral input fails withUNSAFE_NUMERIC_VALUE. SUMadds selected, non-null values sequentially in source order, beginning at positive zero.AVERAGEdivides that sequential sum by the number of included values. Thus(0.1 + 0.2) + 0.3 == 0.6000000000000001is an intentional, stable binary64 result.- Every aggregate rejects a non-number with
NON_NUMERIC_ELEMENT. The selected null-element policy is applied before arithmetic; it never converts a value. - A non-finite aggregate result, or an integral result outside the safe-integer
interval, fails with
NUMERIC_OVERFLOW. It is never clamped or rounded. - Numeric equality and ordering compare binary64 values directly, without an
epsilon. For example,
0.1 + 0.2is greater than the binary64 value represented by the literal0.3. Unsafe values and incompatible scalar types fail rather than being coerced. - Sort ties retain source order, making the result deterministic after numeric comparisons.
The matching Java display name and TypeScript test title beginning
FR-COL-007 are the executable boundary anchors for this contract.
Tests
platform-monolith/src/test/java/com/inflowai/platform/screen/collection/catalog/RecordMemberCatalogTest.java
covers reference parity with the canonical projection, sensitivity / nullability
/ version / permission enrichment, latest-version-wins per stable model id,
single-workspace scoping (rejecting mixed workspaces and colliding wire
typeRefs), explicit exact-match source declarations (valid, stale, forged/unknown
rootRef, mismatched type/version/cardinality, duplicate/malformed declarations),
and the checker adapter accepting a valid PROJECT plan while catching member
drift.