Introduction

JSON-LD, or JSON for Linked Data, is a lightweight data interchange format designed to express linked data in a format that is both human-readable and machine-friendly. It extends JSON by providing a standard way to embed linked data within JSON documents, allowing for a network of standards-based, machine-readable, structured data on the web.

Stencila provides support for JSON-LD for storing and transferring documents in a format with high interoperability.

Usage

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

stencila convert doc.smd doc.jsonld

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

Implementation

Stencila Schema is based on schema.org and has a JSON-LD @context published at https://stencila.org/context.jsonld. When Stencila documents are exported as JSON, this context is applied. As such, the JSON documents that Stencila produces are inherently JSON-LD documents.

For example, an Article is exported like so:

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

However, because the the schema.org is the most widely used vocabulary for JSON-LD, the JsonLdCodec translates terms in the Stencila context, to those in the schema.org context, and uses schema.org as the default vocabulary, with the Stencila context as an extension. This saves consumers of the JSON-LD from having to do this translation themselves.

In addition, when exporting to JSON-LD, the @type and @id keywords are used instead of type and id.

For example, the above article as exported to JSON-LD as follows. Note that because the types Article and Text are part of schema.org, there is no need to prefix their name. However because schema.org does not have a Paragraph type or a content property, it is necessary to prefix those with stencila:.

{
  "@context": {
    "@vocab": "https://schema.org/",
    "stencila": "https://stencila.org/"
  },
  "@type": "Article",
  "stencila:content": [
    {
      "@type": "stencila:Paragraph",
      "stencila:content": [
        {
          "@type": "Text",

Support

Stencila supports these operations for JSON-LD:

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