Schema file elements for data rule definitions, rule set definitions, data rules, rule sets, and folders

This is a description of the elements of the XML document used when requesting, creating, or modifying data rule definitions, rule set definitions, data rules, rule sets, and folders.

Name of the XSD file where the elements are defined

iaapi.xsd, which is in the following locations:

ASBServer/docs/IA/schema (server)
ASBNode/docs/IA/schema (client)

Commands that use these elements

POST create
POST update
GET project
GET ruleDefinition
GET executableRule

Example of an XML document for the GET ruleDefinition command:

<?xml version="1.0" encoding="UTF-8"?>
<iaapi:Project xmlns:iaapi="http://www.ibm.com/investigate/api/iaapi" name="project1">
  <DataRuleDefinitions>
    <DataRuleDefinition name="Rule1Def">
      <description>Description of Rule1Def</description>
      <LongDescription> Long description of Rule1Def></LongDescription>
      <expression>if col1='E' then col2 in_reference_column refcol</expression>
      <Variables>
        <Variable name="col1" dataType="string" defaultBinding="SOURCE1.SCHEMA1.TABLE1.COL1"/>
        <Variable name="col2" dataType="string"/>
        <Variable name="refcol" dataType="string"/>
      </Variables>
    </DataRuleDefinition>
(...)
  </DataRuleDefinitions>
</iaapi:Project>

XSD file elements

<DataRuleDefinitions>: Specifies the list of data rule definitions or rule set definitions that are defined in a project. Each rule definition is defined as a child element of <DataRuleDefinitions>. Data rules are specified as children elements of the rule definition element.

The following table shows the children of the <DataRuleDefinitions> element:

Table 1. Children of the <DataRuleDefinitions> element
Element	Cardinality	Description
<DataRuleDefinition>	0..*	Rule definitions defined in the project
<RuleSetDefinition>	0..*	Rule set definitions defined in the project

<DataRuleDefinition name="...">: Specifies a rule definition. A rule definition contains an expression and a list of data rules generated from the rule definition.

The following table shows the attributes of the <DataRuleDefinition> element:

Table 2. Attributes of the <DataRuleDefinition> element
Attribute	Description
name	Name of the rule definition
folder	Folder name or folder path. A folder name can also be a folder path in the following form <folder1>/<folder2>/<folder3>/.

The following table shows the children of the <DataRuleDefinition> element:

Table 3. Children of the <DataRuleDefinition> element
Element	Cardinality	Description
<description>	0 or 1	An optional description of the data rule
<LongDescription>	0 or 1	An optional long description of the data rule
<expression>	1	The rule expression
<Variables>	0 or 1	The list of variables that are contained in the data rule expression. This list is returned when the "GET project" or "GET ruleDefinition" commands are used, but it is not required when creating a rule with the "POST create" command.
<ExecutableRules>	0 or 1	The list of data rules created for the rule definition

<RuleSetDefinition name="...">: Specifies a rule set definition. A rule set definition contains a list of rule definitions. The rule definitions can be references to rule definitions that already exists or are defined elsewhere in the XML, or they can be created as nested <RuleDefinition> elements within the rule set definition.

The following table shows the attributes of the <RuleSetDefinition> element:

Table 4. Attributes of the <RuleSetDefinition> element
Attribute	Description
name	Name of the rule set definition
folder	Folder name or folder path. A folder name can also be a folder path in the following form <folder1>/<folder2>/<folder3>.

The following table shows the children of the <RuleSetDefinition> element:

Table 5. Children of the <RuleSetDefinition> element
Element	Cardinality	Description
<description>	0 or 1	An optional description of the rule set definition
<LongDescription>	0 or 1	An optional long description of the rule set definition
<RuleDefinitionReference>	0..*	A reference to rule definitions that either already exist or are defined in the document by a <RuleDefinition> element
<DataRuleDefinition>	0..*	A rule definition that you want to create as a part of the rule set
<Variables>	0 or 1	The list of variables contained in the data rule expression. This list is returned when the "GET project" or "GET ruleDefinition" commands are used, but it is not required when creating a rule with the "POST create" command.
<ExecutableRules>	0 or 1	The list of data rules created for the rule definition

