Summary
Clause libraries, and include fragments (§12.2), hold text meant to be inserted into another document. Validating one on its own draws errors that only the host document can resolve: ref-broken, term-undefined, party-unknown, side-unknown, attach-undeclared, and condition-invalid/choose-invalid for an undeclared question. The same rule ids also report mistakes inside the fragment itself that no host can fix:
- a malformed
when= (when=Audit_Rights, when=audit:);
- a
{{choose:}} in a heading;
- a
{{ref:}} whose target is not an identifier ({{ref: Bad Ref}}).
A Diagnostic carries only rule, level and message, so a caller can't separate the two cases without re-parsing the directive or matching message text. ForLegalAI/PactTrack does this in app/services/clause_analysis.py, re-lexing to decide which diagnostics a host could resolve.
Proposal
Either of these would work:
- Separate rule ids for "the target is not declared in this document", as opposed to "the directive or condition is malformed". For example, split
condition-invalid into syntax and undeclared-question variants. The split for refs already exists in spirit: anchor-format and placeholder-id-malformed cover some of the malformed cases.
- A fragment mode:
validate_document(document, *, fragment=True) reports cross-references to undeclared targets as a separate category, or with a host_dependent: bool on Diagnostic, and skips the frontmatter-level rules (sides-absent, parties-minimum, def-unreferenced) that don't apply to a fragment.
Related: #26, #35 (Full fragment checks with a loader).
Summary
Clause libraries, and include fragments (§12.2), hold text meant to be inserted into another document. Validating one on its own draws errors that only the host document can resolve:
ref-broken,term-undefined,party-unknown,side-unknown,attach-undeclared, andcondition-invalid/choose-invalidfor an undeclared question. The same rule ids also report mistakes inside the fragment itself that no host can fix:when=(when=Audit_Rights,when=audit:);{{choose:}}in a heading;{{ref:}}whose target is not an identifier ({{ref: Bad Ref}}).A
Diagnosticcarries onlyrule,levelandmessage, so a caller can't separate the two cases without re-parsing the directive or matching message text. ForLegalAI/PactTrack does this inapp/services/clause_analysis.py, re-lexing to decide which diagnostics a host could resolve.Proposal
Either of these would work:
condition-invalidinto syntax and undeclared-question variants. The split for refs already exists in spirit:anchor-formatandplaceholder-id-malformedcover some of the malformed cases.validate_document(document, *, fragment=True)reports cross-references to undeclared targets as a separate category, or with ahost_dependent: boolonDiagnostic, and skips the frontmatter-level rules (sides-absent,parties-minimum,def-unreferenced) that don't apply to a fragment.Related: #26, #35 (Full fragment checks with a loader).