Stencila Schema is the canonical model for representing documents, data, code, and execution in Stencila. It defines the node types that flow through parsers, codecs, editors, kernels, and publishing pipelines so that content can be validated, transformed, and exchanged consistently across formats and languages.

Overview

The schema is authored as YAML files in schema/, with each file describing a type, its properties, inheritance, and metadata such as JSON-LD identifiers. The result is an interconnected graph of node types covering creative works, prose, math, code, data structures, execution flow, styling, edits, and configuration.

Why it exists

Stencila supports many input and output formats. A shared schema provides a single source of truth so that:

documents can round-trip between formats with fewer surprises

validation rules and constraints are centralized

type-safe APIs can be generated for multiple languages

semantic identifiers align with JSON-LD and https://schema.org conventions

Relationship to schema.org

Where possible, Stencila adopts schema.org types and properties so that metadata and content are immediately interoperable with existing tools, crawlers, and linked data ecosystems. When schema.org lacks the concepts needed for executable, interactive, or richly structured documents, Stencila extends it with additional types and properties rather than inventing a parallel vocabulary. This keeps common concepts aligned with the wider web while allowing Stencila to model features such as execution, provenance, prompts, and structured data.

Generated artifacts

The Rust crate in rust/schema-gen/ is responsible for turning the YAML source files into concrete outputs used throughout the project. It reads the schema, checks and extends inheritance, expands union types, and then generates:

reference documentation in site/docs/schema/ (this section)

codec capability documentation in docs/formats/

Rust types in rust/schema/src/types.rs

TypeScript types in ts/src/types/ and supporting enums in ts/src/

Python types in python/stencila_types/src/stencila_types/types.py

