MIRA is a vocabulary for representing modular research objects and the relations between them. Stencila documents can now carry those objects directly: claims, evidence, questions, protocols, and requests are block nodes with identifiers, rich content, and typed relations.

The complete example used on this page is a synthetic dawn-chorus study at The Deerstone in County Wicklow. It was chosen as a nod to the venue of MIRA's inaugural gathering; its data and scientific conclusions are explicitly illustrative. The setting is real—The Deerstone describes its rewilding work—but the study and observations are not.

In MyST, use directives named claim, evidence, question, protocol, and request. Give every object that participates in a relation a stable id, and point to a local object with #id:

Relation targets can also be absolute identifiers. This lets a document refer to a study or another research object published elsewhere:

The same objects can be authored in Quarto Markdown:

Or in Stencila Markdown:

MyST and QMD currently provide the most complete syntax for authoring relations. The decoder recognizes relation property names in kebab case, snake case, camel case, or the corresponding MIRA local spelling. See the Markdown directive decoder for the MyST, QMD, and SMD mappings.

In Stencila's document editor, select one or more blocks and wrap them as a claim, evidence, question, protocol, or request. Research objects remain part of the editable document rather than becoming detached graph records. Their property panel lets you assign a persistent identifier and add relations to another object in the document or to an external URI.

The shared Stencila representation is defined by ResearchObject. Its content accepts normal document blocks, while relations uses a constrained MIRA-derived relation vocabulary. This is why a research object can contain formatted prose or code and still participate in the graph. The editor uses native ResearchObject wrappers and authoring commands together with a relation property control.

Run stencila graph with a .mira.json or .mira.jsonld output filename:

The strict --output-losses abort option is useful for demonstrations and automation: export stops if content cannot be represented faithfully. Stencila resolves local references, retains external identifiers, and writes the research objects and relations into the JSON-LD @graph. The graph construction and export paths are visible in the document graph implementation and stencila graph exporter.

A compact part of the result looks like this. Relations are first-class graph items with their own identifiers, source, and destination:

When the source is a committed file inside a Git repository, the exported @context can include an @base built from its repository, revision, and path metadata. Local fragment identifiers then expand to the exact document version that declared them.

MIRA's description is an Item. Stencila serializes each research object's block content as compact OXA JSON, stores that JSON string in description.content, and sets the sibling description.format to application/vnd.oxa+json.

For easier inspection with jq, parse that nested JSON string:

Paragraphs, headings, code blocks, emphasis, strong text, and inline code have direct OXA mappings. Other Stencila nodes use OXA's evolving generic representation and may report conversion losses. The exact MIRA-to-OXA bridge is implemented in the MIRA codec.

The integration is bidirectional. Stencila decodes MIRA JSON-LD into a Graph, reconstructing the five supported research-object types, their OXA content, and their relations. It can then be converted to a Stencila graph serialization or rendered directly:

The same authored relations can be rendered as a focused graph:

Stencila currently maps five concrete ResearchObject types to MIRA:

It supports all eleven authored relation kinds: supports, supportedBy, opposes, opposedBy, addresses, addressedBy, follows, grounds, is_grounded_in, request_for, and request_target.

MIRA also defines Study, but Stencila does not yet have a corresponding ResearchObject block. For now, evidence and requests can refer to studies by absolute identifiers, as the Deerstone example does. A typed Stencila claim such as a theorem or hypothesis exports as mira:Claim, but its Stencila-specific claimType is reported as a loss. Use an untyped claim when strict, lossless MIRA export is required.