Capturing Content
Content in RAMEN describes material that can be captured, referenced, edited, annotated, and published. A Content node may store text, reference an image or provide another machine-readable representation used by a project.
Content nodes are deliberately simple. They do not define the whole editorial meaning of an object on their own. Their editorial role is created through contextual structures and annotations: a text may become the text of a witness through PART_OF, and it may receive interpretation, classification, or commentary through HAS_ANNOTATION.
Serialised material means material that is stored or referenced in a concrete digital form, such as plain text, a URL, an external file reference, or another representation that a project can process.
Content Nodes
Content nodes represent serialised or addressable material. A refined Content node may, for example, be called Text or Image, but RAMEN does not bind specific media types to these labels. What matters is that the node remains recognisable as a Content node, so tools can rely on the RAMEN base type while projects can define more specific content-bearing roles.
The attributes used to capture material depend on the content type and the used tools. For textual content, a project model may define a text attribute. For image content, a url attribute. Other media or data types may use different attributes.
A project model should define the expected attributes for its content types in advance. Different tools may require different attributes depending on the workflow; these requirements should be specified before data capture begins.
For textual content, a tool may expect a text attribute and use startIndex and endIndex for range-based annotations. For image content, a tool may expect a url attribute and use coordinates or IIIF-regions for image annotations.
Content and Annotations
Content and annotations are closely connected in RAMEN. A Content node carries the material, while Annotation nodes add editorial information to it. This can include interpretation, structural markup, classification, or references to other elements.
The relation between content and annotation is expressed through HAS_ANNOTATION. A content-bearing node may have zero or more annotations. They may describe the whole content or only a specific part of it, such as a text range or an image region.
RAMEN annotations provide a type attribute that can be used to distinguish annotation kinds without necessarily refining the Annotation node itself. How far annotation types define additional properties, constraints, or editing behaviour depends on the project model and tool support.
Examples of Capturing Content
The following examples show how Content nodes can be refined, how material can be captured and annotated, and how existing encodings or more granular serialisations can be integrated into RAMEN.
The examples below describe methods to capture, import and annotate content. They are not intended as best practices, but illustrate possible modelling and methodology choices that may differ between projects and tools.
Capturing Different Content Types
This section shows how different kinds of material can be captured in refined Content nodes.
Capturing Plain Text
A project may capture textual material in a refined Content node such as Text. The text itself can be stored in a text attribute, while structural, interpretive, or classificatory information is represented separately as Annotation nodes.
These annotations can describe the whole content node or specific text ranges. For range-based annotations, attributes such as startIndex and endIndex can identify the relevant part of the text. This makes it possible to attach paragraphs, headings, quotations, names, corrections, comments, or other editorial information to the same textual content through HAS_ANNOTATION.
Capturing Images
A project may capture image-based material in a refined Content node such as Image. The image itself may be referenced through a url attribute or another project-defined attribute.
Annotations can then describe the whole image or a specific region of it. Instead of startIndex and endIndex, image annotations may use coordinates, bounding boxes, polygons, or IIIF-compatible regions, depending on the project model and tool support.
As with text, the Image node carries or references the material, while Annotation nodes add structure, classification, interpretation, or links to other editorial objects.
Working with Content Annotations
This section shows how annotations attached to content can be typed and linked to other editorial objects.
Typing Content Annotations
Annotations attached to content can often remain general Annotation nodes. Their specific meaning can be expressed through the type attribute. For example, a TEI persName annotation can be represented as an Annotation with type: "persName" attached to a content-bearing node.
Depending on the project model and tool support, annotation types may also define different expected properties, validation rules, or editing forms. A persName annotation may therefore require different information than a commentary annotation, even if both remain general Annotation nodes.
Refined annotation nodes are useful when an annotation kind should become a distinct project-specific concept in the model (e.g., using Annotation directly while additionally refining it into TextAnnotation and ImageAnnotation). In many cases, however, type-based annotations are sufficient and avoid unnecessary refinement of the Annotation node.
Linking Content Annotations
Annotations on content can also create connections to other editorial objects. A Text node may HAS_ANNOTATION an annotation with type: "persName", and this annotation may REFERS_TO a Person entity.
In this pattern, the content, the annotation, and the entity remain separate. The Text node carries the written form, the annotation marks and classifies the occurrence, and the Person entity represents the identified person. This allows the same content to remain readable as text while its editorial interpretation becomes explicit in the graph.
Serialising and Reusing Existing Content
This section shows how existing encodings or more granular serialisations can be used together with RAMEN Content nodes.
Using TEI/XML and RAMEN
A project may capture textual content by transforming existing TEI/XML into a RAMEN-compatible graph structure. In this pattern, the plain text is stored in refined Content nodes, while selected TEI/XML encoding information is transformed into RAMEN Annotation nodes.
This follows the same general principle as TEI/XML standoff markup and annotations (cf. Palladino et al. 2020): textual content and annotation information are kept separate, while range information such as startIndex and endIndex connects each annotation to the relevant part of the text. TEI can serve as one possible vocabulary for these annotations, but other vocabularies or project-specific annotation types can also be used.
Alternatively, a refined Content node may reference an existing TEI/XML document as an external resource, if the encoded document should remain the primary representation.
Graph-Serialised Text with ATAG
Some workflows need more granular text structures than a single text attribute can provide. In such cases, RAMEN can be combined with a graph-based text serialisation such as Applied Text as Graph (ATAG) (cf. Kuczera 2024). ATAG can represent a text as a chain of character or token nodes, so that very small textual units become directly addressable for editing, annotation, citation, or computational processing.
In this pattern, the RAMEN Content node remains the content-bearing entry point for the project model. The ATAG structure provides a more detailed internal representation of the text. Relations such as STANDOFF_START and STANDOFF_END belong to this granular serialisation, while RAMEN tools can rely on the Content node and HAS_ANNOTATION relation at the model level.