Annotations

Annotations, metadata, and directives

RIF documents and rule sets may contain annotations, which are properties of rule sets or parts of rule sets which do not have a direct lexical semantics, but which are important for interchange, as well as human consumption of rules.

We distinguish between two kinds of annotations:

• Annotations which can be ignored for rule set processing (e.g., author, date, title, natural language description); we call these annotations metadata

• Annotations which cannot be ignored for rule set processing (e.g., imports, data set references); we call these annotations directives [this name is not very good; suggestions are welcome]

Annotations can be written about any rule set or rule.

Since metadata can be ignored for rule set processing, we do not restrict the metadata properties which can be used in any dialect.

Directives cannot be ignored; in fact, all directives must be understood by anyone who processes rule sets of a particular dialect. Therefore, every dialect has a fixed set of directives which may be used.

Suggested directives for BLD: rif:imports, rif:requiresDataSet, rif:dataModel (see the page on datasets for a description of the rif:requiresDataSet and rif:dataModel properties).

Recommendations about the use of metadata properties

We might consider to recommend the use of particular metadata properties, for enhanced interoperability. Two candidates sets of metadata properties would be Dublin core and the RDFS metadata properties (such as label, comment, seeAlso).

Extension of the presentation syntax

The syntax for rule sets and rules needs to be extended to allow for rule set and rule identification. Furthermore, it is convenient to group annotations together with rule sets and rules. Finally, it is currently foreseen that rule sets can have both metadata and directives, and rules can only have metadata. We propose the following modification of the grammar:

 Ruleset  ::= ' Ruleset( ' iri? Directive* Metadata* RULE* ' ) '
 RULE     ::= ' Rule( ' iri? Metadata* RuleContent ' ) '
 RuleContent ::= ' Forall ' Var+ ' ( ' RULE ' ) ' | Implies | ATOMIC
 Implies  ::= ATOMIC ' :- ' CONDITION

 Directive ::= ' Directive ( ' iri Const ' ) '
 Metadata ::= ' Metadata ( ' MetadataList ' ) '

 MetadataList ::= iri MetadataValue | MetadataList ' ; ' MetadataList

 MetadataValue ::= Const | ' [] ' | ' [ ' MetadataList ' ] '

The structure of metadata can be a single IRI (name of the metadata property) with a value or a list of name value pairs. The values themselves do not necessary have a name (indicated with '[]'), and they can be further structured themselves through nesting of ' [ ' MetadataList ' ] '.

Metadata properties can be any IRI; each RIF dialect prescribes a fixed list of directive IRIs.

NOTE: an alternative approach for the specification of directives would be to extend the RIF syntax for each specific directive.

Neither directives nor metadata are reflected in the model theory.

If it is deemed necessary that arbitrary metadata statements (not only about rule sets and rules) can be added, the following change could be made to the Ruleset production:

 Ruleset  ::= ' Ruleset( ' iri? Directive* Metadata* (RULE | MetadataStatement)* ' ) '
 MetadataStatement  ::= ' MetadataStatement ( ' Const MetadataList ' ) '

Example 1 -- Consider a rule set with the infamous uncle example. The example uses the FOAF ontology as data model and contains metadata throughout. IRIs are written using the CURI shortcut syntax; the ex prefix stands for http://example.org/myruleset#; the cc prefix stands for the creative commons namespace. For an explanation of the rif:schema directive see the data sets page.

