Introduction

JavaScript Object Notation (JSON) is a lightweight data interchange format widely used for structured data storage and transmission. JSON's simplicity, flexibility, and compatibility with various programming languages make it a popular choice for APIs, configuration files, and data exchange between applications. Stencila uses JSON as the default storage format for documents.

Usage

Use the .json file extension, or the --to json or --from json options, when converting to/from JSON e.g.

stencila convert doc.smd doc.json

By default, the encoded JSON is indented. The --compact option can be used to produce un-indented, single line JSON.

When the --standalone option is used (the default for encoding to files), two properties are added to the JSON encoding of root nodes to improve interoperability:

a $schema property which links to the JSON Schema for the node type
a @context property which links to the JSON-LD context for the Stencila Schema

For example,

{
  "$schema": "https://stencila.org/Article.schema.json",
  "@context": "https://stencila.org/context.jsonld",
  "type": "Article",
  ...

Specification

See the ECMA-404 The JSON Data Interchange Standard.

Implementation

Stencila support lossless, bi-directional conversion between Stencila documents and JSON powered by serde_json.

Support

Stencila supports these operations for JSON:

decoding from a file
decoding from a string
encoding to a file
encoding to a string

Support and degree of loss by node type:

Node type	Encoding	Decoding
Works
Article	🟢 No loss	🟢 No loss
AudioObject	🟢 No loss	🟢 No loss
AuthorRole	🟢 No loss	🟢 No loss
Chat	🟢 No loss	🟢 No loss
ChatMessage	🟢 No loss	🟢 No loss
ChatMessageGroup	🟢 No loss	🟢 No loss
Claim	🟢 No loss	🟢 No loss
Collection	🟢 No loss	🟢 No loss
Comment	🟢 No loss	🟢 No loss
CreativeWork	🟢 No loss	🟢 No loss
Directory	🟢 No loss	🟢 No loss
Figure	🟢 No loss	🟢 No loss
File	🟢 No loss	🟢 No loss
ImageObject	🟢 No loss	🟢 No loss
MediaObject	🟢 No loss	🟢 No loss
Periodical	🟢 No loss	🟢 No loss
Prompt	🟢 No loss	🟢 No loss
PublicationIssue	🟢 No loss	🟢 No loss
PublicationVolume	🟢 No loss	🟢 No loss
Review	🟢 No loss	🟢 No loss
SoftwareApplication	🟢 No loss	🟢 No loss
SoftwareSourceCode	🟢 No loss	🟢 No loss
Table	🟢 No loss	🟢 No loss
TableCell	🟢 No loss	🟢 No loss
TableRow	🟢 No loss	🟢 No loss
VideoObject	🟢 No loss	🟢 No loss
Prose
Admonition	🟢 No loss	🟢 No loss
Annotation	🟢 No loss	🟢 No loss
Cite	🟢 No loss	🟢 No loss
CiteGroup	🟢 No loss	🟢 No loss
DefinedTerm	🟢 No loss	🟢 No loss
Emphasis	🟢 No loss	🟢 No loss
Heading	🟢 No loss	🟢 No loss
Link	🟢 No loss	🟢 No loss
List	🟢 No loss	🟢 No loss
ListItem	🟢 No loss	🟢 No loss
Note	🟢 No loss	🟢 No loss
Paragraph	🟢 No loss	🟢 No loss
QuoteBlock	🟢 No loss	🟢 No loss
QuoteInline	🟢 No loss	🟢 No loss
Section	🟢 No loss	🟢 No loss
Strikeout	🟢 No loss	🟢 No loss
Strong	🟢 No loss	🟢 No loss
Subscript	🟢 No loss	🟢 No loss
Superscript	🟢 No loss	🟢 No loss
Text	🟢 No loss	🟢 No loss
ThematicBreak	🟢 No loss	🟢 No loss
Underline	🟢 No loss	🟢 No loss
Math
MathBlock	🟢 No loss	🟢 No loss
MathInline	🟢 No loss	🟢 No loss
Code
CodeBlock	🟢 No loss	🟢 No loss
CodeChunk	🟢 No loss	🟢 No loss
CodeExpression	🟢 No loss	🟢 No loss
CodeInline	🟢 No loss	🟢 No loss
CompilationMessage	🟢 No loss	🟢 No loss
ExecutionMessage	🟢 No loss	🟢 No loss
Data
Array	🟢 No loss	🟢 No loss
ArrayHint	🟢 No loss	🟢 No loss
ArrayValidator	🟢 No loss	🟢 No loss
Boolean	🟢 No loss	🟢 No loss
BooleanValidator	🟢 No loss	🟢 No loss
ConstantValidator	🟢 No loss	🟢 No loss
Cord	🟢 No loss	🟢 No loss
Datatable	🟢 No loss	🟢 No loss
DatatableColumn	🟢 No loss	🟢 No loss
DatatableColumnHint	🟢 No loss	🟢 No loss
DatatableHint	🟢 No loss	🟢 No loss
Date	🟢 No loss	🟢 No loss
DateTime	🟢 No loss	🟢 No loss
DateTimeValidator	🟢 No loss	🟢 No loss
DateValidator	🟢 No loss	🟢 No loss
Duration	🟢 No loss	🟢 No loss
DurationValidator	🟢 No loss	🟢 No loss
EnumValidator	🟢 No loss	🟢 No loss
Integer	🟢 No loss	🟢 No loss
IntegerValidator	🟢 No loss	🟢 No loss
Null	🟢 No loss	🟢 No loss
Number	🟢 No loss	🟢 No loss
NumberValidator	🟢 No loss	🟢 No loss
Object	🟢 No loss	🟢 No loss
ObjectHint	🟢 No loss	🟢 No loss
String	🟢 No loss	🟢 No loss
StringHint	🟢 No loss	🟢 No loss
StringValidator	🟢 No loss	🟢 No loss
Time	🟢 No loss	🟢 No loss
TimeValidator	🟢 No loss	🟢 No loss
Timestamp	🟢 No loss	🟢 No loss
TimestampValidator	🟢 No loss	🟢 No loss
TupleValidator	🟢 No loss	🟢 No loss
Unknown	🟢 No loss	🟢 No loss
UnsignedInteger	🟢 No loss	🟢 No loss
Flow
Button	🟢 No loss	🟢 No loss
CallArgument	🟢 No loss	🟢 No loss
CallBlock	🟢 No loss	🟢 No loss
CodeLocation	🟢 No loss	🟢 No loss
CompilationDigest	🟢 No loss	🟢 No loss
ExecutionDependant	🟢 No loss	🟢 No loss
ExecutionDependency	🟢 No loss	🟢 No loss
ExecutionTag	🟢 No loss	🟢 No loss
ForBlock	🟢 No loss	🟢 No loss
Form	🟢 No loss	🟢 No loss
Function	🟢 No loss	🟢 No loss
IfBlock	🟢 No loss	🟢 No loss
IfBlockClause	🟢 No loss	🟢 No loss
IncludeBlock	🟢 No loss	🟢 No loss
Parameter	🟢 No loss	🟢 No loss
Variable	🟢 No loss	🟢 No loss
Walkthrough	🟢 No loss	🟢 No loss
WalkthroughStep	🟢 No loss	🟢 No loss
Style
StyledBlock	🟢 No loss	🟢 No loss
StyledInline	🟢 No loss	🟢 No loss
Edits
InstructionBlock	🟢 No loss	🟢 No loss
InstructionInline	🟢 No loss	🟢 No loss
InstructionMessage	🟢 No loss	🟢 No loss
PromptBlock	🟢 No loss	🟢 No loss
SuggestionBlock	🟢 No loss	🟢 No loss
SuggestionInline	🟢 No loss	🟢 No loss
Config
Config	🟢 No loss	🟢 No loss
Other
Brand	🟢 No loss	🟢 No loss
ContactPoint	🟢 No loss	🟢 No loss
Enumeration	🟢 No loss	🟢 No loss
Grant	🟢 No loss	🟢 No loss
ModelParameters	🟢 No loss	🟢 No loss
MonetaryGrant	🟢 No loss	🟢 No loss
Organization	🟢 No loss	🟢 No loss
Person	🟢 No loss	🟢 No loss
PostalAddress	🟢 No loss	🟢 No loss
Product	🟢 No loss	🟢 No loss
PropertyValue	🟢 No loss	🟢 No loss
ProvenanceCount	🟢 No loss	🟢 No loss
RawBlock	🟢 No loss	🟢 No loss
Thing	🟢 No loss	🟢 No loss

See the Rust crate codec-json for more details.