Skip to content

6 Data Structures

Jump to bottom
Sarah Lück edited this page Sep 15, 2026 · 2 revisions

Reference & Enhancement data structure

Robots create Enhancements (=labels) for references. The data structure is stored in pydantic models. The complete documentation can be found here

Titles and Abstracts

A title of a reference is stored in

destiny.sdk.references.Reference.enhancements.BibliographicMetadataEnhancement.title

An abstract of a reference is stored in

destiny.sdk.references.Reference.enhancements.AbstractContentEnhancement.abstract

Enhancements

Enhancement is a container class where in the content-field supports different enhancement types.

Enhancement
│
├── metadata about the enhancement
│   ├── reference_id
│   ├── source
│   ├── visibility
│   └── robot_version
│
└── content  ← one of several EnhancementContent subtypes
    │
    ├── AnnotationEnhancement
    │   └── annotations
    │       ├── BooleanAnnotation
    │       └── ScoreAnnotation
    │
    ├── LinkedDataEnhancement
    │   └── data (JSON-LD)
    │
    ├── RawEnhancement
    │   └── data (arbitrary/unstructured)
    │
    ├── FullTextEnhancement
    │   └── file_url, mime_type, ...
    │
    ├── LocationEnhancement
    │   └── locations
    │
    └── ReferenceAssociationEnhancement
        └── associated_reference_ids

Boolean and Score Annotations

These annotation types can store simple classifier results.

content=AnnotationEnhancement(
                            annotations=[
                                BooleanAnnotation(
                                    scheme=SCHEME,
                                    label=LABEL,
                                    value=True,
                                    score=0.8,
                                    )
                                ]
                            )
ScoreAnnotation(
        scheme=SCHEME,
        label=LABEL,
        score=0.8,
        )

The first example contains the complete content how it would be stored in the Enhancement, the second only the annotation. Please note that scheme and label are available to all projects accessing the destiny-repository. scheme serves as mode of annotation and label to identify the project. There is no naming convention yet.

I used in the query robot

SCHEME = "query:inclusion"
LABEL = "cdr"

for references which are included by the query

SCHEME = "domain:inclusion"
LABEL = "cdr"

for annotations generated by the relevance classifier in the relevance robot.

Linked Data Annotations

LinkedDataEnhancement stores the classification as references to concepts in a controlled vocabulary. Instead of assigning a text label such as "Biochar", the robot stores the persistent concept URI, for example:

https://vocab.cdr.org/cdr-method/CDR000011

This provides a stable, shared vocabulary that can be versioned and extended over time.

Building a vocabulary

To use this type of annotations you need to create and publish your own vocabulary at the vocabulary builder. Credentials needs to be provided by the DESTINY repository team. You can examine already published vocabularies at the taxonomy viewer.

A vocabulary consists of four main building blocks:

  • Concept Schemes: controlled lists of allowed values for one dimension of the taxonomy, e.g. CDR technology.
  • Concepts: the individual entries within a scheme, e.g. Biochar.
  • Classes: the types of nodes that can occur in a LinkedDataEnhancement, e.g. Investigation or TechnologyCodingAnnotation.
  • Properties: relationships or values associated with classes. A property can refer to another class, a concept scheme, or a datatype such as decimal.

The DESTINY repository provides a set of predefined core classes and properties. Among the predefined lasses are Investigation and CodingAnnotation, which can be used as building blocks for project-specific classes. The benefit of using them would be that they fit into the scheme which the DESTINY-repo uses for their projections.

Projections are flattened LinkedDataEnhancements that make their contents searchable via the DESTINY API.

For CodingAnnotation nodes, the evrepo:status property determines whether the annotation is included in the projection:

  • If evrepo:status is present and its value is not evrepo:coded, the CodingAnnotation is skipped during projection.
  • If no evrepo:status is present, the CodingAnnotation is projected as **coded** by default.
  • If evrepo:status is explicitly set to evrepo:coded, the CodingAnnotation is projected as coded.

Notes on the vocabulary builder

There are two ways to build a vocabulary: the vocabulary builder UI can be used directly, or a TTL file can be imported.

If a vocabulary inherits from one of the predefined classes, such as evrepo:CodingAnnotation, the import function needs to be used. The UI does not currently provide functionality for defining this inheritance.

For example, a TTL file can contain the following definitions:

@prefix cdr:     <https://vocab.cdr.org/> .
@prefix evrepo:  <https://vocab.evidence-repository.org/> .
@prefix owl:     <http://www.w3.org/2002/07/owl#> .
@prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#> .
@prefix skos:    <http://www.w3.org/2004/02/skos/core#> .
@prefix xsd:     <http://www.w3.org/2001/XMLSchema#> .

evrepo:LinkedDataEnhancement a owl:Class ;
    rdfs:label "Linked Data Enhancement"@en ;
    rdfs:comment "A structured linked-data annotation attached to a Reference in the repository. Contains one or more Investigations."@en .

evrepo:Investigation a owl:Class ;
    rdfs:label "Investigation"@en ;
    rdfs:comment "A study reported within a Reference. An Investigation produces one or more Findings."@en .

evrepo:hasInvestigation a owl:ObjectProperty ;
    rdfs:label "has investigation"@en ;
    rdfs:domain evrepo:LinkedDataEnhancement ;
    rdfs:range evrepo:Investigation .

evrepo:CodingAnnotation a owl:Class ;
    rdfs:label "Coding Annotation"@en ;
    rdfs:comment "A coded value with provenance from source material. Wraps each coded property value with supporting text, coder identity, and coding status."@en .

evrepo:codedValue a rdf:Property ;
    rdfs:label "coded value"@en ;
    rdfs:domain evrepo:CodingAnnotation ;
    rdfs:comment "The extracted value. Type varies by CodingAnnotation subclass."@en .

# The node type that carries one classification result
cdr:TechnologyCodingAnnotation a owl:Class ;
    rdfs:subClassOf evrepo:CodingAnnotation ;
    rdfs:label "Technology Coding Annotation"@en ;
    rdfs:subClassOf [
        a owl:Restriction ;
        owl:onProperty evrepo:codedValue ;
        owl:allValuesFrom cdr:TechnologyConcept
    ] .

cdr:TechnologyConcept a owl:Class ;
    rdfs:subClassOf skos:Concept ;
    rdfs:label "Technology Concept"@en .

# The link from a reference's investigation to a result, and the score on it
cdr:hasTechnology a owl:ObjectProperty ;
    rdfs:domain evrepo:Investigation ;
    rdfs:range cdr:TechnologyCodingAnnotation ;
    cdr:allowMultiple true .

cdr:classifierScore a owl:DatatypeProperty ;
    rdfs:domain evrepo:CodingAnnotation ;
    rdfs:range xsd:decimal .

# The controlled list and its concepts
cdr:TechnologyScheme a skos:ConceptScheme ;
    rdfs:label "Technology Scheme"@en ;
    skos:hasTopConcept cdr:CDR000010 , cdr:CDR000011 .

cdr:CDR000011 a cdr:TechnologyConcept , skos:Concept ;
    skos:inScheme cdr:TechnologyScheme ;
    skos:topConceptOf cdr:TechnologyScheme ;
    skos:prefLabel "Biochar"@en .

After creating the TTL file, it can be imported into the vocabulary builder.

Note that a class in the vocabulary builder can only be deleted when all its properties are deleted. There is a very subtle error message which informs about this fact when trying to delete a class with properties and the message might be missed.

Different design options for building a vocabulary

For the CDR project, the following structure is used.

LinkedDataEnhancement
│
└── hasInvestigation
    │
    └── Investigation
        │
        ├── hasTechnology
        │   │
        │   └── TechnologyCodingAnnotation
        │       │
        │       ├── technologyCodedValue
        │       │   └── cdr-method Scheme
        │       │       └── CDR000001 ... CDR000015
        |       | 
        │       ├── evrepo:CodedStatus
        │       │   └── coded OR lowClassifierScore
        │       │
        │       └── technologyClassifierScore
        │           └── decimal
        │
        ├── hasScientificMethod
        │   │
        ....

Each TechnologyCodingAnnotation contains one coded value from the cdr-method scheme and one classifier score as properties. Investigation has the property hasTechnology, which refers to TechnologyCodingAnnotation and can contain multiple values. In this way one can store multiple TechnologyCodingAnnotation in one LinkedDataEnhancement. CodedStatus defines if the coded value appears in the projection. A CodedStatus=coded OR None will appear in the projection, any other value will be skipped. However, this implementation is a current work around.

Only classes such Investigation and TechnologyCodingAnnotation define the nodes in the classLinkedDataEnhancement. The nodes are connected by class properties such as hasInvestigation or hasTechnology. Concepts such as Biochar (CDR000001) from the controlled vocabulary are referenced as values of properties, rather than used as node types.