1 Ruleset(ex:uncleRuleSet
2  Directive(rif:schema "http://xmlns.com/foaf/0.1/"^^rif:iri)
3  Metadata(dc:creator "Jos de Bruijn")
4  Metadata(cc:permits "http://web.resource.org/cc/Distribution"^^rif: iri)
5  Rule(ex:uncleRule
6   Metadata(dc:title "The infamous uncle rule")
7   Metadata(dc:description "Any brother of any parent of a person is that person's uncle.")
8   Forall ?x ?y ?z (?x[ex:hasUncle -> ?z] :- And ( ?x[rdf:type -> foaf:Person] ?x[ex:hasParent-> ?y] ?y[ex:hasBrother-> ?z]) )
9  MetadataStatement(ex:hasBrother dc:relation ex2:hasSibling) )

The directive on line 2 refers to the RDF Schema ontology http://xmlns.com/foaf/0.1/. The metadata on the lines 3 and 4 say something about the creator of the rule sets and the permissions related to its license. The metadata of the rule sets, all clients 6 and 7, describes the title and gives a natural language description of the rule. The MetadataStatement on line 9 indicates that there is some relation between ex:hasBrother and the property ex:hasSibling.

Extension of the XML syntax

By example:

Ruleset(  rs1
  Directive("a1"^^rif:iri "v1"^^rif:iri)
  Directive("a2"^^rif:iri "v2"^^xsd:string)
  Metadata(
           "a3"^^rif:iri  "v3"^^xsd:string; 
           "a6"^^rif:iri [];  
           "a7"^^rif:iri ["a8"^^rif:iri  "v3"^^xsd:string; 
                          "a9"^^rif:iri  "v3"^^xsd:string]
          )
  Metadata("a4"^^rif:iri  "v4"^^rif:iri)
  Rule( r1
    Metadata("a5"^^rif:iri  "v5"^^xsd:string)
  ....
  )
)

translates to

<Ruleset rif:identifier="rs1">
  <Directive rif:identifier="a1" type="rif:iri">v1</Directive>
  <Directive rif:identifier="a2" type="xsd:string">v2</Directive>
  <Metadata rif:identifier="a3" type="xsd:string">v3</Metadata>
  <Metadata rif:identifier="a6"/>
  <Metadata rif:identifier="a7">
    <Metadata rif:identifier="a8" type="xsd:string">v3</Metadata>
    <Metadata rif:identifier="a9" type="xsd:string">v3</Metadata>
  </Metadata>
  <Metadata rif:identifier="a4" type="rif:iri">v4</Metadata>
  <Rule rif:identifier="r1">
    <Metadata rif:identifier="a5" type="xsd:string">v5</Metadata>
    ....
  </Rule>
</Ruleset>

Mapping metadata to RDF

We present a mapping from metadata to RDF (using turtle syntax). The purpose of this mapping is to show how RDF tools can be used for managing metadata in RIF rules. This does not mean that it is required to use RDF for managing RIF metadata.

The mapping reuses the mapping tr on the page RDF embeddings for mapping IRIs and data values.

tr(Ruleset(  rs
  ...
  Metadata(meta1)
  ...
  Metadata(metan)
  Rule( rule1 )
  ....
  Rule( rulen )
  )
)

tr(rs, meta1) .
...
tr(rs, metan) .
tr(Rule( rule1 ))
...
tr(Rule( rulen ))

tr(Ruleset(
  ...
  Metadata(meta1)
  ...
  Metadata(metan)
  Rule( rule1 )
  ....
  Rule( rulen )
  )
)

tr([], meta1) .
... 
tr([], metan) .
tr(Rule( rule1 ))
... 
tr(Rule( rulen ))

tr(Rule(  r
  Metadata(meta1)
  ...
  Metadata(metan)
  )
)

tr(r, meta1) .
... 
tr(r, metan) .

tr(Rule(
  Metadata(meta1)
  ...
  Metadata(metan)
  )
)

tr([], meta1)
... 
tr([], metan)

tr(iri1, iri2 Const)

tr(iri1) tr(iri2) tr(Const)

tr([], iri2 Const)

[] tr(iri2) tr(Const)

tr(iri, m1 ; ... ; mn)

tr(iri) tr(m1);  
...  ;
tr(iri) tr(mn)

tr([], m1 ; ... ; mn)

[] tr(m1) ;
... ;
tr(mn)

tr(iri Const)

tr(iri) tr(Const)

tr([])

[]

tr([m1 ; ... ; mn])

[tr(m1) ; ... ; tr(mn)]