JSON Schema files in json/*.schema.json

JSON-LD contexts in json/*.jsonld

Kuzu graph schema, migrations, and Rust ORM code in rust/node-db/

Using this reference

Reference documentation for Stencila Schema types is organized by category below. Each type page is generated from its corresponding YAML schema and includes the full set of properties and constraints.

Works

Agent - An AI agent definition.

Article - An article, including news and scholarly articles.

AudioObject - An audio file.

Author - A union type for authors of a CreativeWork or other type.

AuthorRole - An author and their role.

AuthorRoleAuthor - A union type for authors in an AuthorRole.

AuthorRoleName - A controlled author contribution role.

Bibliography - A bibliography loaded from an external source file.

Chat - A chat conversation, usually with a generative AI model.

ChatMessage - A message within a Chat.

ChatMessageGroup - A group of messages, usually alternative model messages, within a Chat.

Claim - A reviewable claim or statement.

ClaimType - A category of claim.

Collection - A collection of creative works or other artifacts.

Comment - A comment on an item.

CreativeWork - A creative work.

CreativeWorkType - A category of creative work.

CreativeWorkVariant - Union type for all types that are descended from CreativeWork

Directory - A directory on a file system.

Figure - A figure.

File - A file on the file system.

HorizontalAlignment - The horizontal alignment of content.

ImageObject - An image file.

InstructionType - An operation requested by an instruction.

LabelType - An automatic labeling category.

MediaObject - A media object.

Periodical - A periodical publication.

Prompt - A prompt for creating or editing document content.

PublicationIssue - A publication issue.

PublicationVolume - A publication volume.

Reference - A reference to a creative work, including books, movies, photographs, software programs, etc.

Review - A review of an item, e.g of an Article or SoftwareApplication.

Skill - An agent skill providing instructions for AI agents.

SoftwareApplication - A software application.

SoftwareSourceCode - Source code for software.

Supplement - A supplementary creative work associated with a document.

Table - A table.

TableCell - A cell within a Table.

TableCellType - The structural role of a table cell.

TableRow - A row within a Table.

TableRowType - The structural role of a table row.

VerticalAlignment - The vertical alignment of content.

VideoObject - A video file.

Workflow - An AI workflow definition.

Prose

Admonition - An admonition within a document.

AdmonitionType - A category of admonition.

Annotation - Annotated content.

AppendixBreak - A break marking the start of appendices.

Block - A union type for block content.

Boundary - A positional boundary marker within inline content.

Citation - A reference to a CreativeWork that is cited in another CreativeWork.

CitationGroup - A group of Citation nodes.

CitationIntent - The rhetorical or factual intent of a citation.

CitationMode - The presentation mode of a citation.

DefinedTerm - A word, name, acronym, phrase, etc. with a formal definition.

Emphasis - Emphasized content.

Heading - A heading.

Icon - An icon, typically rendered using an icon font.

Inline - Union type for valid inline content.

InlinesBlock - A block containing inlines with no other semantics.

Link - A hyperlink to other pages, sections within the same document, resources, or any URL.

List - A list of items.

ListItem - A single item in a list.

ListOrder - The ordering of a list.

Mark - An abstract base type for marked inline content.

Note - A note associated with document content.

NoteType - A category of note placement.

Paragraph - A paragraph.

QuoteBlock - A section quoted from somewhere else.

QuoteInline - Inline, quoted content.

Section - A section of a document.

SectionType - A category of section.

Sentence - A sentence, usually within a Paragraph.

Strikeout - Content that is marked as struck out.

Strong - Strongly emphasized content.

Subscript - Subscripted content.

Superscript - Superscripted content.

Text - A text node.

ThematicBreak - A thematic break.

Underline - Inline text that is underlined.

Math

Math - An abstract base type for mathematical content.

MathBlock - A block of math, e.g an equation, to be treated as block content.

MathInline - A fragment of math, e.g a variable name, to be treated as inline content.

Code

CodeBlock - A code block.

CodeChunk - An executable code chunk.

CodeExecutable - An abstract base type for executable code nodes.

CodeExpression - An executable code expression.

CodeInline - Inline code.

CodeStatic - An abstract base type for non-executable code nodes.

CompilationMessage - An error, warning or log message generated during compilation.

ExecutionMessage - An error, warning or log message generated during execution.

Data

Array - An array value.

ArrayHint - A concise summary of the values and structure of an Array.

ArrayValidator - A validator specifying constraints on an array node.

Boolean - A value that is either true or false.

BooleanValidator - A validator for boolean values.

ConstantValidator - A validator specifying a constant value that a node must have.

Cord - A CRDT-backed sequence of characters.

Datatable - A table of data.

DatatableColumn - A column of data within a Datatable.

DatatableColumnHint - A concise summary of the properties of a DatatableColumn.

DatatableHint - A concise summary of the structure of a table of data.

Date - A calendar date encoded as a ISO 8601 string.

DateTime - A combination of date and time of day in the form [-]CCYY-MM-DDThh:mm:ss[Z|(+|-)hh:mm].

DateTimeValidator - A validator specifying the constraints on a date-time.

DateValidator - A validator specifying the constraints on a date.

Duration - A value that represents the difference between two timestamps.

DurationValidator - A validator specifying the constraints on a duration.

EnumValidator - A validator for a fixed set of allowed values.

Hint - Union type for hints of the value and/or structure of data.

Integer - An integer value.

IntegerValidator - A validator for integer values.

Null - The null value.

Number - A value that is a number.

NumberValidator - A validator for numeric values.

Object - An object value.

ObjectHint - A concise summary of the structure of an Object.

Primitive - A union type for primitive values.

String - A value comprised of a string of characters.

StringHint - A concise summary of the properties of a String.

StringValidator - A validator for string values.

Time - A point in time recurring on multiple days.

TimeUnit - A unit in which time can be measured.

TimeValidator - A validator specifying the constraints on a time.

Timestamp - A value that represents a point in time.

TimestampValidator - A validator specifying the constraints on a timestamp.

TupleValidator - A validator specifying constraints on an array of heterogeneous items.

Unknown - A placeholder for a value of unknown type.

UnsignedInteger - An integer value that is greater or equal to zero.

Validator - A union type for validators.

Flow

Button - An interactive button.

CallArgument - An argument used when calling a document.

CallBlock - Call another document, optionally with arguments, and include its executed content.

CodeLocation - A location within source code.

CompilationDigest - A digest of an executable node and its dependencies.

Executable - An abstract base type for executable nodes.

ExecutionBounds - A boundary for node execution.

ExecutionDependant - A downstream execution dependant of a node.

ExecutionDependantRelation - A downstream execution relation between nodes.

ExecutionDependency - An upstream execution dependency of a node.

ExecutionDependencyRelation - An upstream execution relation between nodes.

ExecutionMode - The circumstances under which a node should be executed.

ExecutionRequired - A reason why a node does or does not require execution.

ExecutionStatus - The status of a node's most recent execution.

ExecutionTag - An execution-affecting tag on code.

ForBlock - A block that repeats content for each item in an array.

Form - A form for batched updates to document parameters.

FormDeriveAction - An action for applying a derived form value.

Function - A function signature.

IfBlock - A block that conditionally shows and executes alternative content.

IfBlockClause - A clause within an IfBlock node.

IncludeBlock - A block that includes content from an external source.

Parameter - A document parameter.

Variable - A named value.

Walkthrough - An interactive walkthrough.

WalkthroughStep - A step in a Walkthrough.

Style

Page - A page in a document.

Styled - An abstract base type for styled content.

StyledBlock - Styled block content.

StyledInline - Styled inline content.

Edits

Instruction - An abstract base type for document editing instructions.

InstructionBlock - An instruction to edit some block content.

InstructionInline - An instruction to edit some inline content.

InstructionMessage - A message within an Instruction.

MessagePart - A union type for message parts.

PromptBlock - A preview of a rendered prompt at a location in a document.

Suggestion - Abstract base type for nodes that indicate a suggested change to content.

SuggestionBlock - Abstract base type for nodes that indicate a suggested change to block content.

SuggestionInline - Abstract base type for nodes that indicate a suggested change to inline content.

SuggestionStatus - A review status for a suggestion.

SuggestionType - A category of suggested edit.

Other

Brand - A brand used by an organization or person for labeling a product, product group, or similar.

ContactPoint - A contact point, usually within an organization.

Entity - An abstract base type for compound nodes.

Enumeration - Lists or enumerations, for example, a list of cuisines or music genres, etc.

Excerpt - An excerpt from a CreativeWork.

Grant - A grant, typically financial or otherwise quantifiable, of resources.

Island - An island of content in a document.

MessageLevel - A severity level for a message.

MessageRole - A role in a message exchange.

ModelParameters - Model selection and inference parameters for generative AI models.

MonetaryGrant - A monetary grant.

Node - Union type for all types in this schema, including primitives and entities

Organization - An organization such as a school, NGO, corporation, club, etc.

Person - A person (alive, dead, undead, or fictional).

PostalAddress - A physical mailing address.

Product - A product or service.

PropertyValue - A property-value pair.

ProvenanceCategory - A category of content provenance.

ProvenanceCount - The count of the number of characters in a ProvenanceCategory within an entity.

RawBlock - A block of raw content in a specific format.

RelativePosition - The position of one node relative to another.

Role - Represents additional information about a relationship or property.

Thing - The most generic type of item.

ThingVariant - Union type for all types that are descended from Thing