Parts of an Aspen file

There are two important parts of any Aspen project: narratives and discourses.

A narrative is a description of data that records facts, observations, and perceptions about relationships. For example, in an Aspen file, we'll describe a relationship between two people like this: (Liz) [knows] (Jack).

A discourse is a way of speaking or writing about a subject. Aspen works out of the box by labeling every node an Entity and assuming the text inside the parentheses is the name of that entity. Aspen can't automatically know that (Liz) and (Jack) are people, so if we want it to know, we have to tell it using the discourse, that little block of YAML on top of an Aspen file.

(Depending on the structure of the project, you might have narratives and discourses spread out across files, or you might have a narrative and discourse in the same file.)

In a single Aspen file, the discourse is written at the top, and the narrative is written at the bottom, always split by a line of just four dashes: ----.

If you're coming from a software development background, you can think of the discourse as a sort of configuration that will be used to build the Cypher file that results from the Aspen narrative.

Here's an example of an Aspen file, with discourse and narrative sections marked:

# Discourse
default:
  label: Person
----
# Narrative
(Liz) [knows] (Jack).
(Jenna) [knows] (Jack).
(Liz) [knows] (Jenna).

If the concepts of discourse and narrative aren't fully clear right now, that's okay—keep going. The rest of the tutorial should shed light on them. Also, this README was written pretty quickly, and if you have suggestions, please contribute—your feedback will be well-received and appreciated!