# Element mapping components

## Classifying an element

### `<classify-as>`

Assign a class to the model element.

## Matching an element to something else

Match the model element to a pre-existing element in the model or the target datastore.

### `<match-with-model>`

Match the model element with something existing in the model.

### `<match-with-store>`

Match the model element with something existing in the target datastore.

## Making a relationship between an element and something else

Create a new relationship in the model between the model element and a pre-existing element in the model or the target datastore.

### `<relate-with-model>`

Make a relationship between the model element and something existing in the model.

### `<relate-with-store>`

Make a relationship between the model element and something existing in the target datastore.

## Setting built-in properties

Use source model information to set built-in properties for the model element, i.e. ones for which there is a default mapping to RDF.

### `<set-uri>`

Set the URI of the model element.

> NB this will also set the GUID of all source elements linked to this model element to be the URI minus the namespace part.

### `<set-label>`

Set the label of the model element.

> NB this will also set the equivalent property of all source elements linked to this model element.

### `<set-description>`

Set the description of the model element.

> NB this will also set the equivalent property of all source elements linked to this model element.

### `<set-tag>`

Set a tag for the model element.

> NB this will also set the equivalent property of all source elements linked to this model element.

### `<set-source>`

Set an arbitrary property of the current source element only, without setting anything for the model element.

> NB this **requires** the use of the `<overwrite>` tag within the `<source-value>` in order to specify which property is to be overwritten.

## Mapping properties and relationships

Map source model information to arbitary properties and relationships of the model element, which requires some further information about how this mapping should be expressed in RDF.

### `<map-attribute>`

Map a `<source-value>` to an attribute of the model element.

### `<map-date>`

Map a `<source-value>` to a date property of the model element.

### `<map-quantity>`

Map a `<source-value>` to a quantitative property of the model element.

### `<map-quality>`

Map a `<source-value>` to a qualitative property of the model element.

### `<map-relationship>`

Map a relationship from the current source element to a relationship for the model element.

> NB this will map a relationship defined in the source model, whereas `<relate-model>` and `<relate-target>` can create relationships that do not exist in the source model.

## Getting values

All element mapping components except for `<classify-as>` allow a `<source-value>` tag that defines the value to be used for the mapping operation.

### `<source-value>`

Extract a value from a source element, using one of several attributes:

`name` gets the value of a specific property from the current source element.

`value` provdes a fixed string as a value.

`value-class` provides a fixed class as a value, either from the default namespace or the namespace specified by the additional `value-namespace` attribute.

`eval` evaluates a Python expression and provides the result as a value.

### `<validate>`

Confirm that the value of a `<source-value>` complies with a given validation rule, set by one of the following attributes:

`value` requires that the `<source-value>` match a fixed string value exactly.

`value-class` requires that the `<source-value>`  match a fixed class value exactly, either from the default namespace or the namespace specified by the additional `value-namespace` attribute.

`pattern` requires that the `<source-value>` match a regular expression.

`eval` evaluates a Python expression and requires that the result evaluate true.

### `<overwrite>`

Overwrite a property of the current source element with the value of a `<source-value>`.

`name` specifies the name of the source property to overwrite.

> NB regardless of the presence or absence of the overwrite tag, setting the so-called built-in properties (guid, id, label, description or tag) will always overwrite the equivalent property in the current source element, providing that such an equivalent property exists (this varies depending on thr source model type).

# Evaluating Python expressions

Wherever the attribute `eval` is permitted, the provided Python expression is evaluated in the context of the current source element. The following local variables are available:

`source_model` is the interface to the complete source model of which the current source element forms a part.

`source_element` is the interface to the current source element.

# Examples

Set the URI of the model element to the value of a Python expression and overwrite the property "Description" in the source model with the same value:

```xml
<set-uri>
  <source-value eval="'http://example.com/' + source_element.guid">
	<overwrite name="Description"/>
  </source-value>
</set-uri>
```

Map a quality of type rdl:Colour to the fixed value rdl:Red for every model element:

```xml
<map-quality>
  <source-value value-namespace="rdl" value-class="Red"></source-value>
  <class namespace="rdl" name="Colour"/>
</map-quality>
```