<Variables>: Specifies the list of local variables of the data rule definition or the rule set definition that contains it. This element is specified in the common.xsd file.

The following table shows the children of the <Variables> element:

Table 6. Children of the <Variables> element
Element	Cardinality	Description
<Variable>	0..*	Local variables of the data rule or rule set definition

<Variable name=”...” dataType=”...”>: Specifies a local variable of a data rule definition or a rule set definition. A variable is characterized by its name and its logical data type (numeric, string, date, time, timestamp, or untyped). It can contain a binding element that represents the default binding of the variable.

The following table shows the attributes of the <Variable> element:

Table 7. Attributes of the <Variable> element
Attribute	Description
name	Name of the variable
dataType	Logical data type of the variable. Possible values include: Numeric String Date Time Timestamp Any

The following table shows the children of the <Variable> element:

Table 8. Children of the <Variable> element
Element	Cardinality	Description
<Binding>	0 or 1	The default binding of the variable

<RuleDefinitionReference ruleName=”...”>: Specifies that a rule definition defined elsewhere in the document or already existing in the system is part of the containing rule set definition.

The following table shows the attributes of the <RuleDefinitionReference> element:

Table 9. Attributes of the <RuleDefinitionReference> element
Attribute	Description
ruleName	Name of the rule definition

<ExecutableRules>: Specifies the list of data rules defined for the data rule definition or rule set definition containing this element.

The following table shows the children of the <ExecutableRules> element:

Table 10. Children of the <ExecutableRules> element
Element	Cardinality	Description
<ExecutableRule>	0..*	The data rules defined for the data rule definition or rule set definition

<ExecutableRule name="...">: Specifies a data rule that was generated from a data rule definition or a rule set definition. The data rule definition or rule set definition is represented by the parent element. A data rule contains a list of bindings, an output definition, and eventual join conditions.

The following table shows the attributes of the <ExecutableRule> element:

Table 11. Attributes of the <ExecutableRule> element
Attribute	Description
name	Name of the data rule
folder	Folder name or folder path. A folder name can also be a folder path in the following form <folder1>/<folder2>/<folder3>.

The following table shows the children of the <ExecutableRule> element:

Table 12. Children of the <ExecutableRule> element
Element	Cardinality	Description
<description>	0 or 1	An optional description of the data rule
<LongDescription>	0 or 1	An optional long description of the data rule
<BoundExpression>	0 or 1	The expression of the data rule definition or rule set definition of this executable rule, where all the variables have been replaced by their binding targets. This element is filled when the specification of an data rule is obtained with the GET project command or the GET executableRule command, but it does not have to be specified when a data rule is created or updated with the POST create command or the POST update command.
<Bindings>	0 or 1	The list of bindings for the data rule
<OutputDefinition>	0 or 1	The definition of the output of the executable rule. The output definition specifies the output type (passing records, failing records, all records, and so on) and the output columns.
<JoinConditions>	0 or 1	The list of join conditions to use if the bindings are done on columns from different tables

<Bindings>: Specifies a list of bindings for the global variables, a data rule or a data rule set.

The following table shows the children of the <Bindings> element:

Table 13. Children of the <Bindings> element
Element	Cardinality	Description
<Binding>	0..*	Bindings of the global logical variables of the data rule or rule set

<Binding var="...">: Specifies the binding of a global logical variable of a data rule or rule set. The binding element contains an element that represents the binding target that can be a column, or a constant or a global logical variable.

The following table shows the attributes of the <Binding var> element:

Table 14. Attributes of the <Binding var> element
Attribute	Description
var	Name of the variable that is being bound

The following table shows the children of the <Binding var> element:

Table 15. Children of the <Binding var> element
Element	Cardinality	Description
<Column>	0 or 1	If this element is used in the <Binding> element, the variable name that is defined by the attribute variable is bound to the fully qualified column name that is specified in the name attribute of the <Column> element. If this element is used, do not define other children elements in the <Binding> element.
<Constant>	0 or 1	Indicates that the variable is bound to a literal value (either a number, a string, a date, a time, or a timestamp constant) If this element is used, do not define other child elements in the <Binding> element.
<Variable>	0 or 1	Indicates that the variable is bound to a global variable. The name of the global variable is specified by the name attribute of the <Variable> element

