Introduction

JSON5 is an extension of the JSON (JavaScript Object Notation) format that incorporates additional features for enhanced readability and flexibility. It maintains compatibility with standard JSON while introducing human-friendly syntax elements such as comments, trailing commas, and relaxed quoting rules.

Stencila provides support for JSON5 as a more human-readable, while still lossless, alternative to JSON for storing documents. JSON5 is also used internally within Stencila as a more human-friendly, JavaScript-like way to represent nodes within documents in formats such as Markdown.

Usage

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

stencila convert doc.smd doc.json5

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

Implementation

Stencila support lossless, bi-directional conversion between Stencila documents and JSON5. The codec-json5-trait Rust crate implements from_json5 and to_json5 methods (and variants of those) for all node types in Stencila Schema, powered by json5 and json5format.

Encodings

By default, the encoded JSON5 is indented but the --compact option is supported which produces un-indented, single line JSON5.

Support

Stencila supports these operations for JSON5:

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-json5 for more details.