Nanoarguments: Vocabulary Survey and Model Specification

Author
Virginia Balseiro
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

https://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." Extends schema:CreativeWork.
  • schema:Question: "A specific question - e.g. from a user seeking answers online, or collected in a Frequently Asked Questions (FAQ) document." Extends schema: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:Annotation
  • oa:hasBody / oa:hasTarget
  • oa:Motivation
  • oa:motivatedBy
  • oa: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

http://purl.org/spar/amo

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 like amo: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:Qualifier is a simple degree-of-certainty modifier ("certainly," "possibly," "presumably"), without support for more complex cases such as linking caveats.
  • AMO's amo:Rebuttal is a restriction on a claim's validity ("unless X happens"). It is narrower than the everyday "rebuttal" usage and not directly equivalent to a cito:disputes reply.
  • 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)

https://www.w3.org/TR/prov-o/

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:Agent
  • prov: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

http://evidenceontology.org/

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:argument
  • sio:evidence
  • sio: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:Note
  • as:Object, as:actor, as:object
  • as: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

https://www.w3.org/TR/ldn/

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:SpecificResource narrowing 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 of as:inReplyTo: a contribution may carry one, the other, both, or neither.

    A plain as:inReplyTo with 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 of as: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 a sio: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 from prov:wasDerivedFrom (which is about derivation, not realization) and from sio: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.