<Constant stringValue=”...” | numericValue=”...” | ...>: Specifies the value of a constant that is used when a variable is bound to a constant. This element contains an attribute for each possible data type (number, string, date, time, timestamp, and so on). Use only one of these attributes at the same time.

The following table shows the attributes of the <Constant> element:

Table 16. Attributes of the <Constant> element
Attribute	Description
numericValue	Use this attribute to specify the numeric value of the constant, if the type of the constant is numeric. The value can be a floating point number.
stringValue	Use this attribute to specify the string value of the constant if the type of the constant is a character string
timeValue	Use this attribute to specify the time value of the constant
dateValue	Use this attribute to specify the date value of the constant
datetimeValue	Use this attribute to specify the timestamp value (date+time) of the constant

<OutputDefinition>: Specifies the output definition of a data rule. The output definition contains the output type (the type of records in the output: passing records, failing records, all records, or statistics only) and the name and definition of the columns composing the output table.

The following table shows the attributes of the <OutputDefinition> element:

Table 17. Attributes of the <OutputDefinition> element
Attribute	Description
outputType	The type of the output. This includes the type of records, passing records, failing records, all records or statistics only. Possible values are: PassingRecords FailingRecords AllRecords StatsOnly

The following table shows the children of the <OutputDefinition> element:

Table 18. Children of the <OutputDefinition> element
Element	Cardinality	Description
<OutputColumn>	0..*	The list of columns that are in the output table

<OutputColumn>: Specifies a column that you want to include in the output table of a data rule. An output column has a name (as it appears in the output table), a type (either a global logical variable of the rule, or a physical column, an expression, or a metric), and a target (the name of the variable, column, the expression, or the metric).

The following table shows the attributes of the <OutputColumn> element:

Table 19. Attributes of the <OutputColumn> element
Attribute	Description
type	The type of the output column. The output type can either be a global logical variable of the rule, a physical column, an expression, or a metric. Possible values are: variable column expression metric
name	The name of the column in the output table
value	If type=”variable” the value should contain the name of the rule variable that should be in the output. If type=”column” the value should contain the full qualified name (datasource.schema.table.column) of the column to put in the output. If type=”expression” the value should contain the expression to output. If type=”metric” the value should be only of the following metric names: METRIC_NB_PASSING_RULES METRIC_NB_VIOLATED_RULES METRIC_PERCENT_PASSING_RULES METRIC_PERCENT_VIOLATED_RULES METRIC_RECORD_ID METRIC_RULE_EXECUTABLE_NAME METRIC_SYSTEM_DATE METRIC_SYSTEM_TIMESTAMP

<JoinConditions>: Specifies an element that contains a list of join conditions to apply to run the data rule.

The following table shows the children of the <JoinConditions> element:

Table 20. Children of the <JoinConditions> element
Element	Cardinality	Description
<JoinCondition>	0..*	The join conditions

<JoinCondition>: Specifies one join condition that is applied in the binding of a data rule. A join condition is made up of a pair of key columns whose value should be equal and a join type (inner, left outer, right outer, or full outer join).

The following table shows the attributes of the <JoinCondition> element:

Table 21. Attributes of the <JoinCondition> element
Attribute	Description
leftKey	The fully qualified name (datasource.schema.table.column) of the left key of the key pair representing the join condition
rightKey	The fully qualified name (datasource.schema.table.column) of the right key of the key pair representing the join condition
joinType	The type of join. Possible values are: inner leftOuter rightOuter fullOuter

<Folders>: Specifies an element that contains a list of folders that a rule or rule definition can be attached to.

The following table shows the children of the <Folders> element:

Table 22. Children of the <Folders> element
Element	Cardinality	Description
<Folder>	0..*	The folder defined for the project

<Folder>: Specifies the folder that a rule or rule definition can be attached to.

The following table shows the attributes of the <Folder> element:

Table 23. Attributes of the <Folder> element
Attribute	Description
name	Name of the folder

The following table shows the children of the <Folder> element:

Table 24. Children of the <Folder> element
Attribute	Cardinality	Description
<description>	0 or 1	An optional description of the folder
<LongDescription>	0 or 1	An optional long description of the folder
<Folder>	0..*	The folder defined for the project