💬Annotation

Social commentary mechanism

An annotation is a localized comment on another entity, which could represent feedback in the case of a review or author arguments explaining why a research component supports the attestation of a claim. Annotations referencing claims can be useful as motivation before an attestation is made, and providing such arguments contributes to user reputation as the discussion is credited.

Annotation thread directly on a research object

Publication author motivates the Data Available claim, and receives feedback from a reviewer

It’s likely that a mechanism for fighting spam will be required in gateways, for example only showing annotations from profiles with a verified identity.

Schema

Field	Type	Description
comment	String	Contextual commentary
researchObjectID	ID	Research object context
researchObjectVersion	Commit	Research object version identifier
targetID	ID	Which node the annotation applies to
targetVersion	Commit	Version identifier of the same
dagNode	CID	Optionally reference a node in the DAG
pathToNode	String	unixFS path to dagNode (it's not necessarily unique)
locationOnFile	String	Optional location specifier on the file in question
claimID	ID	Optional mention of a claim
claimVersion	Commit	Claim version identifier
metadataPayload	String	Optional suggested metadata JSON patch, in the case the target entity has such

Comment

Textual commentary in the shape of feedback, arguments for claims, questions for authors, and similar type of information.

Path

If the annotation target is a research component, the annotation author can further specify the location that the annotation refers to. A standard for the different media types is yet to be set, but here are some illustrative examples:

Media type	Path syntax
text	Line and column number
appplication/pdf	Page index and X/Y percentage coordinates for a selection
video	File timestamp
application/json	JSONPath

Metadata payload

The annotation can attach a suggested delta to the metadata. This is useful for suggesting adding, modifying, or removing metadata entries. The suggestion is credited to the annotation author, but it's up to the target owner if they choose to apply the suggestions. Regardless, the suggestion is still available. The exact specification of this format is pending, but likely some representation of a JSON CRDT patch.

Annotation targets

Annotations can technically target any type of protocol entity, but there are some particularly obvious applications.

Research object

The annotation is considered to apply to the entire research object. This can be used to leave feedback or questions for the author. A valid assignment has these fields set:

Field	Set?
researchObjectID	✅
researchObjectVersion	✅
targetID	❌
targetVersion	❌
dagNode	❌
pathToNode	❌
locationOnFile	❌

Research component

The annotation is related to the research object context, but refers to a specific research component. This can be used to leave feedback, but also to submit a metadata delta for the author to consider. A valid assignment has these fields set:

Field	Set?
researchObjectID	✅
researchObjectVersion	✅
targetID	✅
targetVersion	✅
dagNode	❌ (transitive from component)
pathToNode	❌ (transitive from component)
locationOnFile	Depends: on the file itself or a particular section

DAG node (file in tree)

The annotation is related to the research object context, but refers to a specific file in the tree. This can be used to leave feedback or questions on a paper, a piece of code, or part of a dataset. A valid assignment has these fields set:

Field	Set?
researchObjectID	✅
researchObjectVersion	✅
targetID	❌
targetVersion	❌
dagNode	✅
pathToNode	✅
locationOnFile	Depends: the file itself or a particular section

Do note that metadata is mainly suggested against components, because that holds the authorative metadata file. A gateway could find and suggest component metadata updates from raw DAG node annotations, or choose to consider it community contributed metadata.

Annotation (a reply)

The annotation is related to the research object and, transitively, the location of the parent annotation. This can be used to reply to feedback or questions. A valid assignment has these fields set:

Field	Set?
researchObjectID	✅
researchObjectVersion	✅
targetID	✅ (parent annotation)
targetVersion	✅ (parent annotation)
dagNode	❌
pathToNode	❌
locationOnFile	❌

Public and private workflows

In some applications of annotations, it may make sense for the content no to be available until a later point in time. Examples of this could be anonymous peer review, non-public conversation, et cetera. In this case, created annotations could be anchored according to the Sidetree implementation, but its content not made publicly available. That allows the content to be revealed later, with proofs of who authored what and when it was created.

Visibility

Not all authors may want public commentary on their works, in which case gateways could decide to only show annotations made on entities where the creator has selected to accept this. This is a gateway implementation detail, as the underlying data graph is permissionless and has no notion of blocking data contribution from authors.