Orthogonal layers. The annotation sub:annot (an oa:Annotation) carries the anchoring relations oa:hasTarget to the target, oa:hasBody to the content node sub:statement, and oa:motivatedBy to a motivation (oa:assessing). The same sub:statement (a schema:Statement) carries the rhetorical relations cito:disputes and as:inReplyTo directly to the target. Anchoring lives on the annotation, rhetorical relations on the content node, and the body and content node are the same RDF resource. oa:hasTarget oa:hasBody oa:motivatedBy cito:disputes as:inReplyTo sub:annot(oa:Annotation) oa:assessing(oa:Motivation) sub:statement(schema:Statement) target annotation layer — anchoring discourse layer — rhetorical
The annotation layer carries anchoring (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.

Provenance and authorship

This model follows the nanopublication guidelines for authorship and provenance.

Authorship of the nanopublication is recorded in two places: the assertion's creator in the provenance graph, the nanopublication's creator in the pubinfo graph. The two are conceptually distinct and may identify different agents.

Assertion authorship (provenance graph)

The provenance graph records who is responsible for the content of the assertion and where the assertion came from:

sub:assertion prov:wasAttributedTo <agent-IRI> ;
  prov:wasDerivedFrom <source-IRI> .

<agent-IRI> is an ORCID for a human author or a stable IRI for a non-human agent. <source-IRI> (where applicable) identifies the source the assertion was derived from (a paper, dataset, experiment, upstream nanopub). Optionally, prov:generatedAtTime records when the assertion was made.

The provenance graph MUST contain at least one triple referencing the assertion. prov:wasAttributedTo is the recommended way to do this when an agent is responsible for the assertion's content.

When the assertion graph contains an oa:Annotation resource, the annotation's authorship is by default the same as the assertion's: a single prov:wasAttributedTo on the assertion attributes the assertion's content, including any annotation resources within it, to one agent. If the annotation's authorship differs from the assertion's, the annotation resource carries its own attribution, using oa:creator (or dct:creator) directly on the annotation. The common case where this matters is third-party annotation: a curator publishes a nanopub whose assertion contains a pre-existing claim by Author A and an annotation by the curator associating that claim with a target.

Nanopub authorship (pubinfo graph)

The pubinfo graph records who is responsible for the act of publishing the nanopub. The canonical convention is as follows:

this: dct:creator <agent-IRI> ;
  dct:created "..."^^xsd:dateTime .

The pubinfo SHOULD contain attribution and a timestamp. The pubinfo graph also carries the cryptographic signature (sub:sig with npx:signedBy, npx:hasPublicKey, npx:hasSignature), the license (dct:license), and any indexing properties such as npx:hasNanopubType.

Assertion creator and nanopub creator

The assertion creator (provenance graph) and the nanopub creator (pubinfo graph) may identify different agents. There are two common patterns:

  • Same agent in both graphs: a human publishes their own assertion through an application, or an autonomous bot does both. The same IRI appears in each graph but under different predicates (prov:wasAttributedTo in provenance, dct:creator in pubinfo). This is not a redundancy, as each graph attributes a different act to the same agent.
sub:provenance {
  sub:assertion prov:wasAttributedTo orcid:0000-0003-1062-5576 .
}

sub:pubinfo {
  this: dct:creator orcid:0000-0003-1062-5576 ;
    dct:created "2026-06-08T08:08:08Z"^^xsd:dateTime .
}
  • Different agents in each graph: one agent authored the assertion content; a different agent (a curator, a colleague, an organization, an automated publishing tool) is responsible for the publication act. This pattern lets a publisher republish someone else's assertion without claiming the content as their own, or attribute content to its source while taking responsibility for putting it on the network.
sub:provenance {
  sub:assertion prov:wasAttributedTo orcid:0000-0003-3934-0072 .
}

sub:pubinfo {
  this: dct:creator orcid:0000-0003-0183-6910 ;
    dct:created "..."^^xsd:dateTime .
}

Tool-mediated publishing

When a tool publishes a nanopub on behalf of a human author, the assertion creator and the nanopub creator may identify different agents (Assertion creator and nanopub creator). Some patterns include:

  • Naming the tool as dct:creator of the nanopub directly (the tool is the publisher)
  • Keeping the human as dct:creator of the nanopub and naming the tool via a separate property (e.g. npx:wasCreatedAt)
  • Recording the originating session, template, or input as prov:wasDerivedFrom

This specification does not commit to a single pattern, and follows whatever the publishing tool emits. Queries that need to identify the tool that produced a given nanopub can look for any of these properties. A canonical emission convention may be added in a later version once the implementation milestone has chosen one.

Agents

Agents are identified by IRIs. A human is identified by an ORCID; a bot, tool, or automated agent is identified by a stable IRI managed by the project or organization that operates it (e.g. https://w3id.org/kpxl/gen/terms/RoCrateBot ). The model does not require type declaration on agents. An ORCID and a bot IRI are both just creators, treated symmetrically.

Pubinfo may optionally carry a foaf:name on the agent's IRI for display purposes. This is convenience metadata for UIs, not a requirement of the model.

Source application or platform

When a contribution originates from a federated platform or decentralized clientside tool (a discussion forum, an annotation tool, an authoring environment), the originating platform may be recorded in pubinfo so UIs can display source attribution ("via discussit.org") and federation logic can route accordingly. Two properties are seen for this purpose:

  • npx:wasCreatedAt: used by Nanodash to identify the publishing tool.
  • oa:renderedVia: Web Annotation property used by dokieli to identify the tool an annotation was rendered through.

Their exact semantic distinction is not documented in this specification. This document treats either as a source of contribution marker for query and display purposes. The choice of which property to emit is left to the publishing tool based on their specific context.

Nanopub type indexing

The pubinfo graph carries npx:hasNanopubType indicating the primary rhetorical or content type of the nanopub (e.g. cito:disputes, schema:Statement, cito:qualifies). Used for indexing and query.

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:renderedVia source, 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:inReplyTo on 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:wasCreatedAt or oa: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:supports and 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:Argument container (amo:Claim is 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 (or schema:Question) carrying its discourse relations directly.
  • Annotation-based representation shows the same thread re-expressed using oa:Annotation wrappers. 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:qualifies for qualifying caveats and add it to the recommended CiTO subset (Discourse-graph relations), retiring the previously minted na:qualifies term and its rdfs:subPropertyOf cito:discusses fallback.
  • 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:introduces to each example to mark the content node the nanopublication mints (Worked examples).

Acknowledgements

Thanks to Sarven Capadisli for review and feedback.