A simpler design can also be used, and may be preferred by the DESTINY repository team. In this design, the classifier score is not stored in the LinkedDataEnhancement. Instead, one defines a property hasTechnology which can hold multiple values of the cdr-method scheme. Only classifications whose score exceeds a predefined threshold are included.

LinkedDataEnhancement
│
└── hasInvestigation
    │
    └── Investigation
        │
        ├── hasTechnology
        │   ├── CDR000003
        │   ├── CDR000006
        │   └── ...
        │
        └── hasScientificMethod
            ├── CDR000011
            ├── CDR000017
            └── ...

The two designs therefore differ in where the multiplicity of classification results is represented:

  • Current CDR design: one TechnologyCodingAnnotation per classification result, with its individual classifier score.
  • Simpler design: one hasTechnology property containing multiple classified concepts; the classifier scores are not stored.

Publishing the vocabulary

The vocabulary needs to be published in the vocabulary builder in order to use it at a LinkedDataEnhancement. Once this is done it can be inspected in the Vocabulary Viewer at:

https://vocab.evidence-repository.org/<UID of your project>/<version number>/

The Vocabulary Builder also publishes two files that are used when creating the LinkedDataEnhancement:

https://vocab.evidence-repository.org/published/<UID>/<version>/vocabulary.ttl
https://vocab.evidence-repository.org/published/<UID>/<version>/context.jsonld

Please note the published in these URLs compared to the one before.

The **vocabulary.ttl** contains the formal definition of the vocabulary, including its classes, properties, schemes, and concepts. The **context.jsonld** defines how the terms used in the JSON-LD representation are mapped to their full URIs.

Creating a LinkedDataEnhancement

A LinkedDataEnhancement contains vocabulary_uri and data. vocabulary_uri identifies the published **vocabulary.ttl** that defines the structure and concepts used by the enhancement. data contains the JSON-LD representation of the annotation, including an @context that refers to the corresponding **context.jsonld**.

The structure of the LinkedDataEnhancement for the CDR project (cp. structure above) is as follows:

content = LinkedDataEnhancement(
    vocabulary_uri=(
        "https://vocab.evidence-repository.org/"
        "published/<UID>/<version>/vocabulary.ttl"
    ),
    data={
        "@context": (
            "https://vocab.evidence-repository.org/"
            "published/<UID>/<version>/context.jsonld"
        ),
        "@type": "LinkedDataEnhancement",
            "hasInvestigation": {
                "@type": "Investigation",
    
                "hasTechnology": [
                {
                    "@type": "TechnologyCodingAnnotation",
                    "technologyCodedValue": {
                        "@id": "https://vocab.cdr.org/cdr-method/CDR000003"
                    },
                    "technologyClassifierScore": 0.97,
                },
                {
                    "@type": "TechnologyCodingAnnotation",
                    "technologyCodedValue": {
                        "@id": "https://vocab.cdr.org/cdr-method/CDR000006"
                    },
                    "technologyClassifierScore": 0.82,
                },
                ...
            ],

            "hasScientificMethod": [
                {
                    "@type": "scientificMethodAnnotation",
                    "scientificMethodCodedValue": {
                        "@id": "https://vocab.cdr.org/scientific-method/CDR000025"
                    },
                    "scientificMethodClassifierScore": 0.91,
                },
                ...
            ],

          ...
        },
    },
)

In the simpler design described above where a classification only appears if its score is above a certain threshold the LinkedDataEnhancement would also look simpler:

content = LinkedDataEnhancement(
    vocabulary_uri=(
        "https://vocab.evidence-repository.org/"
        "published/<UID>/<version>/vocabulary.ttl"
    ),
    data={
        "@context": (
            "https://vocab.evidence-repository.org/"
            "published/<UID>/<version>/context.jsonld"
        ),
        "@type": "LinkedDataEnhancement",

        "hasInvestigation": {
            "@type": "Investigation",

            "hasTechnology": [
                "https://vocab.cdr.org/cdr-method/CDR000003",
                "https://vocab.cdr.org/cdr-method/CDR000006",
                ...
            ],

            "hasScientificMethod": [
                "https://vocab.cdr.org/scientific-method/CDR000011",
                "https://vocab.cdr.org/scientific-method/CDR000017",
                ...
            ]
        }
    }
)

Clone this wiki locally