wijis commons

Resolving Authoring Form Include Directives

purpose

The author of a rulesheet may embed directives to include other rulesheets. The Rulesheet Repositories are responsible for recursively resolving all such directives at two points: check-in (adding, duplicating, & changing rulesheets) and retrieval (some variants of retrieval may be exempt).

A distinction is drawn between the rulesheet to be included and the including rulesheet. The rulesheet to be included is identified within the include directive by any combination of three optional parameters:

PrimaryCustodian
document type (aka ProblemSpace)
revision

In resolving the include directive, the stakeholder entity of the rulesheet to be included shall be implied to be identical to the stakeholder entity of the including rulesheet. Include resolution shall ignore utility status but must honor all other rulesheet states as is done in other types of rulesheet retrieval.

Conditional include directives may be conditional on any one or more of:

the stake of the including rulesheet's entity {PrimaryCustodian or Stakeholder}
the ProblemSpace
PrimaryCustodian URI

All three of these aspects are defined by the rulesheet retrieval context (in other words, their values are dependent on the arguments supplied during a rulesheet retrieval request). Of course, the condition must evaluate to true in order to attempt include resolution of the identified rulesheet during typical rulesheet retrieval operations. If the condition is indeterminate, then this is an error condition. If the condition evaluates to false, then the include resolution is not attempted. Note that when conducting include resolution outside of a retrieval context, such as a Syntax Check during rulesheet check-in, these three aspects shall be simulated in order to exercise the conditions to satisfy all conditional directives.

During resolution, the include directives in "rulesheets to be included" shall, in their own right, be resolved. Circular references shall be caught, and once caught, that path of recursion is no longer followed (i.e. terminated). In other words, a rulesheet URI (e.g. either a bona fide rulesheet URI generated by Rulesheet Repositories, which includes revision number, or alternatively a Rulesheet Repository URL plus any input arguments) shall be resolved only once during an Include Resolution unit of work. Any such circular references are ignored once caught and terminated; they are not considered error conditions.

The order of presentation of rules in a rulesheet is inconsequential.

Only a portion of the rulesheet to be included shall wind up in the body of the including rulesheet; that is following completion of include resolution and after all aliases are replaced (alias replacement is always conducted within the scope of a single rulesheet). That portion is the entire set of rules except for the one and only one rule that must exist as the default rule. In addition, the rulesheet URI of the rulesheet to be included shall wind up in the rulesheet URI metadata of the including rulesheet (i.e. a bona fide rulesheet URI generated by Rulesheet Repositories, which includes revision number; a Rulesheet Repository URL plus any input arguments is typically unsatisfactory). The default rule and all other content from the rulesheet to be included, which is not part of the rule set and is not the rulesheet's URI, will be excluded from winding up in the including rulesheet. This has a very important implication. A rulesheet to be included must have its default rule logically match the default rule of the including rulesheet. If it does not, then the include process shall fail on an error. To do: consider whether expectations in included rulesheets shall be ignored, honored even if different from including rulesheet's expectations, or compelled to be identical to those in the including rulesheet.

Rule ID transformation

The rule IDs of the rulesheet to be included shall be transformed in any manner so as to satisfy:

rule ID uniqueness within the including rulesheet
preservation of enough of the original rule ID from the rulesheet to be included such that an auditor may successfully identify rules and the rulesheets from which they came

Content of this site remains the property of its poster.