Main Mapping Rules DTD

Available here: ./mapping.dtd

External Reusable Sub-Paths DTD

Available here: ./reUsableSubPaths.dtd

External Value Map DTD

Available here: ./valueMap.dtd

<!ELEMENT Map (map)>
<!ELEMENT map (entry*)>
<!ELEMENT entry (key?,value?)>
<!ELEMENT key (#PCDATA)>
<!ELEMENT value (#PCDATA)>

Nested Elements

This section contains an example of an element mapping with a nested element mapping. Note that the element contains both text content and a nested element. The mapping rule handles both those items.

An element with both text content and a nested element:

<withNestedWithContent>
  mob
  <nested>
    kidnapping
  </nested>
  <nested>
    blackmail
  </nested>
</withNestedWithContent>

An example of a mapping for the above schema:

<elementMapping elementName="withNestedWithContent">                            
  <patternToPaths>
    <pattern prior="1">(.*)</pattern>
    <path no="1" type="literal">                
      <pathElement elementLevelId="group" elementName="withNestedWithContent">cidoc:E74_Group</pathElement>                                                             
      <pathElement>cidoc:P3_has_note</pathElement>                                                                      
    </path>                             
  </patternToPaths>     
  <elementMapping elementName="nested">         
    <patternToPaths>
      <pattern prior="1">(.*)</pattern>
      <path no="1" type="literal">              
        <pathElement elementLevelId="group" elementName="withNestedWithContent">cidoc:E74_Group</pathElement>                                                           
        <pathElement>cidoc:P144i_gained_member_by</pathElement>                                 
        <pathElement>cidoc:E5_Event</pathElement>                                                                                                       
        <pathElement>cidoc:P3_has_note</pathElement>            
      </path>                           
    </patternToPaths>                   
  </elementMapping>                     
</elementMapping>

When Attributes Matter

In some schemas, like MARC/XML, the element name is not enough to apply mapping semantics. Sometimes the meaning of an element is based on the element name but also the tag values. In a situation like this, you can provide the tag values required for the specified mapping paths to apply. The attribute values are provided within the attrValues tag, like in the following example:

<elementMapping elementName="datafield">
  <attrValues>
    <attrValue attr="tag" value="041" />
  </attrValues>
  <patternToPaths>
  ...
  </patternToPaths>                     
</elementMapping>

Note that the attribute value is a regular expression, so you can provide a pattern of values (e.g. [a-c|e], meaning a,b,c, or e).

Caution: empty attribute contents and lack of the attribute are considered the same situation.

It also is possible to map attribute contents the same way element contents are mapped. The mapping paths look the same and use regular expression groups in the same way. The attr attribute of the path element connects the path to an attribute.

Example:

<elementMapping elementName="ns1:vitalDatesCreator">
        <attrValues>
                <attrValue attr="birthdate" value="(.*)" />
                ...
        </attrValues>           
        <patternToPaths>
                <pattern prior="1">.*</pattern><!--empty element! only attributes matter!-->
                <path attr="birthdate" no="1" type="literal">
                        <pathElement elementLevelId="creator" elementName="ns1:indexingCreatorSet">cidoc:E21_Person</pathElement>
                        <pathElement>cidoc:P98i_was_born</pathElement>
                        <pathElement>cidoc:E67_Birth</pathElement>
                        <reUsableSubPath name="hasTimeSpan" />
                </path>
                ...
        </patternToPaths>
</elementMapping>

Identical Mappings for Different Elements

As you have seen above, the required attributes are defined using regular expressions. This is not the case with element names, but there is one trick you can do. If a number of elements are mapped exactly the same way, you can define one mapping for all of them, using the | syntax:

<elementMapping elementName="same1|same2">              
  <patternToPaths>
    <pattern prior="1">(.*)</pattern>
    <path no="1" type="literal">                
      ...
    </path>                             
  </patternToPaths>                     
</elementMapping>                 

Advanced: the element mapping rule defined for an element with a set of attributes is stored as one instance for all attributes matching the regular expression. This means that if the rule contains a singleton path, the contents will be concatenated even if the attributes were not equal. In case of of identical mappings for different elements, the rules are duplicated and stored separately, which means that any singleton path will only concatenate the contents from one of the elements.

Ignoring Elements

If you want to ignore the contents of an element and all its children without getting warnings about the lack of mapping for it, use the ignored attribute like this:

<elementMapping elementName="irrelevantContents" ignored="true" />              

Another way of marking an element as ignored is to define a pattern with no groups. The difference is that then the mapper will try too look for mappings for the element's children.

Non-Greedy Quantifiers

Try to use non-greedy quantifiers (*? instead of *) in the regular expressions where possible. If the last example in the above section used a greedy quantifier, the contents the element would all match the first group, and the other groups would be empty.

Omitting Groups

If you need to use a group in the regular expression, but you do not want to map it to any paths, you can use a non-capturing group, marking it with (?:) instead of ().

An example:

(a(?:b*))+(c*)

For the abbabc string, the captured groups are:

1. ab
2. c

If the matched group is empty or contains only white characters, the corresponding path will be ignored.

Ignoring All Contents

If you want to ignore the contents of an element without any warnings from the mapper, define a pattern to paths pair in which there are no capturing groups in the pattern and there are not paths.

Path Types

There are five types of paths:

• Literal Path
• Singleton Path
• URI Path
• Static Path
• Case Path

<pattern prior="1">(?s)^.{6}([aefk])(.).+</pattern>                                             
<path no="1" type="case">
  <case>
    <caseValue>a</caseValue>
    <casePath>
      <pathElement recordLevelId = "mainDescribedObject">cidoc:E89_Propositional_Object</pathElement>
      <pathElement>cidoc:P2_has_type</pathElement>
      <pathElement instance="true">http://purl.org/dc/dcmitype/Text</pathElement>
    </casePath>
  </case>
  <case>
    <caseValue>e</caseValue>
    <casePath>
      <pathElement recordLevelId = "mainDescribedObject">cidoc:E89_Propositional_Object</pathElement>
      <pathElement>cidoc:P2_has_type</pathElement>
      <pathElement instance="true">http://dl.psnc.pl/schemas/namedIndividuals/dcmitype_extended#Map</pathElement>
    </casePath>
  </case>       
  <case>
    <caseValue default="true" />
    <casePath />    
  </case>
</path>  

Path Elements

Path elements are further defined with a set of mostly non-required attributes. The semantics of those attributes are described in this section.

Reverse

This is the only one mapping path element attribute that applies to property name elements.

When declaring a mapping path for an ontology in which not every property has an inverse, you may find yourself in the situation when the property works the other way round. If the property should connect the second element with the first one, set the reverse attribute to true.

Default value is false.

Example:

<pathElement>class A</pathElement>
<pathElement>prop 1</pathElement>
<pathElement>class B</pathElement>
<pathElement reverse="true">prop 2</pathElement>
<pathElement>class C</pathElement>
<pathElement>prop 3</pathElement>

External Sub-Paths

Often mapping paths are repeated throughout the mapping rules document. It is possible to extract such paths to an external file. The DTD of such file is given in the External Reusable Sub-Paths DTD section. The external sub-paths file location can be an absolute path or a path relative to the main mapping rules file.

This section given a simple example of an external mapping sub-path to which you can refer by its name.

Sample contents of an external sub-paths file:

<reUsableSubPaths>
  <reUsableSubPath name="hasTimeSpan">
    <pathElement>cidoc:P4_has_time-span</pathElement>
    <pathElement>cidoc:E52_Time-Span</pathElement>
    <pathElement>cidoc:P78_is_identified_by</pathElement>    
    <pathElement blank="true">cidoc:E49_Time_Appellation</pathElement>  
    <pathElement>ext:P3h_has_note</pathElement>  
  </reUsableSubPath>
</reUsableSubPaths>

Call to an external sub-path:

<recordMapping reUsablePathsFile="./reUsableSubPaths.xml" recordTag="...">      
...
  <pathElement recordLevelId = "infObj">frbroo:F24_Publication_Expression</pathElement>
  <pathElement>cidoc:P16i_was_used_for</pathElement>
  <pathElement>ext:E7a_Becoming_Available </pathElement>        
  <reUsableSubPath name="hasTimeSpan"/>
...

Adding a Substring to the Path Value

It is possible to add a string at the beginning or at the end of the mapped value using the startWith and endWith path attributes.

Element-Level Id

Sometimes the contents of an element are separated into may groups, containing different kinds of information about an object. For instance, the creator element may contains the name of a person and the person's birth date. We want to create two separate paths, assigning data to the same object.

To introduce an element-level id you have to use the elementLevelId tag, providing the id.

Additionally, you can add the elementName tag. It defaults to the current element. This tag defines the scope of the identifier: in hierarchical schemas the same element-level id may be valid in many sub-elements.

Example:

<pathElement elementLevelId="creator" elementName="dc:creator">
  cidoc:E21_Person
</pathElement>  

Note that two occurrences of the same ID may belong to path elements with different class names. It is the user's responsibility to make sure that those classes are consistent.

Record-Level Id

A record-level identifier is very similar to an Element-Level Id, but it is valid throughout the whole record. You declare it using the recordLevelId attribute.

In some rare cases you may want to define two record-level ids for the same element - they should be separated with a semicolon (recordLevelId="id1;id2"). If the URI's for both id1 and id2 have already been created, they will be merged when such a path element is obtained, and they will be replaced in the statements already generated for this record.

Iterable Record-Level Id

This is an advanced type of identifier that you probably will not need very often.

There are cases in which two separate elements that share no common parent other than the document root are related to each other in such a way that the first occurrence of element 1 corresponds to the first occurrence of element 2, the same hold for second occurrences and so on. This relation may hold e.g. between MARC 21 datafield 300 (physical description), subfield e (accompanying material) and contents of datafield 538 (system details note).

In such cases you can use a record-level id with iterable attribute set to true.

It is advised to also define the elementName for this identifier: the id will be iterated each time the mapper leaves the attribute, and the iteration is set to 1 at the first occurrence of the element. The default element name is the current one.

Consider the following XML file:

...
<elem1>
  <subel>Name and surname 1</subel>
  <subel>Name and surname 2</subel>
  <subel>Name and surname 3</subel>
</elem1>
...
<elem2>
  <subel2>date of birth 1</subel2>
  <subel2>date of birth 2</subel2>
  <subel2>date of birth 3</subel2>
</elem2>
...

You can connect the names to birth dates using iterable record-level ids:

...
<!--subel mapping in elem1-->
<pathElement recordLevelId = "person" iterable="true">
  cidoc:E21_Person
</pathElement>  
...
<!--subel2 mapping in elem2-->
<pathElement recordLevelId = "person" iterable="true"> 
  cidoc:E21_Person
</pathElement>  
...

You can further restrict the iteration giving attributes together with elementName, like this:

<pathElement iterable="true" recordLevelId="addContent" 
          elementName="http://www.loc.gov/MARC21/slim/subfield(code=e;ind=1)">
    frbroo:F23_Expression_Fragment
</pathElement>

And/or force iteration reset with the resetOn attribute. Then the next occurence of the identifier within the same element will be treated as the first one. It is useful for instance in MARC/XML records where are elements have the same name (subfield). You can reset the iteration after encountering the datafield parent tag.

<pathElement iterable="true" recordLevelId="addContent" resetOn="http://www.loc.gov/MARC21/slim/datafield"
          elementName="http://www.loc.gov/MARC21/slim/subfield(code=e;ind=1)">
    frbroo:F23_Expression_Fragment
</pathElement>

If you want the identifier to be iterated at each occurence within a scope (especially one element scope), you can pass "*" as the element name. Remember to set the resetOn property then - otherwise the identifier will never be reset (each iterated id will be used only once, rendering its existence useless).

URI Identifier Data Source

The object's URI is generated when the identifier is first encountered. Sometimes another occurrence contains data that would allow for a more representative URI (remember, the captured group value is used to generate the URI). If you want the id to be regenerated in a more representative location, mark the location with the idDataSrc attribute set to true.

Conditions

The condition tag may appear within a patternToPaths element.

There are three types of conditions, corresponding to three types of identifier:

• recordLevelId
• elementLevelId
• iterableRecordLevelId

If the patternToPaths element contains a declarations like this:

<condition type="recordLevelId">issnMain</condition>

it means that the pattern will only be evaluated if an object with the given id has already been created. If not, the next pattern will be checked.

Such existential conditions have been introduced for situations in which the first occurence of an element is treated differently, e.g. for titles and alternative titles.

Resetting

Resetting ids is necessary only in very specific scenarios.

You can use the resetIds attribute of a pathElement to reset the saved record level id or element level id. The URI of the element that has the attribute will be the new ID value.

Caution! This functionality has been designed to help deal with recursive elements. This does not change the URI's of the resources that have already been assigned that id (to do that, use idDataSrc). Instead, it causes all references to this id from now on to correspond to the new URI.

If you use it with an iterable id, the id will be iterated.

Default Values

As seen in the example above, it is possible to define a default value, skipping the key.

If a default value is not defined, the mapper will leave the original value. This may lead to a mapper error if the map changes literal values into URI's, and the mapper expects a URI value.

Ignored Values

As seen in the example above, it is possible to ignore some values, skipping the value declaration for a given key.

If you want to ignore all unknown keys, add the following snippet to your map:

<entry>
</entry>

Required configuration

Optional configuration

Namespaces and URI Generation Strategy

The mapper creates URI's for new object based on the provided main knowledge base namespace, the class the object belongs to, and the textual contents of the element that leads to the object creation. The URI's are stable, i.e. they will be the same after each run of the mapper, provided the metadata record does not change.

If you do not like the URI's generated by the mapper, or you have strict rules of URI creation for your data, you can do it easily by extending the pl.psnc.synat.mapper.core.NameSpaceManager abstract class or the pl.psnc.synat.mapper.core.NameSpaceInMemoryManager concrete class and setting your class as the managerClass for the mapper.

You should implement or override the createURI methods.

Inverse Processing

Originally the mapper has been used to create a knowledge base described with the CIDOC CRM ontology. In this ontology, most properties have their inverses. A property name always starts with PX_, where X is a number. Inverse properties start with PXi_. In our use case it was important that the mapper only produces the basic property triples (without 'i'), mostly because we did not want to turn reasoning on at too early a stage, but wanted to be able to query the repository efficiently.

If you have a similar use case, and want the mapper to always use the original property (reversing the triple, of course), here is what you have to do:

• set inverseProcessing to true (in the properties file, or programatically),
• implement the isInverseProp(URI property) method of pl.psnc.synat.mapper.core.NameSpaceManager>,
• make sure the getInverseOfProp(URI property) method works well in the default implementation (it should, as it checks the ontology definition).

Contexts

The mapper puts all triples in a context (named graph). You define the context in the properties file (or mapper constructor), be default it is null.

If you wish to apply a more advanced context logic and base the context on the contents of the metadata record, the Simple way that you can do it is by overriding the setMapperContext(String fullElementName, String elementContents) in pl.psnc.synat.mapper.core.XmlToOntMapper. The method has en empty body in the mapper.