Documentation

-------------

This section documents the RDF library.  It is mostly based on the different

recommendations from the W3C.

### RDF Structures

The RDF Structure is defined in module `(rdf rdf)`.

#### **Scheme Datatype**: `rdf-dataset`

An RDF dataset is a set of graphs, with one default graph and a set of named

graphs.  This type has the following fields:

* **default-graph**: the default graph, an RDF graph

* **named-graphs**: the list of named graphs, an alist where keys are names and

  values are graphs.

#### **Scheme Datatype**: `rdf-triple`

An RDF triple is a truth assertion that a subject is linked to an object by

a certain predicate.  This type has the following fields:

* **subject**: The subject, which can be a blank node, an IRI, a datatype or

  a literal

* **predicate**: The predicate, which can have the same type of values

* **object**: The object, which can have the same type of values

Note that the recommendation restricts the possible values for predicate

further (it should not be a blank node for instance), but also introduces the

notion of *generalized RDF*, which corresponds to our definition of a triple.

This is useful for entailment.  A valid RDF triple can still be represented with

this datatype.

#### **Scheme Datatype**: `rdf-literal`

An RDF literal is the value of a node.  This type has the following fields:

* **lexical-form**: The lexical form of the literal, a unicode string.

* **type**: The type of the literal.  This can be either an IRI or an RDF

  datatype (described later).

* **langtag**: An optional language tag.  Note that when `langtag` is defined,

  the type is necessarily rdf:langString.

Note that the `langtag` restriction only applies semantically.  Operations on

RDF graphs and datasets as implemented in this library do not check that it is

well-formed.  Parsers and producers will fail to execute when the type is not

as expected though.

#### **Scheme Procedure**: blank-node? node

Returns wether a node is a blank node or not.  Blank node representation is

internal and should not be relied upon as it might change without prior

notice.  Two blank nodes can be compared for equality (or unequality) with

`equal?`.  Other procedures are not guaranteed to work on blank nodes.

#### **Scheme Procedure**: rdf-graph? graph

Returns whether a scheme value is an RDF graph.  This does not check the

consistency or validity of the graph, but merely that it is syntactically

correct.

### RDF Datatypes

Datatypes are used to add semantics to literals.  The `(rdf rdf)` further defines

them, as well as some base datatypes.

#### **Scheme Datatype**: `rdf-datatype`

This type has the following fields:

* **iris**: A list of IRIs that represent this type

* **description**: A string describing that datatype, usually taken from

  documentations or recommendations

* **literal?**: A procedure to check whether a string is a literal of that type

* **value?**: A procedure to check whether a value is of that type

* **lexical->value**: A procedure to transform a valid literal into a value value

* **value->lexical**: A procedure to transform a valid value into a valid literal

Note that there might be more that one valid value or literal to transform into.

The last two procedures will choose one canonical representation.

The documentation does not refer to `value->lexical`.  It is an addition of this

implementation.

#### **Scheme Datatype**: `rdf-vocabulary`

A vocabulary is a collection of datatypes.  This implementation also equips a

vocabulary with utility functions.  This type has the following fields:

* **datatypes**: A list of RDF datatypes

* **order**: A procedure that returns whether the first datatype's value space is

  included in the value space of the second (i.e. whether it is smaller).

* **compatible?**: A procedure that returns whether the two datatypes passed as

  parameters are compatible, i. e. their value space is not disjoint.

Compatibility is assumed to be total (it always answers for any pair of recognized

datatype in the vocabulary).  One of the consistency conditions of a graph is

that when a node has multiple types, they must have at least one value in

common (for instance, a node can be both an integer and a decimal, because

integer values are both integers and decimals, but it cannot be a boolean and an

integer).

The type consistency of a node is mathematically expressed as the non-emptyness

of the intersection of value spaces of all the types of the node.  It is assumed

in this implementation that, when all the types or two-by-two compatible, that

intersection is not empty.  This is not true in general, but works at least of

the base vocabulary included in guile-rdf.

**Help wanted**: if you can come up with a better algorithm, please share!

#### Available Datatypes in `(rdf rdf)

* rdf:langString

* rdf:XMLLiteral

#### Available Datatypes in `(rdf xsd)`

When you import this module with `#:prefix xsd:`, you can easily use these

literals with that prefix, in the same way you would write it in a concrete

RDF document.  For instance, the following is a valid triple:

```scheme

(make-rdf-triple

  "http://example.org/a"

  "http://example.org/prop"

  (make-rdf-literal "10" xsd:integer #f))

```

Representing (in turtle syntax):

```

@prefix xsd: http://www.w3.org/2001/XMLSchema#

<http://example.org/a> <http://example.org/prop> "10"^^xsd:integer .

```

Available datatypes are:

* xsd:boolean

* xsd:string

* xsd:decimal

* xsd:integer

* xsd:int

### Graph Operations

The `(rdf rdf)` module also defines some graph operations.  They are presented

below.

#### **Scheme Procedure**: `merge-graphs g1 g2`

Merges two graphs.  As graphs are collections of RDF triples, this is very

similar to appending the two sets.  However, we must ensure that we don't

accidentaly merge blank node identifiers that should not be merged, as two

distinct blank nodes can have the same internal representation in both graphs.

#### **Scheme Procedure**: `rdf-isomorphic? g1 g2`

Returns whether two graphs are the same.  Two graphs can have a different

representation because of order and because of differing blank node

representations.  For instance the following graphs (in turtle format) are

isomorphic, even though their representation is different:

```

_:a1 <http://example.org> "10"^^<xsd:integer>

```

and

```

_:bn <http://example.org> "10"^^<xsd:integer>

```

However, the following is *not* isomorphic with any of the previous graphs:

```

_:a1 <http://example.org> "010"^^<xsd:integer>

```

Because the literal representation of `10` differs.

#### **Scheme Procedure**: `recognize graph vocabulary`

Transforms a graph to replace every instance of recognized IRIs in the

vocabulary by an RDF datatype.