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 agent definition specifying model, tools, and behavioral configuration.

Article - An article, including news and scholarly articles.

AudioObject - An audio file.

Author - Union type for things that can be an author of a CreativeWork or other type.

AuthorRole - An author and their role.

AuthorRoleAuthor - Union type for things that can be an author in AuthorRole.

AuthorRoleName - A roleName for an AuthorRole.

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 claim represents specific reviewable facts or statements.

ClaimType - The type of a Claim.

Collection - A collection of CreativeWorks or other artifacts.

Comment - A comment on an item, e.g on a Article or SoftwareSourceCode.

CreativeWork - A creative work, including books, movies, photographs, software programs, etc.

CreativeWorkType - The kind of a creative work.

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

Directory - A directory on the file system.

Figure - Encapsulates one or more images, videos, tables, etc, and provides captions and labels for them.

File - A file on the file system.

HorizontalAlignment - The horizontal alignment of content.

ImageObject - An image file.

InstructionType - The type of an instruction describing the operation to be performed.

LabelType - Indicates how a block (usually a CodeChunk) should be automatically labelled.

MediaObject - A media object, such as an image, video, or audio object embedded in a web page or a downloadable dataset.

Periodical - A periodical publication.

Prompt - A prompt for creating or editing document content.

PublicationIssue - A part of a successively published publication such as a periodical or publication volume, often numbered.

PublicationVolume - A part of a successively published publication such as a periodical or multi-volume work.

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 - Computer programming source code. Example: Full (compile ready) solutions, code snippet samples, scripts, templates.

Supplement - A supplementary CreativeWork that supports this work but is not considered part of its main content.

Table - A table.

TableCell - A cell within a Table.

TableCellType - Indicates whether the cell is a header or data.

TableRow - A row within a Table.

TableRowType - Indicates whether the row is in the header, body or footer of the table.

VerticalAlignment - The vertical alignment of content.

VideoObject - A video file.

Workflow - A workflow pipeline definition using Graphviz DOT syntax to orchestrate multi-stage AI tasks.

Prose

Admonition - An admonition within a document.

AdmonitionType - The type of an Admonition.

Annotation - Annotated content.

AppendixBreak - A break in a document indicating the start one or more appendices.

Block - Union type in block content node types.

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

CitationGroup - A group of Citation nodes.

CitationIntent - The type or nature of a citation, both factually and rhetorically.

CitationMode - The 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 - Indicates how a List is ordered.

Mark - Abstract base class for nodes that mark some other inline content in some way (e.g. as being emphasised, or quoted).

Note - Additional content which is not part of the main content of a document.

NoteType - The type of a Note which determines where the note content is displayed within the document.

Paragraph - A paragraph.

QuoteBlock - A section quoted from somewhere else.

QuoteInline - Inline, quoted content.

Section - A section of a document.

SectionType - The type of a 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 - Textual content.

ThematicBreak - A thematic break, such as a scene change in a story, a transition to another topic, or a new document.

Underline - Inline text that is underlined.

Math

Math - Abstract base type for a mathematical variable or equation.

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 - A executable chunk of code.

CodeExecutable - Abstract base type for executable code nodes (e.g. CodeChunk).

CodeExpression - An executable code expression.

CodeInline - Inline code.

CodeStatic - Abstract base type for non-executable code nodes (e.g. CodeBlock).

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

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

Data

Array - A value comprised of other primitive nodes.

ArrayHint - A hint to the content of an Array.

ArrayValidator - A validator specifying constraints on an array node.

Boolean - A value that is either true or false.

BooleanValidator - A schema specifying that a node must be a boolean value.

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

Cord - A value comprised of a sequence of characters.

Datatable - A table of data.

DatatableColumn - A column of data within a Datatable.

DatatableColumnHint - A hint to the type and values in a DatatableColumn.

DatatableHint - A hint to 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 schema specifying that a node must be one of several values.

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

Integer - A value that is a integer.

IntegerValidator - A validator specifying the constraints on an integer node.

Null - The null value.

Number - A value that is a number.

NumberValidator - A validator specifying the constraints on a numeric node.

Object - A value comprised of keyed primitive nodes.

ObjectHint - A hint to the structure of an Object.

Primitive - Union type for all primitives values.

String - A value comprised of a string of characters.

StringHint - A hint to the structure of an String.

StringValidator - A schema specifying constraints on a string node.

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 type to indicate a value or or other type in unknown.

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

Validator - Union type for validators.

Flow

Button - A button.

CallArgument - The value of a Parameter to call a document with.

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

CodeLocation - The location within some source code.

CompilationDigest - A digest of the content, semantics and dependencies of an executable node.

Executable - Abstract base type for executable nodes (e.g. CodeChunk, CodeExpression, Call).

ExecutionBounds - The bounds placed on the execution of a document node.

ExecutionDependant - A downstream execution dependant of a node.

ExecutionDependantRelation - The relation between a node and its execution dependant.

ExecutionDependency - An upstream execution dependency of a node.

ExecutionDependencyRelation - The relation between a node and its execution dependency.

ExecutionMode - Under which circumstances a node should be executed.

ExecutionRequired - Whether, and why, the execution of a node is required or not.

ExecutionStatus - Status of the most recent, including any current, execution of a document node.

ExecutionTag - A tag on code that affects its execution.

ForBlock - Repeat a block content for each item in an array.

Form - A form to batch updates in document parameters.

FormDeriveAction - Indicates the action (create, update or delete) to derive for a Form.

Function - A function with a name, which might take Parameters and return a value of a certain type.

IfBlock - Show and execute alternative content conditional upon an executed expression.

IfBlockClause - A clause within an IfBlock node.

IncludeBlock - Include block content from an external source (e.g. file, URL).

Parameter - A parameter of a document.

Variable - A variable representing a name / value pair.

Walkthrough - An interactive walkthrough made up of several, successively revealed steps.

WalkthroughStep - A step in a walkthrough.

Style

Page - A separate page in a document

Styled - An abstract base class for a document node that has styling applied to it and/or its content.

StyledBlock - Styled block content.

StyledInline - Styled inline content.

Edits

Instruction - Abstract base type for a document editing instruction.

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 a part of a message.

PromptBlock - A preview of how a prompt will be rendered at a location in the 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 - The status of an instruction.

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 - Abstract base type for compound (ie. non-atomic) 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 - The severity level of a message.

MessageRole - The role of a message.

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 - Any offered product or service. For example, a pair of shoes; a haircut; or an episode of a TV show streamed online.

PropertyValue - A property-value pair.

ProvenanceCategory - A description of the provenance of content in terms of human/machine involvement.

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

RawBlock - Document content in a specific format

RelativePosition - The relative position of a node 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