ESciDoc Content Relations

Definition[edit]

A content relation in eSciDoc is a resource that relates two other resources. A content relation can relate:

Content item with another content item
Content container with another content container
Content item with a content container

Note: content relations are binary and bi-directional relations i.e.

a content relation can be established only by two content objects
a content relation a->b also assumes a content relation b->a
directions a->b and b->a may have different labels (e.g. isRevisionOf, hasRevisions) that are expressed with a specific relation ontology. Both directions express the same fact, but with a reverse phrase in natural language
- see also http://en.wikipedia.org/wiki/Strong_ontology#Relationships

What content relations are not[edit]

Content relations in eSciDoc should in general not be mixed with structural (isMemberOf, hasMembers) and administrative relations (isContextFor, hasContext) as they are reserved in the present eSciDoc architecture for relations that describe:

relations between Items or Containers and a Context
relations between Containers and members of Containers
relations between parent and child organizational units

Relation types[edit]

defines the meaning of how two resources (e.g. items, container) are related. This meaning is expressed with an ontology (such as Fedora relation ontology, eSciDoc relation ontology) and labels for both directions of the relation
defines the versioning rules for relation i.e. floating or static relation type
- floating-versions relation type is valid for all versions of two related resources which were created after the time the relation was created
- exact-versions relation type is valid only for explicitly related versions of two related resources. Previous and later versions than those related with the relation are not considered as participants in the relation.
(optionally) relation type can define which resources can be related (by use of cmodel property) and in which cardinality they can be related e.g.

Examples for content relation types[edit]

Annotations (isAnnotationOf, hasAnnotations)
Revisions (isRevisionOf, hasRevisions)
History (isPredecessorOf, isSuccessorOf)
Translation (isTranslationOf, hasTranslation)
FeatureOfLanguage (hasFeature/forLanguage)

Example definitions of a relation type[edit]

Type: isRevisionOf
sourceToTarget label: isRevisionOf
TargetToSource label: hasRevisions
Versioning rule: floating

Optionally, the following can be defined:
- Source CModel: PubItem
- SourceToTarget cardinality: 0..M
- Target CModel: PubItem
- TargetToSourceCardinality: 0..M

Relation resources in eSciDoc[edit]

Relation properties (mandatory)
- relation type
- date of creation
- date of last modification
- user who created the relation
- status (pending, submitted?, released) (TBD)
- visibility (public, organizational unit, private) (TBD)

Relation metadata (TBD) (optional)
- relation comment
- persistent identifier

Note: relation metadata are dependent on the relation type in general

Component(TBD) (optional)

Note: not yet clear if one would like to enrich the relation also with a component content. Annotations are such resources

Important, to know before deciding on Item Handler to be used for content relations: Unlike content items and containers the relation resources are not limited within a context, their virtual "context" is rather the relation type associated and the resources they relate.

- Probably an alternative will be to always create them in the same context as the source item? --Natasa 13:28, 19 November 2008 (UTC)

Relation ontology resource in eSciDoc[edit]

A Relation ontology is eSciDoc resource (same structure like Item resource)
- Note: we will later on decide if the Item handler will be used or not for managing relation ontologies

A Relation ontology is described with its metadata record (i.e. authors, description, purpose etc.)
Relation types in the relation ontology are defined either as a Component of a relation ontology resource (or as "content-stream").
relation types are described as in example provided above
Relation ontology resources have own CModel (but see also last question, which brings completely different idea)
Relation ontologies are managed in a Context
Does it make sense actually to try to translate relation ontology to a CModel object?

Relation ontology handler interface[edit]

createRelationOntology(relation-ontology.xml*)
- Description: creates a relation ontology (together with all types of relations)
retrieveRelationOntology(relation-ontology-id*)
- Description: retrieves a relation ontology (together with all types of relations)
updateRelationOntology(relation-ontology.xml*)
- Description: updates a relation ontology (together with all types of relations) (in case when the relation-ontology.xml is released, this should actually mean only allow for creation of new types of relations)
deleteRelationOntology(relation-ontology-id*)
- Description:deletes a relation ontology if not in status "released"
releaseRelationOntology(relation-ontology-id*)
- Description:releases a relation ontology if in status "created" - After a release a relation ontology and its relation types can be used to relate items in the system
withdrawRelationOntology(relation-ontology-id*)
- Description:withdraws a relation ontology if in status "released" - After a withdrawal a relation ontology and its relation types can not be used to relate items in the system (existing relations are however still valid?).

retrieveRelationOntologies()
- Description: retrieves a short list of all relation ontologies available in the system. Check the possibility to use filters.

retrieveRelationTypes (relation-ontology*)
- Description: retrieves a list of relation types (and their definition) available for a specified ontology

retrieveRelationTypesForModel(cmodel-id*)
- Description: retrieves a list of relation types (and their definition) available for a specified content model (including relations defined for any content model)

Content relation methods[edit]

Note: As this is only a conceptual work, is subject to change until agreed (* for mandatory parameters, ? for optional parameters)

create (relation.xml*)
retrieve(relation-id*)
update(relation-id*, relation.xml*)
delete (relation-id*)

To discuss(1)[edit]

Task methods below to be discussed (otherwise, standard task-params)

submit(relation-id*)
release(relation-id*)
withdraw(relation-id*)

To discuss(2)[edit]

retrieveRelatedResourceRefs(resource-id*, relation-ontology*, relation-type?, direction<target, both>?)
- Description: retrieves a list of Id of resources related to specified resource-id and specified relation-ontology, (optionally) specified relation-type and (optionally) specified direction.
  - If a relation-type is not specified retrieves a list of Id of all resources related to specified resource-id within the given relation-ontology (i.e. the resource-id is either target or source of the relation).
  - If direction is specified as "target" it retrieves relations where the resource-id is the source for the relation of (optionally) specified relation-type
  - If direction is specified as "both" it retrieves relations where the resource-id is both the source and target for the relation of (optionally) specified relation-type
  - The output should contain the relation type for each related resource within a relation-ontology and the exact direction

Use cases[edit]

PubMan: relations with comments isRevisionOf, hasRevision, see Create new revision of an item
Faces: relations between person models and face images, see Faces content model
VIRR: translations, transcriptions for images, see ViRR Specification
OrganizationalUnit: create relations to express history of organizational units History of OrgUnits examples (SVN access needed)