Context
I'm prototyping a workflow-orchestration spec (FlowSpec) where the data model is a composed FormSpec: a public applicant-facing intake form, combined with internal context sections (AI extractions, fetched data, computed fields, adjudicator decisions) that the workflow engine populates. The two-document pattern matters because the base form is served to applicants but the composed form (which exposes internal field names like fraudSignals.riskScore) must only be served to authenticated staff.
The ambiguity
The §6.6 narrative describes $ref as a mechanism for reuse of common item sets — demographics blocks, address blocks, signature sections. The §6.6 worked example is a host doc pulling in a shared demographics group.
The pattern I need is the inverse: the base Definition is the canonical "thing" (the public intake form, independently published with its own validation), and the composed Definition adds to it without modifying it.
From §6.6 alone it's not clear whether:
- (a) This is supported and idiomatic —
$ref + host-defined binds is the intended way to extend a base Definition.
- (b) This is technically possible but not the design intent — the spec authors envision a different mechanism (yet to be added) for "extends a published Definition with additional sections and behavior."
- (c) The use case is out of scope — Definitions are expected to be self-contained, with
$ref reserved for narrow common-block reuse.
The shape of $ref itself seems to support (a): fragments (#sectionKey) let you import individual items, host-level binds can target imported paths, and assembly produces a self-contained Definition. But the documentation framing leans toward (c).
Why it matters
Without clarity, implementations will diverge. A composed Definition that extends a base form behaves identically to a self-contained Definition under §6.6.2 assembly, so engines won't catch the divergence — but tooling that surfaces "this Definition extends X" or that supports re-publishing the base independently will quietly break.
What would help
Either:
- A short paragraph in §6.6 (or a §7 example) showing "base Definition + extending Definition" as a recognized pattern, or
- An explicit statement in §6.6 that the supported use case is shared-block reuse only, with extension of a published Definition deferred to a future mechanism.
A worked example would be more useful than prose. Happy to contribute a PR with a minimal "applicant-intake form + workflow-extending form" example (PFML-style, ~100 lines each) once the design intent is settled.
Related
This question is closely tied to #10 (bind merge semantics). If the answer to #10 is "binds don't merge, last-write-wins or error," the extension pattern in (a) is effectively blocked and the answer here is forced toward (b) or (c).
Context
I'm prototyping a workflow-orchestration spec (FlowSpec) where the data model is a composed FormSpec: a public applicant-facing intake form, combined with internal context sections (AI extractions, fetched data, computed fields, adjudicator decisions) that the workflow engine populates. The two-document pattern matters because the base form is served to applicants but the composed form (which exposes internal field names like
fraudSignals.riskScore) must only be served to authenticated staff.The ambiguity
The §6.6 narrative describes
$refas a mechanism for reuse of common item sets — demographics blocks, address blocks, signature sections. The §6.6 worked example is a host doc pulling in a shareddemographicsgroup.The pattern I need is the inverse: the base Definition is the canonical "thing" (the public intake form, independently published with its own validation), and the composed Definition adds to it without modifying it.
From §6.6 alone it's not clear whether:
$ref+ host-defined binds is the intended way to extend a base Definition.$refreserved for narrow common-block reuse.The shape of
$refitself seems to support (a): fragments (#sectionKey) let you import individual items, host-levelbindscan target imported paths, and assembly produces a self-contained Definition. But the documentation framing leans toward (c).Why it matters
Without clarity, implementations will diverge. A composed Definition that extends a base form behaves identically to a self-contained Definition under §6.6.2 assembly, so engines won't catch the divergence — but tooling that surfaces "this Definition extends X" or that supports re-publishing the base independently will quietly break.
What would help
Either:
A worked example would be more useful than prose. Happy to contribute a PR with a minimal "applicant-intake form + workflow-extending form" example (PFML-style, ~100 lines each) once the design intent is settled.
Related
This question is closely tied to #10 (bind merge semantics). If the answer to #10 is "binds don't merge, last-write-wins or error," the extension pattern in (a) is effectively blocked and the answer here is forced toward (b) or (c).