Skip to content

Draft nested support targets

data_sheets_schema.support_targets supplies an offline engineering slice of #3342: a captured schema, target inventory, contextual specifications and pure request rendering. It does not execute a judge, reuse caches, calibrate a model, or authorize a run. The existing support-v2 instrument, prompts, caches and behavior are unchanged.

An additional explicit policy addresses original strings where the selected schema requires an inline class mapping (#4902). The default remains strict. For an offline version-2 plan, select --relationship-policy inline-class-strings; the Python inventory/planner argument is relationship_policy=support_targets.SCALAR_POLICY. This is a distinct draft instrument and prompt, using policy relationship_edge_and_attribute_value_inline_class_strings_v1. It applies to class-valued inline slots generally, rather than depending on a class named Person. The observed 24-record coverage gap was Person-specific; that observation does not establish scientific validity for other class ranges.

The opt-in policy retains a nonempty original string as one relationship_edge, with its exact pointer, value, nearest containing entity and current induced schema specification. It neither splits the string into people nor invents identifiers, mappings or child attributes. The target's representation records schema_invalid_inline_class_string; inventory and plan representation_issues retain each affected pointer and range. This is a known shape mismatch, not a successful schema validation, and a support verdict cannot repair it. Existing seven-verdict precedence is unchanged. Unknown slots, malformed cardinality, missing vocabularies and unsupported owner/slot constraints remain blocked; the new scalar case also refuses inherited constraints on its range class. Boolean/numeric/container values are not coerced into references. Proper inline mappings keep their existing traversal.

Policy, instrument and request bytes are checked again during saved-result and registered-execution reconstruction. Record/target IDs remain plan-local: equal IDs do not permit evidence to cross plans or policies. Historical strict plans retain their original interpretation and request identities. New-policy reports separate selected-target representation issues, all issues verified in the chosen records, and full-plan declared counts; unselected record evidence is not reconstructed. These issues are a subset of relationship edges, not an additional pooled denominator. Attribute values and top-level fitness remain separate, and no verdict propagates to children or another facet. Calibration reports retain their all-edge groups and additionally expose representation_counts and representation_groups for the selected relationship controls. These distinguish inline-string mismatches from other edges; "other" does not mean schema-valid. The subsets contain the same observations, and their metrics retain the existing pending-control and scientific-eligibility limits.

Instrument/context review, independently adjudicated controls, calibration, private-source handling and paid-run authorization remain separate requirements. Producing an additional question is not a semantic label or a scientific result.

from pathlib import Path
from data_sheets_schema.support_targets import (
    NestedSupportSchema, inventory_targets, render_request, request_identity,
)

schema = NestedSupportSchema.from_schema(
    Path("src/data_sheets_schema/schema/data_sheets_schema_all.yaml"),
    root_class="Dataset",
    vocabulary={},  # Explicit captured registry values when the schema requires them.
)
inventory = inventory_targets(
    Path("record.yaml").read_bytes(), schema, artifact_kind="full",
)
target = inventory.target("/creators/0", kind="relationship_edge")
arguments = render_request(target, bundle="Document A\nSource text.", model="explicit-model")
identity = request_identity(target, bundle="Document A\nSource text.", model="explicit-model")

The schema must be explicitly selected. Local transitive imports are captured once; uncaptured remote imports are refused. Specifications include complete induced slot descriptions, class and ancestor meanings along the path, relevant enums and the explicit caller vocabulary snapshot. Full unrelated class attribute inventories are not sent. Inventory specifications are deduplicated in a shared catalog; each target pins its specification reference. A single target expands that specification for request rendering. No ambient profile is selected. A slot's values_from names must have entries in that vocabulary or the target is blocked. The version-2 planner captures an explicit profile vocabulary or caller-supplied vocabulary override together with the selected manifest. This pure inventory API does not select them.

Each populated inline object or list member has a relationship_edge target, such as /creators/1 or /data_governance/committee_contact. Its question is whether this entity occupies that relationship, independent of the truth of all its attributes. Scalar fields and scalar-list members have attribute_value targets, such as /creators/1/name, /variables/0/variable_name, and /flags/0. This distinguishes an accurate name from an unsupported creator relationship. The target keeps the slot chain so a generic nested name does not lose the container's meaning. The two kinds have separate counts; there is no combined support percentage or arbitrary conversion of typed verdicts to points.

Every target binds exact input bytes, artifact kind, root class/field inventory, value, selected specification and context. The nearest containing mapping's complete scalar siblings, scalar-list siblings and explicit qualifier fields (description, notes, source_caveats and declaration fields) are included as untrusted context, with its pointer, class, full-source digest and projected-value digest. The selected slot is supplied separately as the target; unrelated container siblings are omitted with their pointer, content hash and size recorded. No retained description or qualifier is truncated. Anonymous mappings retain this projected context and their path even without an identifier. The context projection is versioned and remains an explicit readiness blocker pending review; an application requiring an omitted container must expand/review the context policy before execution, not treat an omission as evidence of absence. Ancestor mappings supply identity and path, without automatically inheriting collection metadata. A resource's creator is asserted of that resource, not the outer collection. Anonymous entities retain their mapping and pointer. Context declarations come from the selected value and direct containing mapping; unrelated siblings' declarations and ancestor declarations are not inherited. Publication status and was_derived_from remain value/context fields rather than citation declarations. Natural-language attribution inside a value remains visible to the model.

Pointers address the exact original document: wrappers are not stripped. RFC 6901 escaping is strict; array append, negative/leading-zero indices and missing paths are refused. Zero and false are populated. Unknown schema fields, invalid container/cardinality shapes, keyed inline maps, unions/conditional constraints, type-discriminator transitions, and missing vocabularies are reported as blocked paths. Unsupported class constraints are refused across the complete is_a and mixin ancestry, including shared ancestors (#4232). URI references are never followed. Non-inline class references retain their relationship assertion as a string-valued edge. Native YAML dates and timestamps retain typed identities and faithful value_yaml rendering, including time zones; their JSON previews are tagged. Every node is tagged for value and context hashes, so dates, quoted date strings and ordinary tag-shaped mappings remain distinct. The request sends the faithful YAML representation once, without also repeating the JSON preview of the same text. Input bytes are never rewritten. Duplicate YAML keys, unsupported scalar types such as binary values, nonfinite numbers and invalid roots are refused. Empty or null fields do not create targets; empty/null members of a populated list are reported as blocked.

Traversal defaults to 100,000 nodes and depth 64, at most 4 MB input and 64 MB total compact target data plus shared specification catalog. Limits are explicit and pinned in the artifact identity. Exceeding a limit raises instead of returning a truncated inventory. Future context-policy changes alter the instrument and must be reviewed before calibration. The public AI_READI v7 rep1 regression exercises the default limits on its original 89 KB record, including a bounded per-creator request rather than a copy of unrelated sibling collections. The renderer is pure: no client initialization, token-count API, retry, network request or output-file write occurs.

The draft grounding_v3 axis and support_targets v3 draft (#3342) identity are distinct from v2. Request identity hashes all rendered arguments, including model, output limit, prompt, exact target/context and bundle text. This is an identity receipt, not a cache loader. Different artifact bytes, full/core kinds, entity contexts, pointer positions or specifications cannot silently share an old verdict. Returned dictionaries are private copies of immutable captured JSON.

Fitness remains explicitly top-level. Each nested target records a many-to-one mapping to its original top-level field, without inventing a per-target fitness verdict. For example /resources/0/creators/1 maps to the old /resources field. An independently versioned nested fitness instrument can replace that basis in a later, reviewed integration.

Engineering review — 2026-10-10

Optional ancestor context (#4904)

Version 2 plans can select --context-policy ancestor-qualifiers, independently of --relationship-policy strict|inline-class-strings. The Python APIs use context_policy="ancestor_scalar_qualifiers_v1". The default nearest_owner_and_ancestor_identity_v1 retains the original nearest-owner and ancestor-identity projection. Its field is omitted from serialized artifacts, so existing strict and scalar-reference target/request bytes remain unchanged. Version 1 rejects the new context choice.

The new choice addresses a specific missing question context: a Creator's source_caveats can attribute an affiliation to Document A, while the old Organization/name target below it shows only Creator identity. The new target retains that caveat at its actual Creator pointer. It does not certify the affiliation, endorse a claimed source ranking, or assign a support verdict.

Each actual ancestor on the selected path contributes its complete scalar fields and scalar-only lists, plus explicit qualifier fields (attributed_to, claim_status, source_status, description, notes, source_caveats). Each projection carries its class, original pointer, escaped field-origin pointers, full source-mapping digest, projected-value digest and faithful YAML. It excludes the selected path branch and records that branch's pointer, chosen child pointer, digest and cardinality. Other omitted containers have explicit pointers, digests and sizes. Sibling Creator values are not copied through the excluded collection. Direct-owner context is unchanged; ancestor declarations are not merged into the target's declarations. collection_metadata_inherited remains false. Seeing an ancestor fact does not make it a fact about a descendant resource.

The selected context policy has a distinct instrument name and prompt for each relationship policy. Target/context, inventory, request, descriptor, registration, execution and calibration identities bind that choice. Logical target IDs remain plan-local; exact captured plan/request bindings prevent cross-policy replay. Historical artifacts with no context-policy field retain their old interpretation. No alternate executor, cache or top-level fitness instrument is introduced.

Expanded context consumes the existing inventory and request byte budgets. There is no qualifier truncation, increased limit or partial inventory on overflow. The request carries ancestor YAML once, omitting the duplicate JSON value preview. The required 24-record comparison must report target/block/specification/value invariance and context/request size changes separately. More context is not proof of support, improved accuracy or calibration acceptance. Independent context and instrument review, adjudicated controls, empirical calibration and paid-run authorization remain open.

The nested engineering requested by #3342 is already available through the deliberately separate v3 instrument introduced by PR #4252. Extending SupportJudgeV2 or adding another traversal would duplicate that path and risk changing historical requests. This review found the following existing coverage:

Requirement Implementation and regression coverage
Nested schema meaning and entity context support_targets resolves exact pointers, induced nested slot specifications and the nearest containing entity. Public defect-path controls exercise the shapes discussed in #1782/#1801/#1815 against the public full schema, including the maintainer-role enum, caveats and identical claims in different entities. The records are neutral examples, not adjudicated defect labels.
Usable offline planning with explicit identity Planner v2 selects artifact kind, root class, schema and profile, records blocked paths, and captures target/context/specification/request identities. Planner tests cover CLI opt-in, request reconstruction and unchanged default/explicit-v1 outputs.
Separate measurement denominators Relationship edges and attribute values have separate support counts; top-level fitness remains a separate stratum. An edge asks about the relationship rather than grading its descendants again. Fitness mappings are many-to-one, and total requests are accounting totals. Saved-result tests distinguish selected-subset completion from all planned nested targets and reject altered count or target claims.
Saved judgment and actual request binding The saved-response reader reconstructs selected targets from captured inputs. The registered executor binds planned and effective request bytes, model, output limit, target and attempt. Its local HTTP regression compares the actual received POST bytes with the captured effective request and checks offline readback. This is transport capability, not evidence of a provider scoring run.

These controls establish software behavior only. Context projection and question design still need independent instrument review; a supported path does not show that a model detects its defect. Real-roster blocked paths, curator-adjudicated controls and their provenance, #3343 empirical calibration, and per-run registration and authorization remain separate obligations. This review grants no approval, records no semantic scoring, and does not close #3342 or #2929. Historical v2 prompts, defaults and saved artifacts remain unchanged.

Remaining work before #3342 completion or paid calibration

  • Independently review this resolver, context and question contract, including the choice of edge versus attribute strata and their reporting denominators.
  • Review the opt-in offline planner version 2 in offline_support_plan.md, including nested target counts, blocked-path coverage, requests and costs for the selected roster. Old top-level manifests and historical caches remain intact.
  • Decide and test missing registry/profile coverage, unsupported schema shapes, and collection inheritance policies before calling the inventory complete for a real roster. The current report always carries unresolved readiness blockers.
  • Freeze curator-adjudicated positive and supported controls, with exact local original/bundle hashes. Public tests here use neutral synthetic records and the public D4D schema; private rejected outputs are not distributed as fixtures.
  • Separate record-support, artifact-local references and audit-classification controls. Supplying full/core context does not establish that this draft prompt detects self-reference defects. A multi-clause string still yields one verdict under declared precedence, not independent coverage of every clause.
  • Select and review the exact registration before using the implemented registered executor. The separate saved-response reader validates captured replies; neither route reuses historical judgement caches or clears scientific holds. The calibration evidence workflow binds explicit control labels to a registration and reports captured outcomes offline. It does not adjudicate labels or perform empirical calibration itself.
  • Complete independent empirical calibration (#3343) and obtain the required paid-run authorization before a canary or the 24-record cohort.

Offline tests establish binding and rendering behavior, not model recall or false-positive rates. This slice does not close #3342, #3343, #2929, or the preserved generation-acceptance findings.