Nanoarguments: Vocabulary Survey and Model Specification
- Editors
- Virginia Balseiro
- Tobias Kuhn
- Ashley Caselli
- Published
- Latest published version
- https://knowledgepixels.com/nanoarguments/model.html
- Version
- 0.1.1
- Document Type
- Specification
Abstract
This is the first published deliverable of the Nanoarguments project: a vocabulary and model specification for representing scholarly discourse and evidence as decentralized, signed, queryable knowledge graphs.
The project's goal is to let scholarly conversations (claims and responses, support and dispute, evidence and caveats) live as structured, persistent data on a federated network, instead of as ephemeral threads tied to specific platforms. A claim posted in one venue should be referenceable from another; a response should be linkable to its target by IRI regardless of where either was published; the resulting graph should be queryable across documents, tools, and communities. This requires a shared vocabulary for the relations that make a discussion legible as discourse: who supports or disputes what, who replies to whom, what counts as evidence, what cites what.
Audience
This document is for readers interested in adopting, extending, or reviewing the model: researchers, ontology contributors, tool developers, and community organizers working on decentralized scholarly communication. The model specification assumes familiarity with linked data and RDF; the vocabulary survey introduces each candidate ontology, so prior familiarity with every one is not required.
Content
This document includes:
- A vocabulary survey reviewing the W3C and community ontologies that already cover parts of this space: Web Annotation, CiTO, PROV-O, SIO, ECO, SEPIO, AMO, Activity Streams, ActivityPub, Linked Data Notifications. Each entry describes the vocabulary's scope and how this model uses it.
- A model specification defining the Nanoarguments model: how content nodes are typed and identified, what relations connect them, how the model maps onto the nanopublication container format and projects to ActivityPub for federation, and what query patterns the resulting graph supports.
Out of scope
Some work that complements this specification is being addressed in other Nanoarguments project milestones:
- Templates and query infrastructure. Standard query templates and templates for data input.
- Integrations with tools and platforms. Connector implementations bridging the model to external tools and federation protocols.
- Pilot rollout and adoption. Validation and iteration with pilot communities.
The following are out of scope for the project as a whole and may be addressed by future work:
- Aggregation queries such as equivalence resolution, evidence aggregation, and agent-level metrics. Deferred to a follow-up specification effort (Level 2: aggregation queries).
- A canonical convention for which property identifies a contribution's source application (Source application or platform).
Vocabulary Survey
Scope of this Survey
This survey reviews vocabularies and ontologies that cover parts of what a model for decentralized scholarly discourse needs to express: statements as content nodes, relations between statements (support, dispute, citation, reply), provenance and evidence typing, federation, and notification delivery.
The vocabularies covered fall into four loose groups: vocabularies for typing statements (schema.org, SIO), vocabularies for typing relations between statements (CiTO, AMO), vocabularies for recording provenance and evidence (PROV-O, ECO, SEPIO), and vocabularies for anchoring, federating, and notifying (Web Annotation, Activity Streams, ActivityPub, LDN).
Out of scope: vocabularies covering domain-specific scientific knowledge (e.g. Gene Ontology, ChEBI), bibliographic metadata vocabularies beyond the citation-typing case (e.g.: BIBO, FaBIO), and general purpose upper ontologies (e.g. BFO). They either operate at the wrong layer or address concerns adjacent to discourse-graph representation.
Each entry below describes the vocabulary's scope, core terms, and notable limitations or design boundaries. How the Nanoarguments model uses each vocabulary is documented separately in the model specification (Part II).
Existing Vocabularies and Ontologies
Schema.org
Summary: Schema.org is a collaborative vocabulary maintained by Google, Yahoo,
Microsoft, and Yandex, primarily used for marking up structured data on web pages so search engines and
other consumers can interpret content. It defines a hierarchy of types (with schema:Thing at
the root) and a flat set of properties, deployed in JSON-LD, Microdata, and RDFa across a substantial
fraction of the web.
Schema.org's coverage is broad (events, places, products, creative works, medical concepts,
organizations, persons) and growing through a public extension process. Several of its types are directly
relevant to scholarly discourse, including schema:CreativeWork, schema:Article,
schema:Statement, and schema:Claim.
Core terms (relevant subset):
schema:Statement: "a statement about something, for example a fun or interesting fact." Extendsschema:CreativeWork.schema:Question: "A specific question - e.g. from a user seeking answers online, or collected in a Frequently Asked Questions (FAQ) document." Extendsschema:Comment.schema:Claim: "a specific, factually-oriented claim that could be the itemReviewed in a ClaimReview." Targeted at fact-checking contexts.schema:CreativeWork: the broad parent class for authored works, with properties for author, date, license, and so on.
Limitations / scope notes:
schema:Statement is currently in schema.org's "new" area, meaning its definition may evolve
as implementations and feedback shape it. Adopters should track changes.
The distinction between schema:Statement and schema:Claim is formality and
intent: a Claim is the kind of factually-oriented assertion that gets reviewed by fact-checkers, while a
Statement is broader and includes everyday observations, opinions, hypotheses, and other contributions
that don't necessarily commit to being factually evaluated.
Schema.org's relations vocabulary is sparse for discourse purposes: it covers authorship, dates, licensing, and structural document properties, but not rhetorical relations between contributions. A model that uses schema.org for typing typically needs to combine it with another vocabulary (CiTO, PROV-O) for relations.
Web Annotation Data Model (W3C Rec, 2017)
https://www.w3.org/TR/annotation-model/
Summary: The Web Annotation Data Model is a W3C Recommendation defining a structured way
to associate a body of information with a target resource. It supports arbitrary targets (documents, parts
of documents via selectors, other annotations, arbitrary URIs), multiple bodies, and motivation typing
through oa:Motivation and the oa:motivatedBy predicate. It is the foundation of
W3C's annotation work, including the Web Annotation Protocol (delivery) and Web Annotation Vocabulary
(extended terms).
Core terms:
oa:Annotationoa:hasBody/oa:hasTargetoa:Motivationoa:motivatedByoa:hasSelector(text-quote selector, XPath selector, etc.; see selectors)oa:purpose(role of a body vs motivation which is the role of the whole annotation - enables multi body annotations with distinct roles)
Limitations/gaps:
Web Annotation's scope is body-to-target anchoring with typed motivation, with optional selectors for
parts of the target. This model uses oa:Annotation where this scope fits and uses direct
triples between content nodes for rhetorical relations where no anchoring is involved (Relations on statements, Discourse and annotation layers).
oa:motivatedBy specifically expects an oa:Motivation instance as its object.
Using it to carry a CiTO property is a domain stretch; placing the discourse relation on the body resource
(which is itself an addressable RDF resource) is a cleaner alternative.
Argument Model Ontology
Summary: AMO is a SPAR ontology that encodes Toulmin's
model of argument. It defines six interrelated components (claim, evidence, warrant, backing,
qualifier, rebuttal) organized as roles within an amo:Argument container. The first three
(claim, evidence, warrant) are mandatory components of an argument; the others are optional. AMO is
aligned with CiTO, which this model already uses.
Core terms:
amo:Argument(the container)amo:ArgumentationEntity(umbrella for the component types)amo:Claim,amo:Evidence,amo:Warrant,amo:Backing,amo:Qualifier,amo:Rebuttal(the components)- Object properties:
amo:hasClaim,amo:hasEvidence,amo:hasWarrant(and the others), plus inter-component relations likeamo:proves(evidence → claim),amo:leadsTo(warrant → claim),amo:backs(backing → warrant),amo:forces(qualifier → claim),amo:isValidUnless(claim → rebuttal)
Limitations / gaps:
The component classes are definitionally tied to an argument container. Every individual typed
amo:Claim is by the ontology's semantics the claim of some amo:Argument. Typing
a content node amo:Claim would commit us to a Toulmin-structured argument the content node
may not be part of.
The natural-language scope is also narrower than what we need. amo:Claim is "a fact that
must be established," operationally the thing a Toulmin argument is trying to prove. Our use case is
broader: any propositional statement contributes to the discourse graph, whether or not it is the
conclusion of an argument.
- AMO's
amo:Qualifieris a simple degree-of-certainty modifier ("certainly," "possibly," "presumably"), without support for more complex cases such as linking caveats. - AMO's
amo:Rebuttalis a restriction on a claim's validity ("unless X happens"). It is narrower than the everyday "rebuttal" usage and not directly equivalent to acito:disputesreply. - AMO remains a useful candidate for pilot communities that want to structure contributions according to Toulmin's framework. See the spec's Extensions for richer structure for the extension.
SEPIO - Scientific Evidence and Provenance Information Ontology
https://github.com/monarch-initiative/SEPIO-ontology/wiki/The-SEPIO-Core-Ontology
Summary: SEPIO is a domain ontology developed by the Monarch Initiative for representing scientific evidence and its provenance. It targets graded support across multiple independent evidence items, conflicting lines of evidence on a shared proposition, and chained provenance trails. SEPIO was developed in alignment with the Global Alliance for Genomics and Health (GA4GH) information model and is used in clinical and biomedical evidence-curation infrastructure.
Core terms:
- Assertion
- Proposition
- Evidence Line
- Evidence Item
- Contribution
Limitations/gaps:
SEPIO's structural topology is fixed: assertions, propositions, evidence lines, and evidence items each play specific roles. Adopting SEPIO as the core would force every contribution into this topology, which is heavier than most Nanoarguments' use cases need.
The published OWL ontology has also drifted from the GA4GH-aligned information model that SEPIO's documentation references, so adoption would require pinning to a specific version.
PROV-O (W3C Rec)
Summary: PROV-O is the W3C-recommended OWL ontology for representing provenance. It
captures who generated what, when, from what source, through what activity. The core triad is
prov:Entity, prov:Activity, and prov:Agent. Attribution,
derivation, generation, association, and informing relations connect them. PROV-O is widely deployed
across scientific data publishing, including the nanopublication ecosystem, where it is the canonical
vocabulary for the provenance graph.
Core terms:
prov:Entity,prov:Activity,prov:Agentprov:wasGeneratedBy,prov:used,prov:wasAttributedTo,prov:wasDerivedFrom,prov:wasAssociatedWith,prov:wasInformedBy
Limitations/gaps:
PROV-O is generic by design. Its relations cover provenance broadly without committing to domain-specific
notions of derivation, evaluation, or implementation. The Nanoarguments model uses PROV-O for what it
covers (attribution, derivation, generation) and mints na:tests and
na:implements for the domain-specific relations PROV-O doesn't aim to provide (Relations on statements).
The nanopublication network uses PROV-O conventions specific to its own structure; this specification follows those conventions (Provenance and authorship) per the nanopublication guidelines.
CiTO - Citation Typing Ontology
https://sparontologies.github.io/cito/current/cito.html
Summary: CiTO is a SPAR ontology that types citations and references between scholarly works (and, more generally, between any two resources where one references the other). It defines a flat set of citation-typing properties grouped into positive, negative, neutral, and factual categories. CiTO is widely deployed across the scholarly publishing ecosystem and is one of the most commonly reused vocabularies for typed scholarly relationships.
Core terms:
cito:cites/cito:isCitedBy- positive:
cito:supports,cito:confirms,cito:extends - negative:
cito:disputes,cito:refutes,cito:critiques,cito:disagreesWith - neutral:
cito:reviews,cito:discusses,cito:citesAsAuthority - factual:
cito:usesMethodIn,cito:usesDataFrom,cito:citesAsDataSource cito:Citation+cito:hasCitingEntity/cito:hasCitationCharacterization/cito:hasCitedEntity
Limitations/gaps:
CiTO was primarily designed to type citations between scholarly works (document/work-level citation relationships). It can represent statement-level citation and support relations, but statement-centric knowledge graphs are not its principal design focus. Systems such as dokieli use it at statement or fragment granularity by treating statements as addressable RDF resources and applying CiTO relations between them.
ECO - Evidence & Conclusion Ontology
Summary: ECO is a community-curated controlled vocabulary of evidence categories used to describe the type of evidence supporting a scientific assertion. It provides a structured hierarchy of evidence types crossed with assertion methods, producing leaf terms like "experimental evidence used in manual assertion" or "computational evidence used in automatic assertion." ECO is widely deployed in biomedical resources including the Gene Ontology and UniProt.
Core terms:
- evidence (root class)
- assertion method (root class - manual assertion / automatic assertion)
- evidence x assertion method cross-product leaf terms
Limitations/gaps:
ECO types evidence; it does not type contributions more broadly. It complements rather than replaces
other vocabularies in this survey. A contribution typed sio:evidence may optionally carry an
ECO class as a finer-grained subtype (Optional evidence typing with ECO). ECO is not required by the model.
SIO - Semanticscience Integrated Ontology
https://github.com/MaastrichtU-IDS/semanticscience
Summary: SIO is a broad upper-level ontology for the description of scientific objects, processes, and information. It provides class hierarchies for propositions, evidence, hypotheses, arguments, processes, and roles, along with general-purpose relations. SIO sits above more specific domain ontologies and provides shared abstractions across biology, chemistry, and other sciences.
Core terms:
sio:argumentsio:evidencesio:justification
Limitations/gaps:
SIO provides the class hierarchy for hypothesis, evidence, argument, and proposition. This model uses SIO classes for typing and supplies the relations among them through CiTO and project-minted predicates (Relations on statements, SIO subtypes).
ActivityPub
https://www.w3.org/TR/activitypub/
Summary: ActivityPub is a W3C-recommended decentralized social networking protocol built on Activity Streams 2.0. It defines a client-to-server API (clients post to a user's outbox) and a server-to-server federation protocol (servers deliver activities to recipients' inboxes). Each actor has an inbox and an outbox.
Core terms:
- Actor (inbox / outbox)
- delivery (outbox -> inbox federation)
Limitations/gaps:
ActivityPub is a federation transport, not a content vocabulary. This model's content lives in nanopublications, and the connector layer projects nanopublications into ActivityPub activities when federation is needed. ActivityPub and nanopublications have different commitments (federated messaging vs signed immutable graphs), and the connector cannot be fully faithful to both (Alignment with ActivityPub).
Activity Streams 2.0 (alignment target)
https://www.w3.org/TR/activitystreams-vocabulary/
Summary: Activity Streams 2.0 is a W3C-recommended vocabulary for describing social
activities and objects on the web. It defines a small set of activity types (Create, Update, Like, Follow,
and others) and object types (Note, Article, etc.), along with relations like as:inReplyTo
(threading), as:object, and as:actor. It is the data model underlying
ActivityPub federation.
Core terms:
as:Activity(and activity subtypes: Create, Update, etc.)as:Noteas:Object,as:actor,as:objectas:inReplyTo
Limitations / gaps:
Activity Streams covers conversational structure and social activities. This model uses
as:inReplyTo for threading and uses CiTO predicates for rhetorical typing, treating the two
as independent axes (Discourse-graph relations).
Linked Data Notifications
Summary: Linked Data Notifications (LDN) is a W3C-recommended protocol for delivering
structured notifications to a target resource's inbox. The target declares an ldp:inbox IRI;
senders POST notification payloads to it. LDN is transport-only and the payload contents are arbitrary
linked data (typically Activity Streams activities or Web Annotations).
Core terms:
ldp:inbox
Limitations/gaps:
LDN delivers notifications but does not define their semantics. The model treats LDN as one available transport channel for annotation delivery; the model itself doesn't depend on LDN being used.
Background
Reply-To in dokieli:
A reply in dokieli is a Web Annotation with the motivation oa:replying. Its
oa:hasTarget points at the resource being replied to, which can be either an article or another
annotation (so nested replies work by chaining targets).
For federation, the same reply also carries as:inReplyTo from Activity Streams, pointing at
the same target. The reply itself is stored in the author's personal storage as a first-class resource with
its own URL and provenance.
To make the target aware of the reply, dokieli uses Linked Data Notifications: it discovers the target's
ldp:inbox and POSTs a small notification (who, when, motivation, license, link to fetch the
body). dokieli also checks for oa:annotationService in case the article advertises one (where
annotations can be sent to).
The notification is a pointer, not the reply body. The target's UI then pulls the full reply when it needs
to display the thread. The annotation may also reach other destinations depending on what the user does with
it. If the user sends it to their ActivityPub outbox, the AP server wraps it in an activity and delivers a
notification to the inboxes of the user's followers. If the user sends it to an
oa:annotationService (which points to an Annotation Container managed via the Web Annotation
Protocol), the annotation is deposited into that container. These are separate user actions from publishing
the annotation to storage and notifying the target via LDN; storage, LDN, AP outbox, and annotation
container are independent transports, and a user may do any subset of them.
So one reply travels through three transports: storage (where it lives), LDN (how the target finds out about it), and ActivityPub (how federated platforms find out about it). The Web Annotation shape is just how the reply describes itself.
Web Annotation caveat for our use case:
The Web Annotation model associates a body with a target via a typed motivation. The body's standing as a contribution comes from what the body is, not from being wrapped in an annotation. Peer reviews, replies, and bookmarks are all annotations in WA terms, and all unambiguously first-class.
The design question for this model is where the discourse relations between contributions should live: on
the annotation that wraps a body-target association, or directly on the content node. Putting
cito:disputes on the annotation alongside oa:hasBody and oa:hasTarget
conflates two separable jobs. The annotation reifies the body-target association; the discourse relation
expresses a rhetorical stance. Putting the discourse relations directly on the content node, and letting the
annotation do only the anchoring it was designed for, produces a layering that is queryable from either
angle (Discourse and annotation layers).
The resulting layers are orthogonal. The discourse layer lives on content nodes; the annotation layer wraps a body-target association when one is needed. Both layers are first-class.
Resolution:
We considered two approaches: wrapping every contribution as an oa:Annotation to match
dokieli's emission convention, or restricting oa:Annotation to cases where its machinery is
actually doing work, anchoring via a selector, carrying a motivation, or otherwise saying something about
the body-target association that a direct triple between content nodes cannot carry.
The orthogonal-layers model (Discourse and annotation layers) resolves this. Discourse relations live on content nodes as direct
triples, giving them a single canonical placement that supports one-hop queries for "what does this
contribution dispute or support." oa:Annotation is used when an authoring tool produces an
annotation as part of its flow (as dokieli does when a user selects a passage), or when a contribution needs
to express anchoring, motivation, or other association-level information.
The two are not alternatives. A contribution may have only discourse triples on its content node. It may have only an annotation, associating a body with a target. It may have both: the body of an annotation is itself a content node and carries its own discourse relations independently of being wrapped. Implementations consuming the network should be prepared to receive any of these shapes.
Criteria for using oa:Annotation:
Use oa:Annotation when the link itself needs to be a first-class object — when there is
something to say about the connection between body and target that a direct triple between content nodes
cannot carry. Cases:
- The link carries a selector or
oa:SpecificResourcenarrowing the target to a specific section, fragment, region, or other part inside a target (a passage of a paper, a sentence inside a claim). - The link carries a motivation (
oa:replying,oa:assessing,oa:reviewing, etc.) that the contribution wants to record alongside the body-target association. - The contribution is authored by a tool that produces annotations as part of its flow (dokieli is the canonical case. Every contribution it authors naturally has an annotation wrapper because that is its native shape).
- The annotation is authored separately from the body and target (for example, a curator associating two pre-existing nanopubs).
Model Specification
Scope and purpose
This section specifies the model for discourse and evidence graphs.
The model is composed from existing vocabularies (Web Annotation, CiTO, PROV, SIO, with optional ECO and
SEPIO extensions) and a small project-owned namespace (na:), aligned with the nanopublication
container format and projected to ActivityPub for federation.
The model's goal is to express scholarly discourse (claims, replies, support, dispute, caveat, citation) and the evidence that grounds it, in a form that is decentralized, signed, persistent, and queryable across documents.
Namespaces
| Prefix | Namespace |
|---|---|
na: |
https://w3id.org/nanoarguments/ |
oa: |
http://www.w3.org/ns/oa# |
cito: |
http://purl.org/spar/cito/ |
prov: |
http://www.w3.org/ns/prov# |
as: |
https://www.w3.org/ns/activitystreams# |
sio: |
http://semanticscience.org/resource/ |
schema: |
https://schema.org/ |
np: |
http://www.nanopub.org/nschema# |
npx: |
http://purl.org/nanopub/x/ |
dct: |
http://purl.org/dc/terms/ |
rdf: |
http://www.w3.org/1999/02/22-rdf-syntax-ns# |
xsd: |
http://www.w3.org/2001/XMLSchema# |
orcid: |
https://orcid.org/ |
Entity classes (content nodes)
A content node is a first-class RDF resource carrying the substantive content of a contribution. Each
content node has its own identifier, a type (see this section and Statement subtypes), a value (typically as
rdf:value), and may carry discourse relations (Relations on statements) and citations as direct triples. Content
nodes are not annotations, and do not depend on a host resource for their standing. Their identity persists
across the nanopublications and queries that reference them.
The same content node is referenced in several ways depending on context. As a bare node in a nanopub:
sub:statement a schema:Statement ;
rdf:value "Pigeons can pass a modified mirror-mark test." .
As the subject of discourse relations (Relations on statements), the claim now takes a position toward another existing claim expressed as a direct triple:
sub:statement a schema:Statement ;
rdf:value "Pigeons can pass a modified mirror-mark test." ;
cito:disputes <https://w3id.org/np/RAxample/claim> .
<https://w3id.org/np/RAxample/claim> is the IRI of a previously published nanopub's
content node, e.g. "Self-recognition is restricted to great apes". Disputing it does not require knowing
more about it than its IRI.
As the body of an annotation that anchors it to a passage, the claim is now also positioned at a specific sentence inside an external document (in this example, a paper) via Web Annotation's selectors:
sub:statement a schema:Statement ;
rdf:value "Pigeons can pass a modified mirror-mark test." .
sub:annot a oa:Annotation ;
oa:hasBody sub:statement ;
oa:hasTarget [ a oa:SpecificResource ;
oa:hasSource <https://example.org/chimpanzee-self-recognition> ;
oa:hasSelector [ a oa:TextQuoteSelector ;
oa:exact "no nonhuman species other than the great apes" ;
oa:prefix "We conclude that " ;
oa:suffix " demonstrates self-recognition." ] ] .
The previous examples either reference a content node as a whole, or, in the annotation case, narrow the
target via oa:SpecificResource with a selector. The same selector pattern is also available as
the object of a direct discourse relation, without an enclosing oa:Annotation. This lets a
contribution dispute, qualify, or otherwise relate to a specific fragment of a target rather than the target
in full:
sub:statement a schema:Statement ;
rdf:value "Recent field studies show generalization to wild populations." ;
cito:disputes [ a oa:SpecificResource ;
oa:hasSource <https://w3id.org/np/RAxample-prior-claim/claim> ;
oa:hasSelector [ a oa:TextQuoteSelector ;
oa:exact "the training does not generalize to wild populations" ] ] .
Here the prior claim is something like "Pigeons can pass a modified mirror-mark test, but the training does
not generalize to wild populations." The disputer is taking issue only with the generalization caveat, not
the main proposition. The selector narrows the target without an oa:Annotation wrapper around
the disputer's own claim.
In every case the content node is the same RDF resource (sub:statement); what changes is which
other resources reference it and at what granularity. Being the body of an annotation does not constrain a
content node's discourse content: the same sub:statement could simultaneously carry
cito:supports, cito:qualifies, citations, or other discourse triples while being
wrapped in an annotation that anchors it to a passage.
This specification adopts schema:Statement as the base type for content nodes.
schema:Statement is defined by schema.org as "a statement about something." This model uses it
broadly to cover any propositional or near-propositional contribution to the discourse graph: claims,
hypotheses, observations, findings, expressions of stance, and so on. A statement carries its content in
rdf:value, may carry citations to external works via CiTO citation properties (Context relations), and may
target other content nodes via discourse-graph relations (Discourse-graph relations).
A second content node type is schema:Question, used when a contribution asks rather than
asserts: a request for clarification, evidence, or opinion. schema:Question is defined by
schema.org as "a specific question, e.g. from a user seeking answers online, or collected in a Frequently
Asked Questions (FAQ) document." Like schema:Statement, it extends
schema:CreativeWork and carries its content in rdf:value. A question may target
another content node via as:inReplyTo (when the question is asked in response to a prior
contribution) or via CiTO predicates when the question is rhetorically loaded (e.g.
cito:disputes for a question that implicitly challenges its target). Answers to a question are
separate content nodes that target the question; the relationship between question and answer is expressed
by the same discourse-graph relations the model uses for any other pair of contributions.
Schema.org's documentation recommends schema:text for the content of a
schema:Statement. This specification uses rdf:value instead, to align with the
nanopublication ecosystem's existing conventions (which already use rdf:value,
rdfs:label, dct:title, and skos:prefLabel across various contexts)
and to preserve the option of typed literal values such as ^^rdf:HTML. Consumers expecting
schema:text may need to fall back to rdf:value when reading nanopublications
produced under this specification.
Relations on statements
Two kinds of relations sit on statements: those that connect statements to other statements (forming the discourse graph), and those that connect a statement to a non-statement resource, anchoring the discourse graph to external context (papers, datasets, methods, protocols).
Discourse-graph relations (Statement to Statement)
These relations have a statement as subject and a statement as object. They form the graph among contributions and are what discourse-graph traversal queries (Level 1: graph-traversal queries) operate on.
Reused from CiTO
The model reuses CiTO properties without modification. The recommended subset for this version:
cito:supports: the subject contribution argues in favor of the target.cito:disputes: the subject contribution argues against the target.cito:extends: the subject contribution builds on the target.cito:agreesWith: the subject contribution endorses the target.cito:qualifies: the subject contribution places conditions or restrictions on the target (a caveat or qualification).
CiTO's full property set is available where the listed subset does not fit. Implementations should prefer the subset to maximize interoperability and UI legibility.
Reused from Activity Streams
as:inReplyTo: the subject is a reply to the target, expressing conversational threading. Used on content nodes when the contribution is a direct response to another contribution. CiTO predicates capture rhetorical stance (cito:supports,cito:disputes, etc.) and are independent ofas:inReplyTo: a contribution may carry one, the other, both, or neither.A plain
as:inReplyTowith no CiTO predicate is valid and useful for generic conversational replies. Where a contribution carries a rhetorical stance toward its target, however, a CiTO predicate is recommended in addition to or in place ofas:inReplyTo, because typed discourse is the central value the model provides. A contribution that combines threading and rhetorical type, for example, a dispute published as a direct response to the disputed claim, should carry both predicates.
Minted in na:
na:tests: the subject contribution (a study, experiment, analysis, or similar investigative contribution) tests the target contribution (typically asio:hypothesis, SIO subtypes). (Proposed; pending pilot confirmation.)
Context relations (Statement to non-Statement)
These relations have a statement as subject and a non-statement resource as object, typically an external paper, dataset, method, protocol, or other resource that exists outside the discourse graph.
Reused from CiTO (citation subset):
cito:citesAsEvidence: the subject cites the target as evidence.cito:citesAsAuthority: the subject cites the target as authoritative.cito:usesDataFrom: the subject reuses the target's data.
Reused from PROV:
prov:wasDerivedFrom: the subject was generated from the target. Covers derivation and grounding ("this finding follows from this study," "this conclusion is derived from this evidence"). If both subject and object happen to be statements, the relation effectively also lives in the discourse graph; the default case is statement-to-external-resource.
Minted in na:
na:implements: the subject is a concrete realization of the target specification. A protocol implements a method; an experimental procedure implements a study design; a piece of code implements an algorithm. Distinct fromprov:wasDerivedFrom(which is about derivation, not realization) and fromsio:realizes(which relates a process to a realizable entity rather than two informational entities). (Proposed; pending pilot confirmation.)
Relations from other layers
The annotation layer (The annotation layer) introduces annotation properties (oa:hasBody,
oa:hasTarget, oa:hasSelector) that sit on oa:Annotation resources
rather than on content nodes. These describe anchoring (where a body is positioned in relation to a
target) and are distinct from discourse relations in subject type and purpose.
The body of an annotation is itself a content node and may carry the full discourse vocabulary. A body
can simultaneously be the body of an oa:Annotation (positioning it at a target) and the
subject of cito:supports, cito:disputes, cito:qualifies, scientific
relations, or citation triples. The annotation framing does not flatten or restrict the body's discourse
content; the body's RDF resource is independently a full participant in the discourse layer.
Discourse and annotation layers
The model has two orthogonal layers, each carrying a different kind of statement about a contribution.
The discourse layer
The discourse layer lives on content nodes as direct triples. Discourse relations
(cito:supports, cito:disputes, cito:qualifies,
as:inReplyTo, and other CiTO relations from the subset in section 4) sit on the content node
and connect it to its target. This layer carries statements about how a contribution relates to others in
the discussion: who supports or disputes what, who replies to whom, who qualifies whose claims.
The discourse layer is always present on a content node that has any discourse standing regardless of the authoring context. It is the canonical representation of the discussion structure and what aggregation queries (Query patterns) operate on.
The annotation layer
The annotation layer uses oa:Annotation to anchor a body (typically a content node) with a
target. The annotation is a separate, addressable resource with its own properties: a body, a target,
optionally a selector narrowing the target to a part of it, and optionally a motivation. The target may be
a document, a content node, or a part of either, expressed where appropriate as an
oa:SpecificResource carrying an oa:hasSelector. This layer carries statements
about positioning and association: which body is attached where, with what motivation, by whom.
The canonical case is an annotation tool that operates on documents: every tool-authored contribution naturally carries an annotation layer with a document or part of a document as the target (dokieli is one such tool). Annotation targets are not restricted to documents. Any addressable resource can be a target, including other content nodes, allowing one annotation to position a contribution within a target produced elsewhere in the network.
Orthogonality
The two layers are independent:
- A contribution may participate in the discourse layer only. Example: a claim disputing another claim, published directly to the network, with no annotation associating it with a target.
- A contribution may be the body of an annotation only. Example: a comment that associates itself with a passage of a document, without taking any rhetorical position toward another content node.
- A contribution may participate in both. Example: a rebuttal that disputes a counter-argument (discourse layer) and is also associated with a specific passage of that counter-argument via an annotation (annotation layer).
When both layers are present they describe the contribution from different angles and do not duplicate
information. The annotation's body and the content node share an IRI as they are the same RDF resource.
The triples about that resource appear once with discourse relations stated directly on it, and the
annotation references it as oa:hasBody. Anchoring stays on the annotation while the
rhetorical relations stay on the content node.
oa:hasTarget, oa:hasBody);
the discourse layer carries rhetorical relations (cito:disputes, as:inReplyTo)
on the content node.Layers and nanopublications
The two layers may coexist in a single nanopublication when they represent one authoring act. A dokieli user who selects a passage and writes a rebuttal in one operation produces a single nanopub whose assertion graph contains both the rebuttal content node with its discourse triples and the annotation anchoring the body to the passage.
The two layers occupy different nanopublications when they represent separate acts, for example, a content node published in one nanopub by one author, later anchored to a passage by an annotation in a separate nanopub by a different author or at a different time.
Interoperability between the two shapes
The two representations are alternate views of the same underlying fact, and are bidirectionally derivable at query time.
Alignment with Nanopublications
Each contribution is published as one signed nanopublication. The three-graph nanopub structure maps onto the model as follows:
- Assertion graph: contains the content node(s) and their discourse relations. The body of the contribution.
- Provenance graph: contains PROV statements about the assertion: who authored it, when it was made, and what source (if any) it was derived from.
- PublicationInfo graph: contains metadata about the nanopub itself: creator, creation time,
oa:renderedViasource,npx:hasNanopubType, license, version.
Cryptographic signing and trusty URIs are handled by the nanopub layer; the model adds nothing on top.
Aggregation across contributions (e.g. "claims plus their supporting and refuting contributions") is a query pattern over the nanopublication network. The query template is given in section 10.
Alignment with ActivityPub
The model bridges to ActivityPub through two mechanisms:
as:inReplyToon content nodes (section 4.1.3) makes generic conversational threading legible to Activity Streams consumers. CiTO predicates (cito:supports,cito:disputes, and others) on content nodes serve the same threading purpose for more specific rhetorical relations, since any CiTO relation between two content nodes is a form of response. The ActivityPub connector may surface either as threading.- Source-application markers in pubinfo (Source application or platform), whether emitted as
npx:wasCreatedAtoroa:renderedVia, identify the originating platform. The ActivityPub connector uses this to route outbox-to-inbox delivery and to attribute source ("via discussit.org") in receiving UIs.
The connector itself is out of scope for this spec; it is specified in the dokieli/ActivityPub extensions milestone.
ActivityPub and nanopublications differ in their fundamental commitments: ActivityPub centers on user-controlled data and federated messaging; nanopublications center on open, immutable, signed knowledge graphs. The connector therefore cannot be fully faithful to both. Nanopublications are the system of record for the model's content; ActivityPub serves as a federation transport.
Statement subtypes
The base type for any contribution to the discourse graph is schema:Statement (Entity classes). Where a
contribution's nature is more specific, it may also be typed with one of the subtypes below. These remain
optional; minimal deployments may use schema:Statement throughout.
SIO subtypes
The following SIO classes may be used alongside schema:Statement to refine the
contribution's intrinsic type.
sio:hypothesis(SIO_000284): "a proposed explanation for a phenomenon."sio:evidence(SIO_001394): "the body of facts or information indicating whether a belief or proposition is true or valid."sio:argument(SIO_000259): "a set of one or more declarative sentences (or propositions) known as the premises along with another declarative sentence (or proposition) known as the conclusion."
All three are subclasses of sio:proposition (SIO_000256), defined as "a
sentence expressing something true or false." SIO does not define structural relationships between these
concepts; relating them is this model's job, via the discourse-graph relations (Discourse-graph relations).
These types are intrinsic. A statement is sio:evidence because of what it is (a body of
facts bearing on a proposition), not because of which claim it currently grounds. What is contextual is
the role the statement plays in a particular argument, and that role is expressed by the discourse-graph
relations connecting it to other statements.
Additional SIO classes (e.g. for studies, findings, conclusions, beliefs) may be added as pilot use cases surface specific needs.
Optional evidence typing with ECO
A statement typed sio:evidence (or a domain-specific subclass) may optionally carry a
finer-grained evidence type drawn from the Evidence and Conclusion Ontology (ECO). ECO is a
community-curated controlled vocabulary of evidence categories ("experimental evidence," "computational
evidence," "author statement used in manual assertion," etc.), widely used by biomedical resources
including the Gene Ontology and UniProt.
ECO typing is structural-model-neutral: it adds a dct:type (or equivalent) pointing at an
ECO class on an existing statement and does not change this model's topology.
Example: a finding typed as evidence, with the SIO class for the intrinsic type and an ECO class for the leaf category:
sub:finding a sio:evidence ;
rdf:value "Pigeons pecked at mirror-visible stickers but not at hidden controls." ;
dct:type eco:0000006 ; # experimental evidence
cito:supports sub:hypothesis .
A receiver that understands neither SIO nor ECO still sees a statement with a value and a
cito:supports relation; the typing degrades gracefully.
Extensions for richer structure
Two existing ontologies provide structure this model's core does not commit to, but which some pilot communities may want. Each is available as an extension.
- SEPIO: richer evidence-line semantics. Where a contribution needs to group multiple
findings into a single coherent line of support or refutation, the recommended representation is an
intermediate statement that the findings target via
cito:supportsand that itself targets the claim. This handles most evidence-grouping cases without additional machinery. For use cases that require richer semantics — graded support across multiple independent lines, chained provenance trails, contradicting lines on a shared proposition, or alignment with existing SEPIO-based infrastructure — SEPIO (see Part I) may be adopted as an extension. Adoption would require pinning to a specific version (the published OWL ontology has drifted from the GA4GH-aligned information model). - AMO: Toulmin-structured arguments. Where a contribution should be structured
according to Toulmin's model of argument, distinguishing claim, evidence, warrant, backing, qualifier,
and rebuttal as named components of an explicit argument, the Argument Model Ontology (AMO) may be
adopted. AMO is a SPAR ontology aligned with CiTO, with first-class classes for each Toulmin component
and object properties for the relations between them. This model's core does not adopt AMO's component
classes because they are definitionally tied to an
amo:Argumentcontainer (amo:Claimis equivalently defined as the claim of some argument) and the core treats statements as standing on their own without commitment to a Toulmin framework.
Query patterns (informative)
Queries over the discourse and evidence graph operate at two distinct levels. The model is designed to support the first level directly; the second level depends on additional vocabulary work and is out of scope for this version of this specification.
Level 1: graph-traversal queries
Level 1 queries follow typed edges between content nodes, with no aggregation, and equivalent claims are not merged. The pattern supports retrieving a contribution's incoming and outgoing relations by type, walking reply or rhetorical chains to arbitrary depth, and resolving each contribution's author and pubinfo metadata. Each contribution is returned as a distinct result row; equivalent contributions by different agents are not merged.
Find all contributions targeting a given claim, with their relation type:
SELECT ?relation ?contribution ?author WHERE {
?contribution ?relation <CLAIM_IRI> ;
^prov:wasAttributedTo ?author .
FILTER (?relation IN (cito:supports, cito:disputes,
cito:qualifies, cito:agreesWith,
cito:extends, as:inReplyTo))
}
Walk a reply tree from a root:
SELECT ?contribution ?parent ?relation ?author WHERE {
?contribution as:inReplyTo+ <ROOT_CLAIM_IRI> ;
as:inReplyTo ?parent ;
^prov:wasAttributedTo ?author .
OPTIONAL {
?contribution ?relation ?parent .
FILTER (?relation IN (cito:supports, cito:disputes,
cito:qualifies, cito:agreesWith,
cito:extends))
}
}
Find scientific reasoning chains:
SELECT ?contribution ?type ?predecessor ?relation WHERE {
?contribution (prov:wasDerivedFrom|na:tests|na:implements)+ <HYPOTHESIS_IRI> ;
a ?type ;
?relation ?predecessor .
FILTER (?relation IN (prov:wasDerivedFrom, na:tests, na:implements))
FILTER (?type IN (sio:hypothesis, sio:evidence, sio:argument, schema:Statement))
}
Implementations are expected to provide query templates of this shape in the templates and query patterns milestone of the Nanoarguments project.
Level 2: aggregation queries (out of scope for this version)
Aggregation queries derive summary information by grouping, counting, ranking, or otherwise combining results across multiple contributions. Categories include:
- Equivalent-claim sets.
- Evidence aggregation (grouped lines of evidence, graded support, conflict resolution).
- Agent-level aggregation (per-author counts, agreement clusters, derived signals).
These queries depend on vocabulary and convention additions that this spec does not commit to. They are out of scope and deferred to a follow-up specification effort.
Worked examples
This section presents one complete discourse thread expressed in the model. To demonstrate the orthogonal-layers framing of Discourse and annotation layers, the thread is shown in two representations:
- Direct discourse representation uses direct discourse triples between content nodes. Each contribution is a nanopublication whose
assertion graph contains a
schema:Statement(orschema:Question) carrying its discourse relations directly. - Annotation-based representation shows the same thread re-expressed using
oa:Annotationwrappers. Each contribution after the root is published as an annotation targeting a previous contribution, as an annotation tool would emit. The body of each annotation is the same content node that appears in Direct discourse representation; the annotation adds anchoring to the target. - Discourse rooted in an annotation of a paper shows a different thread rooted in an annotation of an external paper. Subsequent contributions annotate previous annotations, producing a chain anchored to the paper at the root.
Together, Direct discourse representation and Annotation-based representation demonstrate the orthogonal-layers framing of Discourse and annotation layers: the same discourse expressed with and without annotation wrappers, and the equivalence between the two (Equivalence of the two representations). Discourse rooted in an annotation of a paper demonstrates a different scholarly workflow where annotations are first-class from the start.
Direct discourse representation
Each contribution is a nanopublication. Discourse relations are direct triples on the content nodes.
The thread consists of:
- A root claim about gut microbiota and vaccine response.
- A supporting contribution.
- A caveat noting a methodological concern.
- A counter-argument disputing the root claim.
- A rebuttal of the counter-argument, citing evidence.
- An open question requesting clarification.
Root claim
@prefix this: <https://w3id.org/np/RAxample-alvarez-microbiota-claim> .
@prefix sub: <https://w3id.org/np/RAxample-alvarez-microbiota-claim/> .
@prefix np: <http://www.nanopub.org/nschema#> .
@prefix npx: <http://purl.org/nanopub/x/> .
@prefix prov: <http://www.w3.org/ns/prov#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix orcid: <https://orcid.org/> .
@prefix schema: <https://schema.org/> .
@prefix cito: <http://purl.org/spar/cito/> .
sub:Head {
this: a np:Nanopublication ;
np:hasAssertion sub:assertion ;
np:hasProvenance sub:provenance ;
np:hasPublicationInfo sub:pubinfo .
}
sub:assertion {
sub:claim a schema:Statement ;
rdf:value "Certain gut microbiota profiles have stronger mRNA vaccine responses." ;
cito:citesAsEvidence <https://doi.org/10.1234/kim-2025-microbiota-vaccine> .
}
sub:provenance {
sub:assertion prov:wasAttributedTo orcid:0000-0001-alvarez-b ;
prov:generatedAtTime "2026-05-24T08:00:00Z"^^xsd:dateTime .
}
sub:pubinfo {
this: dct:creator orcid:0000-0001-alvarez-b ;
dct:created "2026-05-24T08:00:00Z"^^xsd:dateTime ;
npx:introduces sub:claim ;
npx:hasNanopubType schema:Statement .
}
The root claim carries no discourse-graph relation because it has no target.
Support
@prefix this: <https://w3id.org/np/RAxample-wang-support> .
@prefix sub: <https://w3id.org/np/RAxample-wang-support/> .
sub:Head {
this: a np:Nanopublication ;
np:hasAssertion sub:assertion ;
np:hasProvenance sub:provenance ;
np:hasPublicationInfo sub:pubinfo .
}
sub:assertion {
sub:reason a schema:Statement ;
rdf:value "Their SCFA data is compelling." ;
cito:supports <https://w3id.org/np/RAxample-alvarez-microbiota-claim/claim> .
}
sub:provenance {
sub:assertion prov:wasAttributedTo orcid:0000-0002-wang-p ;
prov:generatedAtTime "2026-05-24T09:00:00Z"^^xsd:dateTime .
}
sub:pubinfo {
this: dct:creator orcid:0000-0002-wang-p ;
dct:created "2026-05-24T09:00:00Z"^^xsd:dateTime ;
npx:introduces sub:reason ;
npx:hasNanopubType cito:supports .
}
Caveat
@prefix this: <https://w3id.org/np/RAxample-medaibot-caveat> .
@prefix sub: <https://w3id.org/np/RAxample-medaibot-caveat/> .
sub:Head {
this: a np:Nanopublication ;
np:hasAssertion sub:assertion ;
np:hasProvenance sub:provenance ;
np:hasPublicationInfo sub:pubinfo .
}
sub:assertion {
sub:caveat a schema:Statement ;
rdf:value "Be cautious about interpreting causality here without intervention studies." ;
cito:qualifies <https://w3id.org/np/RAxample-alvarez-microbiota-claim/claim> .
}
sub:provenance {
sub:assertion prov:wasAttributedTo <https://example.org/agents/medai-bot> ;
prov:generatedAtTime "2026-05-24T10:10:00Z"^^xsd:dateTime .
}
sub:pubinfo {
this: dct:creator <https://example.org/agents/medai-bot> ;
dct:created "2026-05-24T10:10:00Z"^^xsd:dateTime ;
npx:introduces sub:caveat ;
npx:hasNanopubType cito:qualifies .
}
Counter-argument
@prefix this: <https://w3id.org/np/RAxample-moller-counterargument> .
@prefix sub: <https://w3id.org/np/RAxample-moller-counterargument/> .
sub:Head {
this: a np:Nanopublication ;
np:hasAssertion sub:assertion ;
np:hasProvenance sub:provenance ;
np:hasPublicationInfo sub:pubinfo .
}
sub:assertion {
sub:counterclaim a schema:Statement ;
rdf:value "The correlation could be confounded by diet." ;
cito:disputes <https://w3id.org/np/RAxample-alvarez-microbiota-claim/claim> .
}
sub:provenance {
sub:assertion prov:wasAttributedTo orcid:0000-0003-moller-m ;
prov:generatedAtTime "2026-05-24T10:28:00Z"^^xsd:dateTime .
}
sub:pubinfo {
this: dct:creator orcid:0000-0003-moller-m ;
dct:created "2026-05-24T10:28:00Z"^^xsd:dateTime ;
npx:introduces sub:counterclaim ;
npx:hasNanopubType cito:disputes .
}
Rebuttal
@prefix this: <https://w3id.org/np/RAxample-criticaibot-rebuttal> .
@prefix sub: <https://w3id.org/np/RAxample-criticaibot-rebuttal/> .
@prefix as: <https://www.w3.org/ns/activitystreams#> .
sub:Head {
this: a np:Nanopublication ;
np:hasAssertion sub:assertion ;
np:hasProvenance sub:provenance ;
np:hasPublicationInfo sub:pubinfo .
}
sub:assertion {
sub:rebuttal a schema:Statement ;
rdf:value "Note that [Kim 2025] controlled for fiber intake using dietary logs." ;
cito:citesAsEvidence <https://doi.org/10.1234/kim-2025-microbiota-vaccine> ;
as:inReplyTo <https://w3id.org/np/RAxample-moller-counterargument/counterclaim> ;
cito:disputes <https://w3id.org/np/RAxample-moller-counterargument/counterclaim> .
}
sub:provenance {
sub:assertion prov:wasAttributedTo <https://example.org/agents/criticai-bot> ;
prov:generatedAtTime "2026-05-24T10:48:00Z"^^xsd:dateTime .
}
sub:pubinfo {
this: dct:creator <https://example.org/agents/criticai-bot> ;
dct:created "2026-05-24T10:48:00Z"^^xsd:dateTime ;
npx:introduces sub:rebuttal ;
npx:hasNanopubType cito:disputes .
}
Open question
@prefix this: <https://w3id.org/np/RAxample-perez-question> .
@prefix sub: <https://w3id.org/np/RAxample-perez-question/> .
sub:Head {
this: a np:Nanopublication ;
np:hasAssertion sub:assertion ;
np:hasProvenance sub:provenance ;
np:hasPublicationInfo sub:pubinfo .
}
sub:assertion {
sub:question a schema:Question ;
rdf:value "Has anyone tested this in non-trial populations?" ;
as:inReplyTo <https://w3id.org/np/RAxample-alvarez-microbiota-claim/claim> .
}
sub:provenance {
sub:assertion prov:wasAttributedTo orcid:0000-0002-perez-l ;
prov:generatedAtTime "2026-05-24T11:15:00Z"^^xsd:dateTime .
}
sub:pubinfo {
this: dct:creator orcid:0000-0002-perez-l ;
dct:created "2026-05-24T11:15:00Z"^^xsd:dateTime ;
npx:introduces sub:question ;
npx:hasNanopubType schema:Question .
}
Annotation-based representation
The same six contributions, expressed as a thread where each contribution after the root is published as
an oa:Annotation targeting a previous contribution, as an annotation tool would emit. Bodies
are content nodes carrying the same discourse relations as in Direct discourse representation; the annotation wrapper adds
anchoring. The root claim (Root claim) is the same nanopublication shown in Root claim, with no annotation.
A note on targets: an annotation can target any addressable resource (a document, a passage of a
document, an image region, another annotation, a content node, or any other URI). The choice depends on
the context and use case. In the examples below, the contributions are annotations of a claim published as
a nanopublication, so each annotation's oa:hasTarget is the canonical nanopublication IRI
(https://w3id.org/np/...). This anchoring is distinct from the discourse relation: the
oa:hasTarget records where the annotation is positioned (the nanopublication as a citeable
artifact), while the discourse relation on the content node (cito:supports,
cito:qualifies, as:inReplyTo, etc.) points at the content node being responded to
(the /claim resource), matching the direct representation in Direct discourse representation. The two
may legitimately point at different granularities (see Counter-argument, where the discourse
relation targets the whole claim while the anchoring narrows to a phrase).
Root claim
Identical to Root claim. No annotation; the root has no target to anchor to.
Support (as annotation)
@prefix this: <https://w3id.org/np/RAxample-wang-support-annotation> .
@prefix sub: <https://w3id.org/np/RAxample-wang-support-annotation/> .
@prefix oa: <http://www.w3.org/ns/oa#> .
sub:Head {
this: a np:Nanopublication ;
np:hasAssertion sub:assertion ;
np:hasProvenance sub:provenance ;
np:hasPublicationInfo sub:pubinfo .
}
sub:assertion {
sub:reason a schema:Statement ;
rdf:value "Their SCFA data is compelling." ;
cito:supports <https://w3id.org/np/RAxample-alvarez-microbiota-claim/claim> .
sub:annot a oa:Annotation ;
oa:hasBody sub:reason ;
oa:hasTarget <https://w3id.org/np/RAxample-alvarez-microbiota-claim> ;
oa:motivatedBy oa:assessing .
}
sub:provenance {
sub:assertion prov:wasAttributedTo orcid:0000-0002-wang-p ;
prov:generatedAtTime "2026-05-24T09:00:00Z"^^xsd:dateTime .
}
sub:pubinfo {
this: dct:creator orcid:0000-0002-wang-p ;
dct:created "2026-05-24T09:00:00Z"^^xsd:dateTime ;
npx:introduces sub:reason ;
npx:hasNanopubType cito:supports .
}
The content node sub:reason carries the same value and cito:supports triple as
in Support. The annotation wraps it and anchors it to the root. A consumer reading the discourse graph
sees the same cito:supports edge in either representation.
Caveat (as annotation)
@prefix this: <https://w3id.org/np/RAxample-medaibot-caveat-annotation> .
@prefix sub: <https://w3id.org/np/RAxample-medaibot-caveat-annotation/> .
sub:Head {
this: a np:Nanopublication ;
np:hasAssertion sub:assertion ;
np:hasProvenance sub:provenance ;
np:hasPublicationInfo sub:pubinfo .
}
sub:assertion {
sub:caveat a schema:Statement ;
rdf:value "Be cautious about interpreting causality here without intervention studies." ;
cito:qualifies <https://w3id.org/np/RAxample-alvarez-microbiota-claim/claim> .
sub:annot a oa:Annotation ;
oa:hasBody sub:caveat ;
oa:hasTarget <https://w3id.org/np/RAxample-alvarez-microbiota-claim> ;
oa:motivatedBy oa:assessing .
}
sub:provenance {
sub:assertion prov:wasAttributedTo <https://example.org/agents/medai-bot> ;
prov:generatedAtTime "2026-05-24T10:10:00Z"^^xsd:dateTime .
}
sub:pubinfo {
this: dct:creator <https://example.org/agents/medai-bot> ;
dct:created "2026-05-24T10:10:00Z"^^xsd:dateTime ;
npx:introduces sub:caveat ;
npx:hasNanopubType cito:qualifies .
}
Counter-argument (as annotation, with selector)
This contribution disputes a specific phrase of the root claim, demonstrating selector-narrowed targeting.
@prefix this: <https://w3id.org/np/RAxample-moller-counterargument-annotation> .
@prefix sub: <https://w3id.org/np/RAxample-moller-counterargument-annotation/> .
sub:Head {
this: a np:Nanopublication ;
np:hasAssertion sub:assertion ;
np:hasProvenance sub:provenance ;
np:hasPublicationInfo sub:pubinfo .
}
sub:assertion {
sub:counterclaim a schema:Statement ;
rdf:value "The correlation could be confounded by diet." ;
cito:disputes <https://w3id.org/np/RAxample-alvarez-microbiota-claim/claim> .
sub:disputedPhrase a oa:SpecificResource ;
oa:hasSource <https://w3id.org/np/RAxample-alvarez-microbiota-claim> ;
oa:hasSelector [ a oa:TextQuoteSelector ;
oa:exact "stronger mRNA vaccine responses" ] .
sub:annot a oa:Annotation ;
oa:hasBody sub:counterclaim ;
oa:hasTarget sub:disputedPhrase ;
oa:motivatedBy oa:assessing .
}
sub:provenance {
sub:assertion prov:wasAttributedTo orcid:0000-0003-moller-m ;
prov:generatedAtTime "2026-05-24T10:28:00Z"^^xsd:dateTime .
}
sub:pubinfo {
this: dct:creator orcid:0000-0003-moller-m ;
dct:created "2026-05-24T10:28:00Z"^^xsd:dateTime ;
npx:introduces sub:counterclaim ;
npx:hasNanopubType cito:disputes .
}
The annotation's target is an oa:SpecificResource selecting a particular phrase from the
source. Møller's counter-argument disputes the "stronger response" part specifically; the selector
disambiguates this. The cito:disputes on the content node still points at the whole claim,
reflecting that the rhetorical disagreement is with the claim as a whole even when the anchoring picks out
a phrase.
Rebuttal (annotation of an annotation)
The rebuttal targets Møller's annotation, demonstrating that annotations can be targets of other annotations.
@prefix this: <https://w3id.org/np/RAxample-criticaibot-rebuttal-annotation> .
@prefix sub: <https://w3id.org/np/RAxample-criticaibot-rebuttal-annotation/> .
sub:Head {
this: a np:Nanopublication ;
np:hasAssertion sub:assertion ;
np:hasProvenance sub:provenance ;
np:hasPublicationInfo sub:pubinfo .
}
sub:assertion {
sub:rebuttal a schema:Statement ;
rdf:value "Note that [Kim 2025] controlled for fiber intake using dietary logs." ;
cito:citesAsEvidence <https://doi.org/10.1234/kim-2025-microbiota-vaccine> ;
as:inReplyTo <https://w3id.org/np/RAxample-moller-counterargument-annotation/counterclaim> ;
cito:disputes <https://w3id.org/np/RAxample-moller-counterargument-annotation/counterclaim> .
sub:annot a oa:Annotation ;
oa:hasBody sub:rebuttal ;
oa:hasTarget <https://w3id.org/np/RAxample-moller-counterargument-annotation> ;
oa:motivatedBy oa:replying .
}
sub:provenance {
sub:assertion prov:wasAttributedTo <https://example.org/agents/criticai-bot> ;
prov:generatedAtTime "2026-05-24T10:48:00Z"^^xsd:dateTime .
}
sub:pubinfo {
this: dct:creator <https://example.org/agents/criticai-bot> ;
dct:created "2026-05-24T10:48:00Z"^^xsd:dateTime ;
npx:introduces sub:rebuttal ;
npx:hasNanopubType cito:disputes .
}
The annotation uses oa:motivatedBy oa:replying since the contribution is a
direct reply. The body carries cito:disputes and as:inReplyTo as direct triples,
exactly as in Rebuttal; the annotation adds the body-target association.
Open question (as annotation)
@prefix this: <https://w3id.org/np/RAxample-perez-question-annotation> .
@prefix sub: <https://w3id.org/np/RAxample-perez-question-annotation/> .
sub:Head {
this: a np:Nanopublication ;
np:hasAssertion sub:assertion ;
np:hasProvenance sub:provenance ;
np:hasPublicationInfo sub:pubinfo .
}
sub:assertion {
sub:question a schema:Question ;
rdf:value "Has anyone tested this in non-trial populations?" ;
as:inReplyTo <https://w3id.org/np/RAxample-alvarez-microbiota-claim/claim> .
sub:annot a oa:Annotation ;
oa:hasBody sub:question ;
oa:hasTarget <https://w3id.org/np/RAxample-alvarez-microbiota-claim> ;
oa:motivatedBy oa:questioning .
}
sub:provenance {
sub:assertion prov:wasAttributedTo orcid:0000-0002-perez-l ;
prov:generatedAtTime "2026-05-24T11:15:00Z"^^xsd:dateTime .
}
sub:pubinfo {
this: dct:creator orcid:0000-0002-perez-l ;
dct:created "2026-05-24T11:15:00Z"^^xsd:dateTime ;
npx:introduces sub:question ;
npx:hasNanopubType schema:Question .
}
The annotation uses oa:motivatedBy oa:questioning (a standard Web Annotation
motivation) for the question case.
Equivalence of the two representations
The content nodes in Direct discourse representation and Annotation-based representation are the same: same IRIs, same values, same discourse-graph
relations. A query for "all contributions targeting Alvarez's claim" returns the same result set in either
representation, because the cito:supports, cito:disputes,
cito:qualifies, and as:inReplyTo triples sit on the content nodes regardless of
whether an annotation wraps them.
What differs between the two representations is the anchoring: Annotation-based representation contributions additionally carry
oa:Annotation resources with oa:hasTarget pointing at the contribution they
respond to. Direct discourse representation contributions have no such anchoring; the discourse-graph relation is the only
structural connection.
For a network mixing both representations (some contributions published as plain nanopubs, others as
annotations), the discourse-graph traversal queries of Level 1: graph-traversal queries operate uniformly. Implementations interested
in the additional anchoring information can additionally query oa:hasTarget to recover where
annotations are positioned.
Discourse rooted in an annotation of a paper
The previous examples started with a claim published as a nanopublication. A different common pattern starts with an annotation of an external document: a contributor reads a paper, selects a passage, and writes a claim about it. Subsequent contributions respond by annotating the original annotation, producing a chain where each annotation's target is the previous one.
This section uses a different topic from Direct discourse representation and Annotation-based representation to keep the patterns distinct. The thread:
- A root annotation of a passage in a paper, asserting a counter-claim.
- A support annotation of the root, citing evidence.
- A counter-argument annotation of the root.
- A rebuttal annotation of the counter-argument, citing further evidence.
Root annotation of a paper passage
@prefix this: <https://w3id.org/np/RAxample-pigeon-mirror-root> .
@prefix sub: <https://w3id.org/np/RAxample-pigeon-mirror-root/> .
@prefix np: <http://www.nanopub.org/nschema#> .
@prefix npx: <http://purl.org/nanopub/x/> .
@prefix prov: <http://www.w3.org/ns/prov#> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix orcid: <https://orcid.org/> .
@prefix schema: <https://schema.org/> .
@prefix oa: <http://www.w3.org/ns/oa#> .
@prefix cito: <http://purl.org/spar/cito/> .
sub:Head {
this: a np:Nanopublication ;
np:hasAssertion sub:assertion ;
np:hasProvenance sub:provenance ;
np:hasPublicationInfo sub:pubinfo .
}
sub:assertion {
sub:claim a schema:Statement ;
rdf:value "Pigeons can pass a modified mirror-mark test." ;
cito:disputes <https://example.org/chimpanzee-self-recognition> .
sub:annot a oa:Annotation ;
oa:hasBody sub:claim ;
oa:hasTarget [ a oa:SpecificResource ;
oa:hasSource <https://example.org/chimpanzee-self-recognition> ;
oa:hasSelector [ a oa:TextQuoteSelector ;
oa:exact "no nonhuman species other than the great apes" ;
oa:prefix "We conclude that " ;
oa:suffix " demonstrates self-recognition." ] ] ;
oa:motivatedBy oa:assessing .
}
sub:provenance {
sub:assertion prov:wasAttributedTo orcid:0000-0002-1234-5678 ;
prov:generatedAtTime "2026-05-24T11:05:00Z"^^xsd:dateTime .
}
sub:pubinfo {
this: dct:creator orcid:0000-0002-1234-5678 ;
dct:created "2026-05-24T11:05:03Z"^^xsd:dateTime ;
npx:introduces sub:claim ;
npx:hasNanopubType cito:disputes .
}
The contributor reads a paper claiming "no nonhuman species other than the great apes demonstrates
self-recognition," selects that passage, and publishes a counter-claim. The annotation's target is an
oa:SpecificResource with a text-quote selector identifying the exact passage in the paper.
The body is the counter-claim, which carries cito:disputes directly pointing at the paper.
Support annotation (of the root annotation)
@prefix this: <https://w3id.org/np/RAxample-pigeon-mirror-support> .
@prefix sub: <https://w3id.org/np/RAxample-pigeon-mirror-support/> .
sub:Head {
this: a np:Nanopublication ;
np:hasAssertion sub:assertion ;
np:hasProvenance sub:provenance ;
np:hasPublicationInfo sub:pubinfo .
}
sub:assertion {
sub:evidence a schema:Statement ;
rdf:value "Trained pigeons pecked at body stickers only visible via a mirror, not at hidden controls." ;
cito:citesAsEvidence <https://doi.org/10.1111/pigeon-mirror-mark-test> ;
cito:supports <https://w3id.org/np/RAxample-pigeon-mirror-root/claim> .
sub:annot a oa:Annotation ;
oa:hasBody sub:evidence ;
oa:hasTarget <https://w3id.org/np/RAxample-pigeon-mirror-root/annot> ;
oa:motivatedBy oa:assessing .
}
sub:provenance {
sub:assertion prov:wasAttributedTo orcid:0000-0003-2345-6789 ;
prov:generatedAtTime "2026-05-24T12:30:00Z"^^xsd:dateTime .
}
sub:pubinfo {
this: dct:creator orcid:0000-0003-2345-6789 ;
dct:created "2026-05-24T12:30:00Z"^^xsd:dateTime ;
npx:introduces sub:evidence ;
npx:hasNanopubType cito:supports .
}
The support is itself an annotation: its target is the root annotation (sub:annot of the
root nanopub), not the paper. The body cites evidence and carries cito:supports pointing at
the root's body (the counter-claim). The two structures coexist: the annotation chain records that this
contribution was authored as a response to the root annotation, while the discourse-graph triple records
that it supports the root claim.
Counter-argument annotation (of the root annotation)
@prefix this: <https://w3id.org/np/RAxample-pigeon-mirror-counter> .
@prefix sub: <https://w3id.org/np/RAxample-pigeon-mirror-counter/> .
sub:Head {
this: a np:Nanopublication ;
np:hasAssertion sub:assertion ;
np:hasProvenance sub:provenance ;
np:hasPublicationInfo sub:pubinfo .
}
sub:assertion {
sub:counterclaim a schema:Statement ;
rdf:value "The training conditions may not generalize beyond the lab setting." ;
cito:disputes <https://w3id.org/np/RAxample-pigeon-mirror-root/claim> .
sub:annot a oa:Annotation ;
oa:hasBody sub:counterclaim ;
oa:hasTarget <https://w3id.org/np/RAxample-pigeon-mirror-root/annot> ;
oa:motivatedBy oa:assessing .
}
sub:provenance {
sub:assertion prov:wasAttributedTo orcid:0000-0004-3456-7890 ;
prov:generatedAtTime "2026-05-24T14:15:00Z"^^xsd:dateTime .
}
sub:pubinfo {
this: dct:creator orcid:0000-0004-3456-7890 ;
dct:created "2026-05-24T14:15:00Z"^^xsd:dateTime ;
npx:introduces sub:counterclaim ;
npx:hasNanopubType cito:disputes .
}
A counter-argument, also annotating the root. The annotation's target is the root annotation; the body's
cito:disputes points at the root's claim.
Rebuttal annotation (of the counter-argument)
@prefix this: <https://w3id.org/np/RAxample-pigeon-mirror-rebuttal> .
@prefix sub: <https://w3id.org/np/RAxample-pigeon-mirror-rebuttal/> .
@prefix as: <https://www.w3.org/ns/activitystreams#> .
sub:Head {
this: a np:Nanopublication ;
np:hasAssertion sub:assertion ;
np:hasProvenance sub:provenance ;
np:hasPublicationInfo sub:pubinfo .
}
sub:assertion {
sub:rebuttal a schema:Statement ;
rdf:value "Wild populations of corvids show similar mirror-guided behaviour, suggesting the capacity is not lab-specific." ;
cito:citesAsEvidence <https://doi.org/10.1016/magpie-mirror-self-recognition-review> ;
as:inReplyTo <https://w3id.org/np/RAxample-pigeon-mirror-counter/counterclaim> ;
cito:disputes <https://w3id.org/np/RAxample-pigeon-mirror-counter/counterclaim> .
sub:annot a oa:Annotation ;
oa:hasBody sub:rebuttal ;
oa:hasTarget <https://w3id.org/np/RAxample-pigeon-mirror-counter/annot> ;
oa:motivatedBy oa:replying .
}
sub:provenance {
sub:assertion prov:wasAttributedTo orcid:0000-0005-4567-8901 ;
prov:generatedAtTime "2026-05-24T15:45:00Z"^^xsd:dateTime .
}
sub:pubinfo {
this: dct:creator orcid:0000-0005-4567-8901 ;
dct:created "2026-05-24T15:45:00Z"^^xsd:dateTime ;
npx:introduces sub:rebuttal ;
npx:hasNanopubType cito:disputes .
}
The rebuttal demonstrates the deepest annotation nesting in the example: its target is the
counter-argument's annotation, which is itself targeting the root annotation, which is targeting a passage
in the paper. Each annotation in the chain anchors a contribution to its predecessor. The discourse-graph
triples (cito:disputes, cito:supports, as:inReplyTo) are
independent of this chain and connect the bodies directly.
Notes on the pattern
Two structures coexist throughout the example:
The annotation chain records anchoring: each annotation's oa:hasTarget records what the
contribution was authored relative to (a paper passage, a previous annotation). This structure is what an
annotation-aware client follows to render the thread with anchored selections and nesting.
The discourse graph records rhetorical stance: each body's outgoing CiTO predicates record what it supports, disputes, or qualifies. This structure is what discourse-graph traversal queries (Level 1: graph-traversal queries) operate on, regardless of whether the contributions were authored as annotations.
A consumer interested in pure discourse can ignore the annotations entirely and still recover the full structure of who supports or disputes what. A consumer interested in rendering the thread visually follows the annotation chain to recover the anchoring and the threading. The two structures align because the annotation's body is the same RDF resource that carries the discourse triples (Discourse and annotation layers).
Changelog
Version 0.1.1
- Reuse
cito:qualifiesfor qualifying caveats and add it to the recommended CiTO subset (Discourse-graph relations), retiring the previously mintedna:qualifiesterm and itsrdfs:subPropertyOf cito:discussesfallback. - Standardize the worked examples on slash sub-resource IRIs
for content nodes (
<np>/claim), matching the IRIs produced at signing time (Worked examples). - Add
npx:introducesto each example to mark the content node the nanopublication mints (Worked examples).
Acknowledgements
Thanks to Sarven Capadisli for review and feedback.