graffl

graffl is a simple RDF (Resource Description Framework) file format. It allows you to quickly and easily enter graph data manually. It is intended as data source and not as a target serialization format. Think of it as Markdown for RDF.

The two main design goals are

RDF is based on URI (Uniform Resource Identifier). However, URI are a very technical concept, and in most cases the URIs of the things you want to say something about are not defined until a later stage. This makes manually creating RDF files impractical. Therefore, graffl initially allows you to define the graph structure and specify the URIs later.

Nevertheless, graffl is a rigorous RDF file format. The parser produces statements consisting of subject, predicate and objects. Contexts aka. named graphs are also supported.

Another important feature is support for nested graphs. This is made possible by the concept of group graphs

The basic structure:

A block starts with a subject followed by predicate-object pairs. The block is terminated with empty line:

An object produces a literal unless:

The syntax with three quotation marks (""" …​ """) is for multiline string and may contain line breaks. Quotation marks ", slashes / and backslashes \ can be escaped with backslashes`.

If the label is a word without whitespace like "Alice", then Alice, (Alice), "Alice" or """Alice""" all refer to the same node.

If a node is defined with label (e.g. Alice, "Mr. Bean", """Mr. Bean""") graffl will produce a rdfs:label when it encounters the node for the first time as statement subject. If the node is a node reference_ (e.g. (Alice)) or URI (e.g. <mailto:alice@example.org>) then no rdfs:label is produced.

For example the graph:

produces RDF as Turtle:

If a node is defined without label as node reference (e.g. (my node)) or URI <https://example.org> or it only appears as statement object then no additional statement is produced.

graffl supports outgoing relations (->) and incoming relations (<-). Incoming relations are very convenient if you are focusing on a certain subject. If you want to say that Alice`likes `Bob and Bob is in love with Alice you can write:

graffl supports line comments. A line with double slash // as the first non-whitespace characters is ignored.

Note: If you are within a multiline string and want to start line with // you can use escaping \//.

Implementation Note: Because the introduction of comments would make the grammar very complicated the line comments are removed in a pre-process.

The directive @prefix defines the base URI prefix. It is called "prefix" because the resulting URI is a simple concatenation of the prefix with the encoded node label:

produces the URI <http://example.org/ns#Mr.%20Bean>.

The default URI prefix is https://www.hedenus.de/graffl/ plus a runtime UUID, i.e. every parser run will create new unique URIs for the nodes. Define a custom prefix for reproducible URIs.

Every word can be an alias for a URI. For defining an alias in the script use an assignment = followed by a URI in a directive:

The set of aliases is called dictionary. Here is a list of predefined aliases or default dictionary (see also the code of src/graffl/config.py):

graffl supports namespaces and qnames (qualified names). to make your script more concise and readable. A qname consists of a prefix and a local name, separated by a colon (e.g. foaf:Person). When parsing, graffl automatically expands this into a full URI.

You can define a namespace prefix using the assignment directive with an = sign followed by a URI at the beginning of your file:

Once a namespace is defined, you can use it for classes, properties, or individuals:

The following prefixes are predefined (see also the code of src/graffl/config.py):

graffl's default behavior of generating URIs from labels is perfect for quick sketches ("ABox") and ontologies ("TBox"). Very often, especially in the ABox case, the final URI of an entity is not known from the beginning of the modeling process. You can either use namespaces or you can use aliases for specifying URIs ex post.

For example, you start with the initial graph:

Later, when you have identified the URIs you define them as aliases:

If you need to distinguish between two entities with the same name, use the node reference syntax (e.g. (person001)):

Sometimes a predicate is considered a property but its value shall be an individual. Then a predicate can be specified to be a URI property by assigning it a URI type:

The produced RDF as Turtle:

Predefined URI properties are (see also the code of src/graffl/config.py):

graffl supports datatypes for literals. To specify a datatype, use the @ symbol followed by the datatype name directly before the object value. The common XML Schema 1.1 datatypes are predefined (see also the code of src/graffl/config.py).

Example:

The produced RDF as Turtle:

Every literal without a datatype (or language) is a plain literal. The syntax makes it easy for defining the datatype ex post.

Note: If the datatype is not known it will be interpreted as language tag (see below).

An object may be tagged with an ISO 639 language code. This will produce tagged RDF literals:

Objects may be blank nodes. They are surrounded by square brackets and look very much like Turtle:

By default * is a predefined alias for rdf:li.

A numbering nnn., where nnn is any positive integer number, produces rdf:_nnn:

The produced RDF as Turtle:

A list (i.e. a closed collection or rdf:List) starts with *( and ends with ). The predicate type is applied to the list members. For example:

will regard the colors as literals whereas

will regard the colors as nodes.

You can specify the target context (named graph) with the directive context followed by a URI

There are predfined profiles for RDFSchema, OWL and SHACL. This makes writing an ontology nice and simple:

If you use SHACL as well, there are naming conflicts, especially for hasValue. In that case you can disambiguate with namespaces:

Group graphs provide a simple and visual way to cluster statements into logical groups or contexts. A group graph begins with a header containing the group’s name enclosed by ---- (at least four minus characters) and ends with a closing line of ---- (at least four minus characters). Any node that appears as a subject within these boundaries is automatically linked as being contained by the group.

Note: The graffl syntax does not allow you to physically nest one group graph block inside another. Trying to open a new group graph before closing the current one will result in a syntax error.

Instead, to model hierarchical structures or logical nesting, you must define the group blocks side by side. You can then establish the hierarchy by simply using a child group’s name as a subject within the parent group’s block, or by linking them with explicit relations.