TOC Menu Button

science.ai hypermedia API

science.ai api logo (hypercube)

Concepts

JSON-LD

The science.ai API uses JSON-LD to organize and connect data. Although no specific knowledge regarding JSON-LD is necessary to use the API, interested readers may consult the JSON-LD specification or the W3C RDF primer.

Data are expressed using schema.org and a schema.org extension that describe with greater precision the production process, content, and preservation of scholarly articles (and similar artefacts).

The science.ai JSON-LD context is available at https://science.ai.

Accessing the science.ai JSON-LD context requires an Accept: application/ld+json header.

Actions

Schema.org Actions are the only way to create and update data on science.ai.

Readers not familiar with schema.org actions can refer to schema.org's introductory blog post for a quick overview.

Most common actions exposed by the science.ai API
object potentialAction
science.ai
Service
Organization
Periodical
Graph
Offer
CreativeWork
MediaObject (Encoding)
Review
Person
Question
Action

The action reference at the end of this document provides detailed examples of all the actions used by the science.ai API.

Events

Events are modeled after the schema.org Event type.

Graph

The science.ai API allows one to build and access a Graph of content. A graph typically contains creative works (e.g. dataset, code, article, reviews), persons, and organizations associated with these works (authors, reviewers, institutions), and relationships between the different nodes of a graph (e.g. a work may "depend" on another work). Furthermore, nodes of a graph can be actionable and expose (in a machine readable way) potential actions that can be performed on that node (e.g. converting an article written with Microsoft Word to HTML).

Graphs are organized according to a simplified FRBR model in which a distinction is made between creative works (e.g. an article) and their "encodings" (e.g. an HTML representation of the article). (This is essentially a resource/representation distinction.)

The primary entity described in a Graph (typically a ScholarlyArticle) should be indicated with the mainEntity property of the Graph.

Types of Creative Works (CreativeWork) and corresponding Encodings (MediaObject) commonly associated with a ScholarlyArticle.
Creative Work Encoding
ScholarlyArticle DocumentObject
Image ImageObject
Audio AudioObject
Video VideoObject
Dataset DataDownload
Table TableObject
SoftwareSourceCode SoftwareSourceCodeObject
Formula FormulaObject
Example of a Graph containing a ScholarlyArticle (indicated as the mainEntity of the Graph).

{
  "@context": "https://science.ai",
  "@id": "scienceai:graphId",
  "@type": "Graph",
  "mainEntity": "scienceai:articleId",
  "@graph": [
    {
      "@id": "scienceai:articleId",
      "@type": "ScholarlyArticle",
      "author": {
        "@id": "user:peter",
        "@type": "Person",
        "name": "Dr. Peter Jon Smith"
      },
      "hasPart": [
        {
          "@id": "scienceai:datasetId",
          "@type": "Dataset",
          "author": {
            "@id": "user:peter",
            "@type": "Person",
            "name": "Dr. Peter Jon Smith"
          },
          "distribution": {
            "@type": "DataDownload",
            "contentUrl": "http://example.com/data.xlsx",
            "contentSize": 1024
          }
        },
        {
          "@id": "scienceai:imageId",
          "@type": "Image",
          "author": {
            "@id": "user:peter",
            "@type": "Person",
            "name": "Dr. Peter Jon Smith"
          },
          "isBasedOn": "scienceai:datasetId",
          "encoding": {
            "@type": "ImageObject",
            "fileFormat": "image/png",
            "contentUrl": "http://example.com/image.png",
            "potentialAction": {
              "@type": "ImageProcessingAction",
              "target": {
                "@type": "EntryPoint",
                "httpMethod": "POST",
                "urlTemplate": "http://example.com/{encodingId}"
              }
            }
          }
        }
      ]
    }
  ]
}
            

Normalization and framing

Graphs represented as trees (as in the example above) can be highly denormalized (for instance, in the example above, the author node is fully duplicated 3 times).

Working with denormalized graphs can be difficult (and inefficient) as there are risks of creating different versions of nodes that should be identical (especially when a graph is being edited collaboratively).

To avoid the data-integrity problems that come with denormalization, science.ai stores a normalized version of graphs by leveraging the JSON-LD 1.0 Processing Algorithms and API specification to flatten JSON-LD documents.


{
  "@context": "https://science.ai",
  "@id": "scienceai:graphId",
  "@type": "Graph",
  "mainEntity": "scienceai:articleId",
  "@graph": [
    {
      "@id": "scienceai:articleId",
      "@type": "ScholarlyArticle",
      "author": [
        "user:peter"
      ],
      "hasPart": [
        "scienceai:datasetId",
        "scienceai:imageId"
      ]
    },
    {
      "@id": "user:peter",
      "@type": "Person",
      "name": "Dr. Peter Jon Smith"
    },
    {
      "@id": "scienceai:datasetId",
      "@type": "Dataset",
      "author": [
        "user:peter"
      ],
      "distribution": [
        "_:30269b53-6a9d-46e3-936f-01eb0bb18ec8"
      ]
    },
    {
      "@id": "scienceai:imageId",
      "@type": "Image",
      "author": [
        "user:peter"
      ],
      "encoding": [
        "_:e145ba2e-efbe-459d-a263-adfdcd010c4a"
      ],
      "isBasedOn": "scienceai:datasetId"
    },
    {
      "@id": "_:30269b53-6a9d-46e3-936f-01eb0bb18ec8",
      "@type": "DataDownload",
      "contentSize": 1024,
      "contentUrl": "http://example.com/data.xlsx"
    },
    {
      "@id": "_:e145ba2e-efbe-459d-a263-adfdcd010c4a",
      "@type": "ImageObject",
      "contentUrl": "http://example.com/image.png",
      "fileFormat": "image/png",
      "potentialAction": [
        "_:b9bc9eb7-37d8-4667-8a32-0a97b61f3aa3"
      ]
    },
    {
      "@id": "_:b9bc9eb7-37d8-4667-8a32-0a97b61f3aa3",
      "@type": "ImageProcessingAction",
      "target": {
        "@id": "_:e60fee88-5062-459a-98c2-ddd699a37c4c"
      }
    },
    {
      "@id": "_:e60fee88-5062-459a-98c2-ddd699a37c4c",
      "@type": "EntryPoint",
      "httpMethod": "POST",
      "urlTemplate": "http://example.com/{encodingId}"
    }
  ]
}
            
Flattened form of the previous example.

When trees are required, JSON-LD framing provides a convenient way to recreate trees out of a flattened JSON-LD document. When retrieving graphs, the science.ai API provides a way to return a framed version of a graph.


{
  "@context": "https://science.ai",
  "@type": "ScholarlyArticle",
  "@embed": "@always"
}
            
A JSON-LD frame allowing to get a tree for the ScholarlyArticle of a flattened JSON-LD document.

Multiversion concurrency control

To allow safe concurrent collaborative editing, science.ai relies on MVCC.

Each revision of a document comes with a specific revision value. To update or delete a document, the latest revision value must be specified. This mechanism ensures that, if another user changed a document while you are operating on it, science.ai will not accept your subsequent update since you are likely to overwrite data you did not know existed. When the change is accepted, a new revision number will be generated.


{
  "_id": "54peter\u00014sid\u0001\u0001",
  "_rev": "1-6080aefe797f5068d36518c954e813a7",
  "@id": "user:peter",
  "@type": "Person",
  "name": "Dr. Peter Jon Smith"
}
            
A node of a graph containing a revision number (_rev).

In addition to the _rev property, an additional _id property may be present in the response body returned by science.ai. This property (_id) is used internally by science.ai to ensure efficient indexing of all the stored documents (both on the server and in the browser) and is subject to occasional change. API consumers should never rely on this value, and instead, use the @id as the canonical identifier of the document.

When updating a document, the revision token can be specified either as:

  • a _rev property directly in the document
  • using the If-Match HTTP header.

Versioning

Graphs can be versioned. To version a Graph, a snapshot is taken. Snapshots are entirely frozen (immutable) and are characterized by a version and a digital signature (the NaSH) that is invariant to the different forms of serialization of the graph.


{
  "@context": "https://science.ai",
  "@id": "scienceai:graphId?version=1.0.0",
  "@type": "Graph",
  "version": "1.0.0",
  "dateCreated": "2016-06-29T19:49:22.349Z",
  "contentChecksum": {
    "@type": "Checksum",
    "checksumAlgorithm": "nash",
    "checksumValue": "nashxAqaxNgOZS4mebiZJhOlR372Iy7C3w6a1Igc45//wlo="
  },
  "mainEntity": "scienceai:articleId",
  "@graph": [
    {
      "@id": "scienceai:articleId",
      "@type": "ScholarlyArticle",
      "author": [
        "user:peter"
      ],
      "hasPart": [
        "scienceai:datasetId",
        "scienceai:imageId"
      ]
    },
    {
      "@id": "user:peter",
      "@type": "Person",
      "name": "Dr. Peter Jon Smith"
    },
    {
      "@id": "scienceai:datasetId",
      "@type": "Dataset",
      "author": [
        "user:peter"
      ],
      "distribution": [
        "_:30269b53-6a9d-46e3-936f-01eb0bb18ec8"
      ]
    },
    {
      "@id": "scienceai:imageId",
      "@type": "Image",
      "author": [
        "user:peter"
      ],
      "encoding": [
        "_:e145ba2e-efbe-459d-a263-adfdcd010c4a"
      ],
      "isBasedOn": "scienceai:datasetId"
    },
    {
      "@id": "_:30269b53-6a9d-46e3-936f-01eb0bb18ec8",
      "@type": "DataDownload",
      "contentSize": 1024,
      "contentUrl": "http://example.com/data.xlsx"
    },
    {
      "@id": "_:e145ba2e-efbe-459d-a263-adfdcd010c4a",
      "@type": "ImageObject",
      "contentUrl": "http://example.com/image.png",
      "fileFormat": "image/png",
      "potentialAction": [
        "_:b9bc9eb7-37d8-4667-8a32-0a97b61f3aa3"
      ]
    },
    {
      "@id": "_:b9bc9eb7-37d8-4667-8a32-0a97b61f3aa3",
      "@type": "ImageProcessingAction",
      "target": {
        "@id": "_:e60fee88-5062-459a-98c2-ddd699a37c4c"
      }
    },
    {
      "@id": "_:e60fee88-5062-459a-98c2-ddd699a37c4c",
      "@type": "EntryPoint",
      "httpMethod": "POST",
      "urlTemplate": "http://example.com/{encodingId}"
    }
  ]
}
            
Example of a snapshot of Graph.

The @id of a snapshot is made of the @id of the Graph followed by a version query string parameter (e.g. scienceai:graphId?version=1.0.0)

Role

A (Role) represents additional information about a relationship or property.

For example let's consider the memberOf property which specifies an Organization to which a person belongs:


{
  "@context": "https://science.ai",
  "@id": "user:peter",
  "@type": "Person",
  "name": "Dr. Peter Jon Smith",
  "memberOf": {
    "@id": "https://science.ai",
    "@type": "Organization"
  }
}
            
Dr. Peter Jon Smith is a member of science.ai

A role can be used to specify additional information about that property, for instance to indicate the date when Peter became a member of science.ai.


{
  "@context": "https://science.ai",
  "@id": "user:peter",
  "@type": "Person",
  "name": "Dr. Peter Jon Smith",
  "memberOf": {
    "@type": "OrganizationRole",
    "memberOf": {
      "@id": "https://science.ai",
      "@type": "Organization"
    },
    "startDate": "2020-01-01T21:04:20.262Z"
  }
}
            
Example of using a Role (here OrganizationRole) to provide additional information about the memberOf property (here the startDate of the membership).

Readers not familiar with the semantics of schema.org Roles can consult the introductory blog post.

Persona

Roles can also be used to express different persona of a Person.

For instance Roles can be used to specify that an agent tagged an object as a given persona (for instance as an "editor"):


{
  "@context": "https://science.ai",
  "@id": "scienceai:tagActionId",
  "@type": "TagAction",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": {
      "@id": "user:jon",
      "@type": "Person"
    }
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "result": {
    "@type": "Tag",
    "name": "Linked data"
  }
}
            
Example of using Roles to specify a persona. Here the agent tagged a Graph as an editor (roleName).

science.ai API supports the following values for the roleName property:

  • user
  • author
  • editor
  • producer
  • reviewer

Additional role names are available for values of the participant property of Actions (Action).

  • subscriber
  • assigner

Selectors

Roles are also used to define selectors. Selectors (Selector) specify specific parts (e.g. a text selection, part of an image, a time point in a video) of a resource.


{
  "@type": "Review",
  "itemReviewed": {
    "@type": "TargetRole",
    "itemReviewed": "scienceai:graphId",
    "hasSelector": {
      "@type": "WebVerseSelector",
      "nodeId": "scienceai:encodingId",
      "webVerseKey": "HcbUid",
      "webVerseHash": "3433ded23256",
      "webVerseId": "id",
      "startOffset": 0,
      "endOffset": 10
    }
  }
}
            
Example of using a TargetRole to specify which part of a CreativeWork (indicated by the hasSelector property) a review applies to (itemReviewed property).

Annotations

Annotation abilities (e.g. linking, tagging, commenting) are provided with schema.org Actions (Action) and often leverage the TargetRole class (see selectors section) to provide more context about the annotation targets.

A resource can be marked as annotable (adding hypermedia controls) by leveraging the potentialAction property available on any object.


{
  "@context": "https://science.ai",
  "@id": "scienceai:graphIdId?version=1.0.0",
  "@type": "Graph",
  "version": "1.0.0",
  "potentialAction": {
    "@type": "CommentAction",
    "target": {
      "@type": "EntryPoint",
      "httpMethod": "POST",
      "urlTemplate": "http://example.com/comment"
    }
  }
}
            
Adding hypermedia controls to make a Graph open to comments.

Audience

The science.ai API supports the following types (audienceType) of Audience:

  • public
  • user
  • author
  • editor
  • producer
  • reviewer

Access control and permissions

Access control is defined using:

  • the hasDigitalDocumentPermission property of a Periodical or a Graph

    
    {
      "@context": "https://science.ai",
      "@type": "Periodical",
      "hasDigitalDocumentPermission": {
        "@type": "DigitalDocumentPermission",
        "grantee": {
          "@type": "Audience",
          "audienceType": "public"
        },
        "permissionType": "ReadPermission"
      }
    }
                    
    Example specifying that a journal (Periodical) can be viewed publicly
  • the expectsAcceptanceOf property to express the required acceptance of an Offer (typically monetary)
    
    {
      "@context": "https://science.ai",
      "@id": "scienceai:scholarlyArticleId",
      "@type": "ScholarlyArticle",
      "potentialAction": {
        "@type": "ConsumeAction",
        "expectsAcceptanceOf": {
          "@type": "Offer",
          "potentialAction": {
            "@type": "BuyAction",
            "price": "25USD"
          }
        }
      }
    }
                    
    Example of a paywall for a ScholarlyArticle.
Permissions supported by the science.ai API.
DigitalDocumentPermissionType audienceType (permissionScope)
ReadPermission -
WritePermission -
AdminPermission -
ReadReviewPermission [ "user", "author", "editor", "reviewer", "producer" ]
WriteReviewPermission [ "user", "author", "editor", "reviewer", "producer" ]
ReadCommentPermission [ "user", "author", "editor", "reviewer", "producer" ]
WriteCommentPermission [ "user", "author", "editor", "reviewer", "producer" ]
AssessPermission -
CommunicatePermission [ "user", "author", "editor", "reviewer", "producer" ]
InvitePermission [ "user", "author", "editor", "reviewer", "producer" ]
ViewIdentityPermission [ "user", "author", "editor", "reviewer", "producer" ]
AssignPermission [ "user", "author", "editor", "reviewer", "producer" ]
CreateReleasePermission -
CreateOfferPermission -

Journal and editorial workflow management

A journal (Periodical) is the starting point of the editorial workflow management and peer review process of a scholarly article (or more generally a Graph). Editorial workflow management is modeled with the hasDigitalDocumentPermission and potentialAction properties of a Graph.

Graphs produced following an editorial workflow refer to it through the publishingPrinciples property of the Graph.

A given Journal (Periodical) can have different editorial workflows. The possible editorial workflows of a journal are exposed as potential actions (potentialAction) of the journal ( CreateGraphAction ) and usually involve CreateWorkflowStageAction to specify the various stages (triage, review, production, ...) of the editorial workflow.

Members of the journal part of the journal editorial office (and therefore acting as an entry point for the journal new submission) are indicated with the roleContactPoint property of the ContributorRole class.

Example of a journal (Periodical) and an associated editorial workflow (CreateGraphAction) involving 2 stages (CreateWorkflowStageAction) specified as potential action (potentialAction).

{
  "@context": "https://science.ai",
  "@id": "scienceai:journalId",
  "@type": "Periodical",
  "url": "https://journal.science.ai",
  "name": "journal name",
  "hasDigitalDocumentPermission": {
    "@type": "DigitalDocumentPermission",
    "grantee": {
      "@type": "Audience",
      "audienceType": "public"
    }
  },
  "editor": [
    {
      "@type": "Role",
      "roleName": "editor",
      "name": "Editor-in-Chief",
      "editor": "user:elsa",
      "startDate": "2015-02-15T21:04:20.262Z"
    },
    {
      "@type": "ContributorRole",
      "roleName": "editor",
      "name": "editorial office",
      "editor": "user:tim",
      "startDate": "2015-02-15T21:04:20.262Z",
      "roleContactPoint": {
        "@type": "ContactPoint",
        "email": "mailto:tim@example.com"
      }
    }
  ],
  "potentialAction": {
    "@type": "CreateGraphAction",
    "actionStatus": "PotentialActionStatus",
    "name": "Example workflow",
    "object": "scienceai:periodicalId",
    "result": {
      "@type": "Graph",
      "hasDigitalDocumentPermission": {
        "@type": "ViewIdentityPermission",
        "grantee": [
          {
            "@type": "Audience",
            "audienceType": "author"
          },
          {
            "@type": "Audience",
            "audienceType": "editor"
          },
          {
            "@type": "Audience",
            "audienceType": "producer"
          },
          {
            "@type": "Audience",
            "audienceType": "reviewer"
          }
        ],

        "permissionScope": [
          {
            "@type": "Audience",
            "audienceType": "editor"
          },
          {
            "@type": "Audience",
            "audienceType": "author"
          },
          {
            "@type": "Audience",
            "audienceType": "producer"
          },
          {
            "@type": "Audience",
            "audienceType": "reviewer"
          }
        ]

      },

      "potentialAction": {
        "@type": "CreateWorkflowStageAction",
        "name": "Submission stage",
        "result": {
          "@type": "CreateReleaseAction",
          "agent": { "@type": "Role", "roleName": "author" },
          "name": "Upload files",
          "expectedDuration": "P1D",
          "result": {
            "@type": "Graph",
            "potentialAction": {
              "@type": "AssessAction",
              "expectedDuration": "P2D",
              "agent": { "@type": "Role", "roleName": "editor" },
              "name": "Assess manuscript",
              "result": [
                {
                  "@type": "RejectAction",
                  "agent": { "@type": "Role", "roleName": "editor" }
                },

                {
                  "@type": "CreateWorkflowStageAction",
                  "name": "Production stage",
                  "alternateName": "Accept",
                  "result": [
                    {
                      "@type": "AllocateAction",
                      "expectedDuration": "P2D",
                      "agent": { "@type": "Role", "roleName": "producer" },
                      "name": "Allocate a URL"
                    },
                    {
                      "@type": "CreateReleaseAction",
                      "expectedDuration": "P7D",
                      "agent": { "@type": "Role", "roleName": "producer" },
                      "name": "Publish",
                      "result": {
                        "@type": "Graph",
                        "hasDigitalDocumentPermission": {
                          "@type": "DigitalDocumentPermission",
                          "grantee": {
                            "@type": "Audience",
                            "audienceType": "public"
                          }
                        }
                      }
                    }
                  ]
                }
              ]
            }
          }
        }
      }
    }
  }
}
            

Services

Available services (Service):
Entry point (@id) Description
service:webify Convert encodings (MediaObject) to web friendly formats.

In order to leverage those services, a CreateGraphAction with an object pointing to the service @id must first be issued.

Emails and Notifications

science.ai takes care of sending emails and notifications (messages) automatically when communicate actions (CommunicateAction) are issued.

The instrument property of the CommunicateAction is used to specify the communication medium (EmailMessage or Message)

For convenience, communicate action (CommunicateAction) can be attached to other actions using the potentialAction property e.g.


{
  "@context": "https://science.ai",
  "@type": "InviteAction",
  "agent": "user:peter",
  "recipient": "user:elsa",
  "potentialAction": {
    "@type": "CommunicateAction",
    "instrument": {
      "@type": "EmailMessage",
      "description": "Email subject",
      "text": "Email body"
    }
  }
}
            
Example specifying that a custom email should be sent when an InviteAction is issued.

When multiple CommunicateAction are possible based on different stage (ActionStatusType) of an action (the object of the CommunicateAction), the object of the CommunicateAction must indicate the relevant ActionStatusType through its actionStatus property.


{
  "@context": "https://science.ai",
  "@id": "scienceai:actionId",
  "@type": "RegisterAction",
  "actionStatus": "ActiveActionStatus",
  "agent": "user:peter",
  "potentialAction": [
    {
      "@type": "CommunicateAction",
      "object": {
        "actionStatus": "ActiveActionStatus"
      },
      "instrument": {
        "@type": "EmailMessage",
        "description": "Registration",
        "text": "Click on the following link to validate your registration"
      }
    },
    {
      "@type": "CommunicateAction",
      "object": {
        "actionStatus": "CompletedActionStatus"
      },
      "instrument": {
        "@type": "EmailMessage",
        "description": "Welcome to science.ai",
        "text": "Welcome!"
      }
    }
  ]
}
            
Example specifying two different email messages (EmailMessage) based on the actionStatus property of the object of the CommunicateAction.

The actionStatus of the CommunicateAction will only be set to CompletedActionStatus once the email has been successfully sent by science.ai.

Authentication

Authentication to the API is performed via HTTP Basic Auth over HTTPS using your username and password (or API key and API secret).

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Errors

science.ai uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g. a required parameter was omitted, authentication is needed, etc.), and codes in the 5xx range indicate an error with science.ai servers.

For long running operations (when a 202 HTTP status code is being returned), errors are provided through the error property of an action and indicated as an actionStatus property set to FailedActionStatus.


{
  "@context": "https://science.ai",
  "@type": "Action",
  "actionStatus": "FailedActionStatus",
  "error": {
    "@type": "Error",
    "description": "something went wrong"
  }
}
          
Example of a failed action.

CRUD Routes

GET /:@id

Get a document by its @id.

Requesting a CreativeWork with an Accept header of text/html will return an HTML/RDFa representation of the work.

For convenience, the :@id can be specified as a CURIE so for instance a document with "@id": "scienceai:uuid" can be retrieved with:

  • GET /uuid (proper URL as the scienceai: prefix resolves to /)
  • GET /scienceai:uuid (CURIE)

The following query string parameters are supported:

version
The version query string parameter can be used to specified a version of the resource. If the resource is not a Graph, the version is used to specify the version of the snapshot of a Graph from which the resource should be retrieved.
bare
Set to true, in the context of a request that accepts HTML, will cause the content to provide only the bare HTML content of the resource without the boilerplate that makes it a complete HTML document or the embedded JSON-LD.
unframed
Set to true, in the context of a request that accepts HTML, will cause the embedded JSON-LD graph to not be framed.
amp
Set to true, it will produce an HTML body that works with AMP (Accelerated Mobile Pages). This also respects the bare parameter, in which case it will only return the AMP body. Note however that AMP places very specific requirements on the HTML scaffolding and header, so be careful when using bare with amp. It is strongly recommended to use the canonical parameter at the same time as this one.
canonical
This parameter is only meaningful in conjunction with amp. When a regular Web page wishes to inform spiders that it has an AMP alternative, it does so by using the following type of element: <link rel="amphtml" href="https://url/of/amp/version">. The AMP variant is then in turn expected to link back in the same manner, with: <link rel="canonical" href="https://url/of/normal/version">. This parameter allows you to set that back link in the AMP version. Note that since the link element is added in the head, using this with bare will have no effect
frame
A JSON-LD frame (specified as a JSON string) to be used to return a framed version of the document. As a shortcut, passing the value ?frame=true has the same effect as the following frame:

{
  "@context": "https://science.ai",
  "@id": "scienceai:documentId",
  "@embed": "@always"
}
                
Default frame used by science.ai when the frame query string parameter is set to true.

GET /user/:username

Get a user profile (Person) by their username.

GET /periodical/:periodicalId

Get a journal (Periodical) by its @id. Note that the hostname of the URL of the journal can be used instead of the periodical @id.

The :periodicalId must be specified as a CURIE including the prefix (e.g. scienceai:uuid).

GET /organization

Returns the list of Organizations that the currently logged-in user belongs to (and therefore can administrate). Note that the list is wrapped in an ItemList.

GET /organization/:organizationId

Returns the given Organization matching the ID.

GET /graph/:graphId

Get a graph (Graph) or a snapshot (version) of a graph by its @id. Note that the slug or NaSH of a graph can be passed instead of the graph (or snapshot) @id.

Unless a NaSH or a slug is used for the :graphId part of the URL, the :graphId must be specified as a CURIE including the prefix (e.g. scienceai:uuid).

The following query string parameters are supported:

version
The version query string paramter can be used to specified a version of the Graph
frame

A JSON-LD frame (specified as a JSON string) to be used to return a framed version of the document. As a shortcut, passing the value ?frame=true has the same effect as the following frame:


                    {
                    "@context": "https://science.ai",
                    "@id": "scienceai:mainEntityId",
                    "@embed": "@always"
                    }
                
Default frame used by science.ai when the frame query string parameter is set to true

DELETE /graph/:graphId

Delete a Graph (only so long as the Graph hasn't been publicly published).

The :graphId must be specified as a CURIE including the prefix (e.g. scienceai:uuid).

GET /action/:actionId

Get an action by @id

The :actionId must be specified as a CURIE including the prefix (e.g. scienceai:uuid).

POST /action

Create a new action (see examples of HTTP request and bodies in the action reference section). The HTTP response body will contain the @id of the newly created action.

The following query string parameters are supported:

mainEntity
Setting mainEntity to true for a CreateGraphAction with a result with a @graph property containing only 1 node, will also set that node as the mainEntity of the Graph.

POST /action/:actionId

Update an action. Note that, in general, POSTing an action will have side effects.

The :actionId must be specified as a CURIE including the prefix (e.g. scienceai:uuid).

The following query string parameters are supported:

actionStatus
If no request body is preset, an existing action (with @id corresponding to :actionid) will be fetched and it's actionStatus overwritten by the value of the actionStatus query string parameter
mainEntity
Setting mainEntity to true for a CreateGraphAction with a result with a @graph property containing only 1 node, will also set that node as the mainEntity of the Graph.

PUT /action/:actionId

Update an action (no side effects) (for instance to setup its agent or update its actionStatus).

The :actionId must be specified as a CURIE including the prefix (e.g. scienceai:uuid).

DELETE /action/:actionId

Delete an action. This is limited to certain actions. You can DELETE:

  • Unassigned ReviewAction or AskAction action (i.e. actions without an agent or participant) so long as they are not the only instance of that type present in a given editorial workflow stage.
  • InviteActions but only so long as the user being invited (invited to participate in a workflow) has not accepted the invite.
  • TagActions

The resulting payload is a DeleteAction.

The :actionId must be specified as a CURIE including the prefix (e.g. scienceai:uuid).

POST /encoding

Store the raw content and metadata of an encoding (MediaObject or subclass thereof). @ids for the encoding and the eventual creative work (resource) encoded by the encoding will be generated.

The following query string parameters are required:

graph
the @id of the graph (Graph) containing the encoding.
name
the name (typically file name) of the encoding.

The following query string parameters are optional:

creativeWork
The @id of the creative work encoded by the encoding (if known)
webify
Set to true of a resource conversion action should be started for the encoding
mainEntity
Set to true if the associated CreativeWork should be set has the mainEntity the Graph.

Returns the metadata associated with the encoding (content size, checksum etc.).

PUT /encoding/:encodingId

Store the raw content and metadata of an encoding (MediaObject or subclass thereof).

The :encodingId must be specified as a CURIE including the prefix (e.g. scienceai:uuid).

The following query string parameters are required:

graph
the @id of the graph (Graph) containing the encoding.
creativeWork
the @id of the encoded creative work.
name
the name (typically file name) of the encoding.

The following query string parameters are optional:

webify
Set to true of a resource conversion action should be started for the encoding
mainEntity
Set to true if the associated CreativeWork should be set has the mainEntity the Graph.

Returns the metadata associated with the encoding (content size, checksum etc.).

GET /encoding/:encodingId

Get the raw content of an Encoding (MediaObject or subclass thereof).

The :encodingId must be specified as a CURIE including the prefix (e.g. scienceai:uuid).

DELETE /encoding/:encodingId

Delete an encoding (MediaObject or subclass thereof) and its associated raw content.

The :encodingId must be specified as a CURIE including the prefix (e.g. scienceai:uuid).

The following query string parameters are supported:

encodedCreativeWork
When set to true this option will trigger the deletion of the creative work encoded by the encoding.

DELETE /event/:eventId

Delete an (Event.

The :eventId must be specified as a CURIE including the prefix (e.g. scienceai:uuid).

Changes Feed

The science.ai changes feed (DataFeed) allows API consumers to browse previous changes or be notified in real time when data are created, updated, or deleted from the science.ai databases.

GET /feed

The following query string parameters are available:

filter
Possible values are:
  • public (default). Restrict the changes to the subset of documents available publicly.
  • user Restrict the changes to the subset of documents that the user has access to (requires authentication).
  • admin Access to all changes (requires admin access).
scope
A Graph or Periodical @id (or JSON list thereof) further narrowing down the emitted changes.
nodes
A boolean (defaulting to true) specifying if the nodes of a Graph should be ignored. When set to false no event are emitted when the nodes changes and Graph (and snapshots of graph) are returned without their nodes (so withouth the @graph property).
descending
A boolean (defaulting to false) specifying to return the changes in sequential order.
limit
A number indicating the maximum number of changes to return (limited to 200 outside of the continuous mode, ignored in continuous mode).
accept
A convenience parameter to use instead of the Accept: text/event-stream HTTP header to specify that the feed should operate in continuous mode using the an event stream. If specified, accept must take the URI encoded value of text/event-stream.
last-event-id
A convenience parameter to use instead of the Last-Event-ID HTTP header. When specified, the API will only return changes that occurred after the specified sequence identifier (last-event-id).

The changes feed is represented as a DataFeed containing DataFeedItem.


{
  "@context": "https://science.ai",
  "@type": "DataFeed",
  "dataFeedElement": [
    {
      "@id": "seq:3",
      "@type": "DataFeedItem",
      "dateCreated": "2016-10-07T21:57:43.766Z",
      "item": {
        "@id": "scienceai:actionId",
        "@type": "Action",
        "actionStatus": "PotentialActionStatus"
      }
    }
  ]
}
          
Example of a DataFeed.

In continuous mode only DataFeedItem are emitted after a mapping to comply to the Server-Sent Events specification:

id: seq:3
event: Action
data: {"@id":"scienceai:actionId","@type":"Action","actionStatus":"PotentialActionStatus"}
          
where:
id
is the @id of the DataFeedItem. This is the value that can be specified in the Last-Event-ID HTTP header.
event
A string grouping DataFeedItem per categories. Possible values are:
  • UserProfile (User profiles for persons)
  • Graph (Graph metadata and nodes)
  • Periodical (Periodicals)
  • Action (Actions)
data
A JSON string representing the value of the DataFeedItem item.

Action reference

Registration

RegisterAction

RegisterAction are used to register new users (Person) to science.ai.

Every registered user gets a personal journal (Periodical) available at the url: https://<username>.science.ai.

HTTP request body posted to the science.ai API to register a new user.

{
  "@context": "https://science.ai",
  "@type":"RegisterAction",
  "actionStatus": "PotentialActionStatus",
  "agent":  {
    "@id": "user:username",
    "@type": "Person",
    "email":"mailto:user@example.com",
    "password": "secret"
  },
  "object":{
    "@id": "https://science.ai",
    "@type": "Product",
    "name": "science.ai"
  },
  "potentialAction": {
    "@type": "CommunicateAction"
   }
}
              
HTTP response body returned by the science.ai API.

{
  "@context": "https://science.ai",
  "@id": "scienceai:registerActionId",
  "@type":"RegisterAction",
  "actionStatus": "ActiveActionStatus",
  "agent":  {
    "@id": "user:username",
    "@type": "Person",
    "email":"mailto:user@example.com"
  },
  "object": {
    "@id": "https://science.ai",
    "@type": "Product",
    "name": "science.ai"
  },
  "startTime":"2016-02-14T00:29:18.514Z",
  "potentialAction": {
    "@type": "CommunicateAction",
    "instrument": {
      "@type": "EmailMessage"
    }
  }
}
              
The email sent to the recipient will embed a ConfirmAction. This enables email clients that support Actions to streamline the registration confirmation experience.

{
  "@context": "https://science.ai",
  "@type": "ConfirmAction",
  "target": {
    "@type": "EntryPoint",
    "httpMethod": "GET",
    "urlTemplate": "http://example.com?action=registerActionId"
  }
}
              
HTTP response body returned by the science.ai API after confirming the registration. Note that a user profile and a periodical have been created as a result of the registration.

{
  "@context": "https://science.ai",
  "@id": "scienceai:registerActionId",
  "@type":"RegisterAction",
  "actionStatus": "CompletedActionStatus",
  "agent":  {
    "@id": "user:username",
    "@type": "Person",
    "email":"mailto:user@example.com"
  },
  "object": {
    "@id": "https://science.ai",
    "@type": "Product",
    "name": "science.ai"
  },
  "startTime": "2016-02-14T00:29:18.514Z",
  "endTime": "2016-02-14T00:29:19.514Z",
  "result": [
    {
      "@id": "user:username",
      "@type": "Person",
      "email":"mailto:user@example.com",
      "memberOf": {
        "@type": "OrganizationRole",
        "memberOf": "https://science.ai",
        "startDate": "2016-02-14T00:29:19.514Z"
      }
    },
    {
      "@id": "scienceai:journal",
      "@type": "Periodical",
      "name": "username journal"
    }
  ],
  "potentialAction": {
    "@type": "CommunicateAction",
    "actionStatus": "CompletedActionStatus",
    "startTime": "2016-02-14T00:29:19.514Z",
    "endTime": "2016-02-14T00:29:19.514Z",
    "agent": "user:username",
    "instrument": {
      "@type": "EmailMessage",
      "potentialAction": {
        "@type": "ConfirmAction",
        "actionStatus": "CompletedActionStatus",
        "agent": "user:username",
        "startTime": "2016-02-14T00:29:19.514Z",
        "endTime": "2016-02-14T00:29:19.514Z"
      }
    }
  }
}
              

Resource creation

CreateOrganizationAction

Create organization actions (CreateOrganizationAction) are used to create new (Organizations). An Organization is essentially a publisher. It serves as a collection of Periodicals such that they can share some important settings (for instance adminstrators or payment).

HTTP request body posted to the science.ai API to create a new organization.


{
  "@context": "https://science.ai",
  "@type": "CreateOrganizationAction",
  "agent": {
    "@type": "Role",
    "roleName": "member",
    "agent": "user:peter"
  },
  "actionStatus": "CompletedActionStatus",
  "result": {
    "@id":    "org:orgId",
    "@type":  "Organization",
    "name":   "Giles Librarian Publications",
    "member":   [
      {
        "@type":  "Role",
        "roleName": "member",
        "member": "user:peter"
      }
    ],
    "contactPoint": {
      "@type":  "ContactPoint",
      "email":  "mailto:peter@example.io"
    }
  }
}
              

HTTP response body returned by the science.ai upon successful organization creation.


{
  "@context": "https://science.ai",
  "@id": "scienceai:createOrganizationActionId",
  "@type": "CreateOrganizationAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2016-02-14T00:29:19.514Z",
  "endTime": "2016-02-14T00:29:19.514Z",
  "agent": {
    "@type": "Role",
    "roleName": "member",
    "agent": "user:peter"
  },
  "result": {
    "@id":    "org:orgId",
    "@type":  "Organization",
    "name":   "Giles Librarian Publications",
    "creator":  {
      "@type":  "Role",
      "roleName": "member",
      "member": "user:peter"
    },
    "member":   [
      {
        "@type":  "Role",
        "roleName": "member",
        "member": "user:peter"
      }
    ],
    "contactPoint": {
      "@type":  "ContactPoint",
      "email":  "mailto:peter@example.io"
    }
  }
}
              

CreatePeriodicalAction

Create periodical actions (CreatePeriodicalAction) allow to create new journals (Periodical). Note that the object of this action must be an Organization, serving as the journal's publisher

HTTP request body posted to the science.ai API to create a new journal


{
  "@context": "https://science.ai",
  "@type": "CreatePeriodicalAction",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": "user:peter"
  },
  "object": "org:orgId",
  "result": {
    "@type": "Periodical",
    "url": "https://myjournal.science.ai",
    "name": "my journal"
  }
}
              

HTTP response body returned by the science.ai upon successful journal creation


{
  "@context": "https://science.ai",
  "@id": "scienceai:createPeriodicalActionId",
  "@type": "CreatePeriodicalAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2016-02-14T00:29:19.514Z",
  "endTime": "2016-02-14T00:29:19.514Z",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": "user:peter"
  },
  "object": "org:orgId",
  "result": {
    "@id": "scienceai:periodicalId",
    "@type": "Periodical",
    "dateCreated": "2016-02-14T00:29:19.514Z",
    "creator": {
     "@type": "Role",
     "roleName": "author",
     "creator": "user:peter"
    },
    "publisher": "org:orgId",
    "url": "https://myjournal.science.ai",
    "name": "my journal"
  }
}
              

CreateGraphAction

A CreateGraphAction allows to create a a Graph.

A CreateGraphAction is typically initialized from the potential action (potentialAction) of a Periodical (see Journal and editorial workflow management section) or a Service (see service section).

HTTP request body.

{
  "@context": "https://science.ai",
  "@id": "scienceai:createGraphActionId",
  "@type": "CreateGraphAction",
  "actionStatus": "PotentialActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:journalId",
    "@type": "Periodical"
  }
}
              

When a CreateGraphAction is a potential action of a Periodical (and therefore part of an editorial workflow process) it may have a participant property specifying which member of the editorial office (if any) should be added to the workflow when a submission is initiated.

If specified, the participant property must list (or refer to) ContributorRoles listed in the Periodical document. In particular, the roleContactPoint property must be defined for these roles.

When POSTing a CreateGraphAction, the result property can be used to provide custom values for the created Graph.

HTTP response body.


{
  "@context": "https://science.ai",
  "@id": "scienceai:createGraphActionId",
  "@type": "CreateGraphAction",
  "actionStatus": "PotentialActionStatus",
  "startTime": "2016-02-14T00:29:19.514Z",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:journalId",
    "@type": "Periodical"
  },
  "result": {
      "@id": "scienceai:graphId",
      "@type": "Graph",
      "publisher": "org:orgId",
      "@graph": [
        {
          "@id": "scienceai:scholarlyArticleId",
          "@type": "ScholarlyArticle",
          "creator": "_:b1",
          "dateCreated": "2016-02-14T00:29:19.514Z"
        },
        {
          "@id": "_:b1",
          "@type": "Role",
          "roleName": "author",
          "creator": "user:peter"
        }
      ]
    }
}
              

POSTing a CreateGraphAction without a defined @id will add the workflow (CreateGraphAction) to the list of potential actions (potentialAction) of a Periodical (object of the CreateGraphAction). In that case, the agent of the CreateGraphAction should be omitted.

Note that in order to invoke this action, the Periodical that it applies to must belong to an Organization subscribing to a paid plan.

Updates

UpdateAction

UpdateAction are the only way to update graphs (Graph), journals (Periodical), reviews (Review), comments (Comment) or user profiles (Person).

HTTP request body posted to the science.ai API to update a resource (Dataset) of a Graph


{
  "@context": "https://science.ai",
  "@type": "UpdateAction",
  "actionStatus": "CompletedActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:datasetId",
    "@type": "Dataset",
    "description": "my dataset"
  },
  "targetCollection": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  }
}
              

HTTP response body returned by the science.ai API upon a successful update action


{
  "@context": "https://science.ai",
  "@type": "UpdateAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2016-02-14T00:29:19.514Z",
  "endTime": "2016-02-14T00:29:19.514Z",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:datasetId",
    "@type": "Dataset",
    "description": "my dataset"
  },
  "result": {
    "@id": "scienceai:datasetId",
    "@type": "Dataset",
    "name": "dataset",
    "description": "my dataset"
  },
  "targetCollection": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  }
}
              

UpdateOrganizationAction

UpdateOrganizationActions are the way in which Organizations are updated.

HTTP request body posted to the science.ai API to update an Organization.


{
  "@context": "https://science.ai",
  "@type": "UpdateOrganizationAction",
  "actionStatus": "CompletedActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "member",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:orgId",
    "@type": "Organization",
    "name": "Hellmouth Inc."
  }
}
              

HTTP response body returned by the science.ai API upon a successful update action


{
  "@context": "https://science.ai",
  "@type": "UpdateAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2016-02-14T00:29:19.514Z",
  "endTime": "2016-02-14T00:29:19.514Z",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:datasetId",
    "@type": "Dataset",
    "description": "my dataset"
  },
  "result": {
    "@id": "scienceai:datasetId",
    "@type": "Dataset",
    "name": "dataset",
    "description": "my dataset"
  },
  "targetCollection": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  }
}
              

AddAction

Add actions (AddAction) are used to add an object to a collection.

Example of an AddAction.


{
  "@context": "https://science.ai",
  "@type": "AddAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2016-02-14T00:29:19.514Z",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": "user:doug"
  },
  "object": {
    "name": "Ancient astronaut theory"
  },
  "targetCollection": {
    "@type": "TargetRole",
    "targetCollection": "scienceai:periodicalId",
    "hasSelector": {
      "@type": "NodeSelector",
      "nodeId": "scienceai:periodicalId",
      "nodeKey": "about"
    }
  }
}
              

DeleteAction

Delete actions (DeleteAction) are used to remove an object from a collection.

Example of a DeleteAction.


{
  "@context": "https://science.ai",
  "@type": "DeleteAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2016-02-14T00:29:19.514Z",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": "user:doug"
  },
  "object": {
    "@id": "_:nodeId",
    "name": "Ancient astronaut theory"
  },
  "targetCollection": {
    "@type": "TargetRole",
    "targetCollection": "scienceai:periodicalId",
    "hasSelector": {
      "@type": "NodeSelector",
      "nodeId": "scienceai:periodicalId",
      "nodeKey": "about"
    }
  }
}
              

Resource conversion

Resource conversions are performed asynchronously by a pool of "workers". An HTTP status code of 202 is returned to acknowledge that the work is being processed. The API can be polled to detect the completion status of an action, or, more efficiently, the caller can listen to the science.ai changes feed to be notified of the action's completion. The result of a resource conversion action is an UpdateAction so that API consumers can have the opportunity to merge conflicts (if any, see multiversion concurrency control section) when executing the UpdateAction.

Resource conversion are initiated by POSTing a resource conversion action to the API.

Resource conversion can be canceled at any time by issuing a DeactivateAction. If the resource has already been converted and stored, this is a noop and the action will be in a FailedActionStatus.

RdfaConversionAction

RDFa conversion actions (RdfaConversionAction) are used to convert encodings into HTML / RDFa and extract the metadata contained in the encoding.

HTTP request body posted to the science.ai API to initiate the conversion of a Microsoft Word document (DOCX) to HTML / RDFa (RdfaConversionAction).


{
  "@context": "https://science.ai",
  "@type": "RdfaConversionAction",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:encodingId",
    "fileFormat": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "contentUrl": "http://example.com/article.docx"
  }
}
              

The object of a RdfaConversionAction must be an encoding (MediaObject or subclass thereof) with a valid contentUrl property (the raw content should have been uploaded using the POST /encoding route of the science.ai API).

The fileFormat of the MediaObject must be one of the following:

Media types for conversion sources
File Type Media Type (fileFormat) Restrictions
DOCX application/vnd.openxmlformats-officedocument.wordprocessingml.document Content must follow DOCX Standard Scientific Style
JATS application/vnd.scienceai.jats+tgz -
HTTP response body returned by the science.ai API to acknowledge that the action has been accepted by the system.

{
  "@context": "https://science.ai",
  "@id": "scienceai:rdfaConversionActionId",
  "@type": "RdfaConversionAction",
  "actionStatus": "PotentialActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:encodingId",
    "fileFormat": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "contentUrl": "http://example.com/article.docx",
    "encodesCreativeWork": "scienceai:resourceId"
  },
  "result": "scienceai:updateActionId",
  "instrument": "scienceai:graphId",
  "potentialAction": {
    "@type": "DeactivateAction",
    "target": {
      "@type": "EntryPoint",
      "httpMethod": "POST",
      "urlTemplate": "http://example.com?action=rdfaConversionActionId",
      "encodingType": "application/ld+json",
      "contentType": "application/ld+json"
    }
  }
}
              

An action status of ActiveActionStatus will only be set once a worker starts to process the work.

Note that:

HTTP response body returned by the science.ai API once a RdfaConversionAction has been completed. Note that in addition to an HTML / RDFa encoding, metadata and sub-resources embedded in the DOCX file are extracted.

{
  "@context": "https://science.ai",
  "@id": "scienceai:rdfaConversionActionId",
  "@type": "RdfaConversionAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2016-02-14T00:29:19.514Z",
  "endTime": "2016-02-14T00:30:19.514Z",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:encodingId",
    "fileFormat": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "contentUrl": "http://example.com/article.docx",
    "encodesCreativeWork": "scienceai:resourceId"
  },
  "instrument": "scienceai:graphId",
  "result": {
    "@id": "scienceai:updateActionId",
    "@type": "UpdateAction",
    "object": {
      "@id": "scienceai:resourceId",
      "@type": "ScholarlyArticle",
      "name": "extracted title",
      "description": "extracted abstract",
      "encoding": {
        "@id": "scienceai:htmlEncodingId",
        "@type": "DocumentObject",
        "contentUrl": "http://example.com/article.html",
        "isBasedOn": "scienceai:encodingId"
      },
      "hasPart": [
        {
          "@id": "scienceai:image",
          "@type": "Image",
          "name": "extracted title",
          "caption": "extracted caption",
          "encoding": {
            "@id": "scienceai:imageEncodingId",
            "@type": "ImageObject",
            "contentUrl": "http://example.com/image.png"
          }
        },
        {
          "@id": "scienceai:table",
          "@type": "Table",
          "name": "extracted title",
          "caption": "extracted caption",
          "encoding": {
            "@id": "scienceai:tableEncodingId",
            "@type": "TableObject",
            "contentUrl": "http://example.com/table.html"
          }
        }
      ]
    },
    "targetCollection": "scienceai:graphId"
  }
}
              

ImageProcessingAction

Image processing actions (ImageProcessingAction) are used to convert image encodings into web friendly formats and extract metadata about the image (e.g. perceptual hash).

HTTP request body posted to the science.ai API to convert images into web friendly formats (ImageProcessingAction).


{
  "@context": "https://science.ai",
  "@type": "ImageProcessingAction",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:encodingId",
    "fileFormat": " image/eps",
    "contentUrl": "http://example.com/image.eps"
  }
}
              

The object of an ImageProcessingAction must be an encoding (MediaObject or subclass thereof) with a valid contentUrl property (the raw content should have been uploaded using the POST /encoding route of the science.ai API).

HTTP response body returned by the science.ai API to acknowledge that the action has been accepted by the system.


{
  "@context": "https://science.ai",
  "@id": "scienceai:imageProcessingActionId",
  "@type": "ImageProcessingAction",
  "actionStatus": "PotentialActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:encodingId",
    "fileFormat": " image/eps",
    "contentUrl": "http://example.com/image.eps",
    "encodesCreativeWork": "scienceai:resourceId"
  },
  "result": "scienceai:updateActionId",
  "instrument": "scienceai:graphId",
  "potentialAction": {
    "@type": "DeactivateAction",
    "target": {
      "@type": "EntryPoint",
      "httpMethod": "POST",
      "urlTemplate": "http://example.com?action=imageProcessingActionId",
      "encodingType": "application/ld+json",
      "contentType": "application/ld+json"
    }
  }
}
              

An action status of ActiveActionStatus will only be set once a worker starts to process the work.

Note that:

HTTP response body returned by the science.ai API once an ImageProcessingAction has been completed.


{
  "@context": "https://science.ai",
  "@id": "scienceai:imageProcessingActionId",
  "@type": "ImageProcessingAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2016-02-14T00:29:19.514Z",
  "endTime": "2016-02-14T00:30:19.514Z",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:encodingId",
    "fileFormat": " image/eps",
    "contentUrl": "http://example.com/image.eps",
    "encodesCreativeWork": "scienceai:resourceId"
  },
  "instrument": "scienceai:graphId",
  "result": {
    "@id": "scienceai:updateActionId",
    "@type": "UpdateAction",
    "object": {
      "@id": "scienceai:resourceId",
      "@type": "Image",
      "encoding": {
        "@id": "scienceai:convertedEncodingId",
        "@type": "ImageObject",
        "fileFormat": "image/png",
        "width": "1600px",
        "height": "1600px",
        "isBasedOn": "scienceai:encodingId",
        "thumbnail": {
          "@id": "scienceai:small-thumbnail",
          "@type": "ImageObject",
          "contentUrl": "http://example.com/image-400x400.png",
          "fileFormat": "image/png",
          "width": "400px",
          "height": "400px",
          "isBasedOn": "scienceai:encodingId"
        }
      }
    },
    "targetCollection": "scienceai:graphId"
  }
}
              

AudioVideoProcessingAction

Audio video processing actions (AudioVideoProcessingAction) are used to convert audio and video encodings into web friendly format and extract metadata about the media.

HTTP request body posted to the science.ai API to convert audio and video resources into web friendly formats (AudioVideoProcessingAction).


{
  "@context": "https://science.ai",
  "@type": "AudioVideoProcessingAction",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:encodingId",
    "fileFormat": "video/quicktime",
    "contentUrl": "http://example.com/video.mov"
  }
}
              

The object of an AudioVideoProcessingAction must be an encoding (MediaObject or subclass thereof) with a valid contentUrl property (the raw content should have been uploaded using the POST /encoding route of the science.ai API).

HTTP response body returned by the science.ai API to acknowledge that the action has been accepted by the system.


{
  "@context": "https://science.ai",
  "@id": "scienceai:audioVideoProcessingActionId",
  "@type": "AudioVideoProcessingAction",
  "actionStatus": "PotentialActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:encodingId",
    "fileFormat": "video/quicktime",
    "contentUrl": "http://example.com/video.mov",
    "encodesCreativeWork": "scienceai:resourceId"
  },
  "result": "scienceai:updateActionId",
  "instrument": "scienceai:graphId",
  "potentialAction": {
    "@type": "DeactivateAction",
    "target": {
      "@type": "EntryPoint",
      "httpMethod": "POST",
      "urlTemplate": "http://example.com?action=audioVideoProcessingActionId",
      "encodingType": "application/ld+json",
      "contentType": "application/ld+json"
    }
  }
}
              

An action status of ActiveActionStatus will only be set once a worker starts to process the work.

Note that:

HTTP response body returned by the science.ai API once an AudioVideoProcessingAction has been completed.


{
  "@context": "https://science.ai",
  "@id": "scienceai:audioVideoProcessingActionId",
  "@type": "AudioVideoProcessingAction",
  "actionStatus": "PotentialActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:encodingId",
    "fileFormat": "video/quicktime",
    "contentUrl": "http://example.com/video.mov",
    "encodesCreativeWork": "scienceai:resourceId"
  },
  "instrument": "scienceai:graphId",
  "result": {
    "@id": "scienceai:updateActionId",
    "@type": "UpdateAction",
    "object": {
      "@id": "scienceai:resourceId",
      "@type": "Video",
      "encoding": {
        "@id": "scienceai:convertedEncodingId",
        "@type": "VideoObject",
        "contentUrl": "http://example.com/video.mpeg",
        "fileFormat": "video/mpeg",
        "isBasedOn": "scienceai:encodingId",
        "thumbnail": {
          "@id": "scienceai:video-small-thumbnail",
          "@type": "ImageObject",
          "contentUrl": "http://example.com/image-400x400.png",
          "fileFormat": "image/png",
          "width": "400px",
          "height": "400px",
          "isBasedOn": "scienceai:encodingId"
        }
      }
    },
    "targetCollection": "scienceai:graphId"
  }
}
              

Progress events

InformAction

Inform actions (InformAction) are used to issue events (such as ProgressEvent about an Action.

Example of an InformAction used to issue a ProgressEvent.


{
  "@context": "https://science.ai",
  "@type": "InformAction",
  "agent": "bot:document-worker",
  "participant": "user:peter",
  "object": "scienceai:rdfaConversionActionId",
  "startTime": "2020-01-01T21:04:20.262Z",
  "endTime": "2020-01-01T21:04:20.262Z",
  "event": {
    "@type": "ProgressEvent",
    "name": "converting file",
    "startDate": "2020-01-01T21:04:20.262Z"
  }
}
              

The object of an InformAction must be an Action

InformActions posted to the API (and the associated Event) will have @id assigned. Trees of events can be generated by specifying the parent event (superEvent) of an event. Posting an InformAction referencing an existing event allows to update it. This is particularly useful for long lasting operations containing sub events such as the following sequence capturing the progress of a conversion action:

The first event signaling the beginning of a file conversion.

  {
    "@context": "https://science.ai",
    "@id": "scienceai:informActionId1",
    "@type": "InformAction",
    "agent": "bot:document-worker",
    "participant": "user:peter",
    "object": "scienceai:rdfaConversionActionId",
    "startTime": "2020-01-01T21:04:20.262Z",
    "endTime": "2020-01-01T21:04:20.262Z",
    "event": {
      "@id": "scienceai:convertingEventId",
      "@type": "ProgressEvent",
      "name": "converting file",
      "startDate": "2020-01-01T21:04:20.262Z"
    }
  }
              
A sub event providing more information (10% progress) about the parent event (superEvent)


{
  "@context": "https://science.ai",
  "@id": "scienceai:informActionId2",
  "@type": "InformAction",
  "agent": "bot:document-worker",
  "participant": "user:peter",
  "object": "scienceai:rdfaConversionActionId",
  "startTime": "2020-01-01T21:05:20.262Z",
  "endTime": "2020-01-01T21:05:20.262Z",
  "event": {
    "@type": "ProgressEvent",
    "superEvent": "scienceai:subEventId1",
    "startDate": "2020-01-01T21:05:20.262Z",
    "endDate": "2020-01-01T21:05:20.262Z",
    "progress": {
      "@type": "QuantitativeValue",
      "minValue": 0,
      "maxValue": 100,
      "value": 10
    }
  }
}
              
Another sub event providing more information (90% progress) about the parent event (superEvent)

{
  "@context": "https://science.ai",
  "@id": "scienceai:informActionId3",
  "@type": "InformAction",
  "agent": "bot:document-worker",
  "participant": "user:peter",
  "object": "scienceai:rdfaConversionActionId",
  "startTime": "2020-01-01T21:06:20.262Z",
  "endTime": "2020-01-01T21:06:20.262Z",
  "event": {
    "@type": "ProgressEvent",
    "superEvent": "scienceai:subEventId2",
    "startDate": "2020-01-01T21:06:20.262Z",
    "endDate": "2020-01-01T21:06:20.262Z",
    "progress": {
      "@type": "QuantitativeValue",
      "minValue": 0,
      "maxValue": 100,
      "value": 90
    }
  }
}
              
Finally when the file conversion completes, the first event is updated to specify its endDate marking its completion.

{
  "@context": "https://science.ai",
  "@id": "scienceai:informActionId4",
  "@type": "InformAction",
  "agent": "bot:document-worker",
  "participant": "user:peter",
  "object": "scienceai:rdfaConversionActionId",
  "startTime": "2020-01-01T21:07:20.262Z",
  "endTime": "2020-01-01T21:07:20.262Z",
  "event": {
    "@id": "scienceai:convertingEventId",
    "@type": "ProgressEvent",
    "name": "converting file",
    "startDate": "2020-01-01T21:04:20.262Z",
    "endDate": "2020-01-01T21:07:20.262Z"
  }
}
              

Access control and resource management

AuthorizeAction

Authorize actions (AuthorizeAction) are used to set (or update) digital document permissions (DigitalDocumentPermission) or contributors (ContributorRole) of journals (Periodical).

HTTP request body.


{
  "@context": "https://science.ai",
  "@type": "AuthorizeAction",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:periodicalId",
    "@type": "Periodical"
  },
  "instrument": {
    "@type": "DigitalDocumentPermission",
    "grantee": {
      "@type": "Audience",
      "audienceType": "editor"
    },
    "permissionType": "AdminPermission"
  }
}
              

HTTP response body.


{
  "@context": "https://science.ai",
  "@id": "scienceai:authorizeActionId",
  "@type": "AuthorizeAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2020-01-01T21:04:20.262Z",
  "endTime": "2020-01-01T21:04:20.262Z",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:periodicalId",
    "@type": "Periodical"
  },
  "instrument": {
    "@type": "DigitalDocumentPermission",
    "grantee": {
      "@type": "Audience",
      "audienceType": "editor"
    },
    "permissionType": "AdminPermission"
  },
  "result": {
    "@id": "scienceai:periodicalId",
    "@type": "Periodical",
    "hasDigitalDocumentPermission": {
      "@type": "DigitalDocumentPermission",
      "grantee": {
        "@type": "Audience",
        "audienceType": "editor"
      },
      "permissionType": "AdminPermission"
    }
  }
}
              

DeauthorizeAction

Deauthorize actions (DeauthorizeAction) are antonym actions of AuthorizeAction and are used to revoke permissions or contact points associated with periodicals (Periodical).

HTTP request body. Here we want to revoke the AdminPermission for editors.


{
  "@context": "https://science.ai",
  "@type": "DeauthorizeAction",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:periodicalId",
    "@type": "Periodical"
  },
  "instrument": {
    "@type": "DigitalDocumentPermission",
    "grantee": {
      "@type": "Audience",
      "audienceType": "editor"
    },
    "permissionType": "AdminPermission"
  }
}
              

InviteAction

Invite actions (InviteAction) are used to invite a recipient ( Person) to join a Graph, an Organization, or a Periodical. To be completed (and executed), an InviteAction must be accepted or rejected (see AcceptAction and RejectAction) by its recipient.

When the InviteAction is accepted, the recipient will be added to the object of the InviteAction with the appropriate permissions.

HTTP request body to invite a recipient to an object (here a Graph).


{
  "@context": "https://science.ai",
  "@type":"InviteAction",
  "description": "Invitation to review a manuscript",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": "user:elsa"
  },
  "recipient": {
    "@type": "Role",
    "roleName": "reviewer",
    "recipient": {
      "@type": "Person",
      "email": "peter@example.com"
    }
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "potentialAction": {
    "@type": "CommunicateAction"
  }
}
              
HTTP response body received by the agent

{
  "@context": "https://science.ai",
  "@id": "scienceai:inviteActionId",
  "@type":"InviteAction",
  "actionStatus": "ActiveActionStatus",
  "startTime": "2020-01-01T21:04:20.262Z",
  "description": "Invitation to review a manuscript",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": "user:elsa"
  },
  "recipient": {
    "@type": "Role",
    "roleName": "reviewer",
    "recipient": {
      "@type": "Person",
      "email": "peter@example.com"
    }
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "potentialAction": {
    "@type": "CommunicateAction"
  }
}
              
HTTP response body emitted by the changes feed once the recipient accepts the InviteAction (the potentialAction property contains a completed AcceptAction). Note that if the recipient were to reject the InviteAction, the potentialAction property will contain a RejectAction

{
  "@context": "https://science.ai",
  "@id": "scienceai:authorizeActionId",
  "@type":"InviteAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2020-01-01T21:04:20.262Z",
  "endTime": "2020-01-04T21:04:20.262Z",
  "description": "Invitation to review a manuscript",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": "user:elsa"
  },
  "recipient": {
    "@type": "Role",
    "roleName": "reviewer",
    "recipient": {
      "@type": "Person",
      "email": "peter@example.com"
    }
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "potentialAction": [
    {
      "@type": "CommunicateAction",
      "actionStatus": "CompletedActionStatus"
    },
    {
      "@type": "AcceptAction",
      "actionStatus": "CompletedActionStatus"
    }
  ]
}
              

AcceptAction

Accept actions (AcceptAction) are used by the recipient of an InviteAction to accept it.

Example of an AcceptAction.

{
  "@context": "https://science.ai",
  "@type": "AcceptAction",
  "actionStatus": "CompletedActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "reviewer",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:inviteActionId",
    "@type": "InviteAction"
  }
}
              

RejectAction

Reject actions (RejectAction) are used by the recipient of an InviteAction to reject (decline) it.

Example of a RejectAction.

{
  "@context": "https://science.ai",
  "@type": "RejectAction",
  "actionStatus": "CompletedActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "reviewer",
    "agent": "user:peter"
  },
  "object": {
    "@id": "scienceai:inviteActionId",
    "@type": "InviteAction"
  }
}
              

JoinAction

Join actions (JoinAction) allow user already contributing to a Graph or a Periodical to join it as an additional role.

Example of a JoinAction.

{
  "@context": "https://science.ai",
  "@type": "JoinAction",
  "actionStatus": "CompletedActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": "user:doug"
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  }
}
              

LeaveAction

Leave actions (LeaveAction) allow user to leave a Graph, an Organization, or a Periodical. The caller can decide if only a specific persona is leaving, or if all the persona associated with a person are leaving (except in the case of Organizations, where leaving is always fully leaving).

Example of a LeaveAction.

{
  "@context": "https://science.ai",
  "@type": "LeaveAction",
  "actionStatus": "CompletedActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": "user:doug"
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  }
}
              

ActivateAction

ActivateAction are used to activate a workflow (CreateGraphAction).

HTTP request body.

{
  "@type": "ActivateAction",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": "scienceai:createGraphActionId"
}
              

The object of a ActivateAction must be a CreateGraphAction.

DeactivateAction

DeactivateAction are used either to:

  • Cancel a resource conversion action (the object of the DeactivateAction). Note that in that case the DeactivateAction only has an effect if the action has not already been carried out. In no case will it cause a roll back of the action's effects, it can only effectively fully stop it if it has not yet produced any effect.
  • Deactivate an active workflow (CreateGraphAction)
HTTP request body.

{
  "@type": "DeactivateAction",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": "user:peter"
  },
  "object": "scienceai:actionId"
}
              

ConsumeAction

Consume actions (ConsumeAction) can be used to model paywalls. They are typically created as a side effect of a CreateOfferAction.

A ConsumeAction acting as a paywall for a ScholarlyArticle. The ConsumeAction cannot be performed until the Offer has been accepted. Offers typically represents a purchase or subscription option.

{
  "@type": "ScholarlyArticle",
  "potentialAction": {
    "@type": "ConsumeAction",
    "expectsAcceptanceOf": {
      "@type": "Offer",
      "potentialAction": {
        "@type": "BuyAction",
        "price": "25USD"
      }
    }
  }
}
              

AuthorizePaymentAction

AuthorizePaymentActions are used to add the ability to process payments on their object, using a Stripe token. The calling code is expected to acquire the token using one of the methods made available by Stripe, and then to set it on either a Person or Organization using this type of action.

When an Organization is authorized for payment, it becomes able to consume a plan so that its Periodicals can become used to the full extent of the science.ai platform.

When a Person becomes authorized for payment, they can subscribe to Periodicals or buy content.

Note that authorizing payment does not trigger a payment. It only enables the means of payment, that later get triggered by other actions.

An AuthorizePaymentAction being used to authorize a method of payment with an Organization.

{
  "@type": "AuthorizePaymentAction",
  "actionStatus": "CompletedActionStatus",
  "agent": {
    "@type": "Person",
    "@id": "user:userId"
  },
  "object": "org:orgId",
  "instrument": {
    "@type":  "StripeToken",
    "value":  "stripeTokenValue"
  }
}
              

ConsumePlanAction

A ConsumePlanAction is used to subscribe an Organization to a given plan. Being subscribed to a paid plan activates all the Periodicals that belong to that organization. Paid plans all have the same features, but the differ in volume discounts.

As of this writing the different plans are no-plan — a default "dud" plan that is the default before a paid plan has been consumed (or after payment has persistently failed leading to paid plan cancellation) — and a choice of explorer-201703, voyager-201703, or enterprise-201703 all of which are paid plans. Other plans are likely to come into existence at later dates.

An ConsumePlanAction being used to subscribe an Organization to a Voyager plan.

{
  "@type": "ConsumePlanAction",
  "actionStatus": "CompletedActionStatus",
  "agent": {
    "@type": "Person",
    "@id": "user:userId"
  },
  "object": "org:orgId",
  "instrument": {
    "@type": "Offer",
    "serialNumber": "voyager-201703"
  }
}
              

BuyAction

Buy actions (BuyAction) are typically used to mediate the purchase of an Offer.

Example of a BuyAction.

{
  "@type": "Offer",
  "@id": "scienceai:offerId",
  "potentialAction": {
    "@type": "BuyAction",
    "actionStatus": "CompletedActionStatus",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://example.com/offerId/buy",
      "encodingType": "application/ld+json",
      "contentType": "application/ld+json"
    },
    "result": {
      "@type": "Order",
      "confirmationNumber": "1ABBCDDF23234",
      "orderNumber": "1199334"
    }
  }
}
              

Editorial Workflow management

The editorial workflow of a graph (Graph) is modeled by the permission associated with the Graph and a series of potential actions (potentialAction). Editorial workflows are typically a peer review processes, but publication workflows are very flexible and can represent other processes as well (e.g. article types for which the editor simply decides to publish without review, as in the case of editorials).

Actions can be assigned to users (Person or Organziation) by setting their agent and participant properties.

Typical actions used during the editorial workflow of a Graph
Action Description Multiple participants
AskAction Ask information (answers to custom questions, results, etc.) about the submission yes
ReplyAction Respond to Questions issued during an AskAction and / or a ReviewAction no
ReviewAction collects reviews about snapshot (version) of the graph no
AssessAction assesses if the submission can be published in the target journal yes
CreateReleaseAction creates revisions (snapshots) of a submission yes
ScheduleAction schedules a publication date for the submission yes
AllocateAction allocates a URL to the submission yes
CreateOfferAction creates commercial offers for the submission yes
PayAction collects article processing charges yes

CreateWorkflowStageAction

CreateWorkflowStageAction are used to orchestrate editorial workflows.

Actions specified as results of a CreateWorkflowStageAction obey the following rules:

Actions automatically activated as part of a CreateWorkflowStageAction will refer to that CreateWorkflowStageAction through their resultOf property.

Example of a CreateWorkflowStageAction defining the Submission stage of an editorial workflow.

{
  "@context": "https://science.ai",
  "@type": "CreateWorkflowStageAction",
  "name": "Submission stage",
  "result": {
    "@type": "CreateReleaseAction",
    "agent": { "@type": "Role", "roleName": "author" },
    "name": "Upload files",
    "expectedDuration": "P1D",
    "result": {
      "@type": "Graph",
      "potentialAction": {
        "@type": "AssessAction",
        "expectedDuration": "P2D",
        "agent": { "@type": "Role", "roleName": "editor" },
        "name": "Assess manuscript",
        "result": [
          {
            "@type": "RejectAction",
            "agent": { "@type": "Role", "roleName": "editor" }
          },

          {
            "@type": "CreateWorkflowStageAction",
            "name": "Production stage",
            "alternateName": "Accept",
            "result": [
              {
                "@type": "AllocateAction",
                "expectedDuration": "P2D",
                "agent": { "@type": "Role", "roleName": "producer" },
                "name": "Allocate a URL"
              },
              {
                "@type": "CreateReleaseAction",
                "expectedDuration": "P7D",
                "agent": { "@type": "Role", "roleName": "producer" },
                "name": "Publish",
                "result": {
                  "@type": "Graph",
                  "hasDigitalDocumentPermission": {
                    "@type": "DigitalDocumentPermission",
                    "grantee": {
                      "@type": "Audience",
                      "audienceType": "public"
                    }
                  }
                }
              }
            ]
          }
        ]
      }
    }
  }
}
              

AskAction

An AskAction is used to ask information (answers to custom questions, results, etc.) regarding a Graph. These are typically journal-dependent questions (Question) (e.g. for deontological issues) that need to be answered (Answer) before an article can be published.

HTTP request body allowing to attach a custom Question (with suggestedAnswer) to a Graph.

{
  "@context": "https://science.ai",
  "@id": "scienceai:askActionId",
  "@type": "AskAction",
  "actionStatus": "PotentialActionStatus",
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "question": {
    "@type": "Question",
    "text": "Were experimental animals used?",
    "suggestedAnswer": [
      {
        "@type": "Answer",
        "text": "yes"
      },
      {
        "@type": "Answer",
        "text": "no"
      }
    ]
  }
}
              

The object of an AskAction must be a Graph.

HTTP response body obtained after the AskAction has been completed.

{
  "@context": "https://science.ai",
  "@id": "scienceai:askActionId",
  "@type": "AskAction",
  "actionStatus": "PotentialActionStatus",
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "question": {
    "@id": "_:questionId",
    "@type": "Question",
    "text": "Were experimental animals used?",
    "suggestedAnswer": [
      {
        "@type": "Answer",
        "text": "yes"
      },
      {
        "@type": "Answer",
        "text": "no"
      }
    ]
  },
  "result": {
    "@type": "Answer",
    "text": "yes",
    "parentItem": "_:questionId"
  }
}
              

The result of an AskAction. is typically an Answer. Other common results include: DisclosureAction, SponsorRole or UpdateAction.

ReplyAction

Reply actions (ReplyAction) are used to provide answers (Answer) to questions (Question) raised during ReviewAction or AskAction.

Example of a ReplyAction.

{
  "@context": "https://science.ai",
  "@type": "ReplyAction",
  "actionStatus": "CompletedActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": "user:doug"
  },
  "object": {
    "@id": "scienceai:questionId",
    "@type": "Question"
  },
  "resultComment": {
    "@type": "Answer",
    "text": "42."
  }
}
              

ReviewAction

Review actions (ReviewAction) are used to create reviews (Review) about a Graph.

HTTP request body to request a Review for a specific version of Graph.

{
  "@context": "https://science.ai",
  "@type": "ReviewAction",
  "actionStatus": "PotentialActionStatus",
  "object": {
    "@id": "scienceai:graphId?version=1.0.0",
    "@type": "Graph"
  }
}
              

The object of a ReviewAction must be a Graph (or a version of a graph).

AssessAction

Assess actions (AssessAction) are used in the context of the editorial workflow process to capture the final decision made by an agent.

An AssessAction results in either:

HTTP request body to specify that the Graph needs a final assessment (AssessAction).


{
  "@context": "https://science.ai",
  "@type": "AssessAction",
  "actionStatus": "PotentialActionStatus",
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  }
}
              

The object of an AssessAction must be a Graph (or a version of a graph).

HTTP response body.

{
  "@context": "https://science.ai",
  "@id": "scienceai:assessActionId",
  "actionStatus": "PotentialActionStatus",
  "@type": "AssessAction",
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  }
}
              
HTTP response body obtained after the agent (an editor here) completed the AssessAction (setting the result property)

{
  "@context": "https://science.ai",
  "@type": "AssessAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2022-12-01T22:01Z",
  "endTime": "2022-12-03T22:01Z",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": {
      "@id": "user:peter",
      "@type": "Person"
    }
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "result": {
    "@type": "AcceptAction"
  }
}
              

If the assessment was obtained with the help of review actions (ReviewAction), the relevant review action @ids should be specified in the instrument property of the AssessAction.

CreateReleaseAction

A CreateReleaseAction takes a snapshot (version) of a Graph.

Note that releases (Graph snapshot) can include reviews (Review) generated during the editorial workflow process of the Graph.

HTTP request body.

{
  "@context": "https://science.ai",
  "@type": "CreateReleaseAction",
  "actionStatus": "CompletedActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": {
      "@id": "user:peter",
      "@type": "Person"
    }
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "result": {
    "@id": "scienceai:graphId?version=1.0.0",
    "@type": "Graph",
    "version": "1.0.0",
    "mainEntity": "scienceai:scholarlyArticleId",
    "@graph": [
      {
        "@id": "scienceai:scholarlyArticleId",
        "@type": "ScholarlyArticle",
        "review": "scienceai:reviewId"
      },
      {
        "@id": "scienceai:reviewId",
        "@type": "Review"
      }
    ]
  }
}
              

When a CreateReleaseAction is performed in response of an AssessAction or a ReviewAction, the resulting snapshot (result of the CreateReleaseAction) should point to it using the isBasedOn property.

HTTP response body.

{
  "@context": "https://science.ai",
  "@id": "scienceai:createReleaseActionId",
  "@type": "CreateReleaseAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2022-12-01T22:01Z",
  "endTime": "2022-12-01T22:01Z",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": {
      "@id": "user:peter",
      "@type": "Person"
    }
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "result": {
    "@id": "scienceai:graphId?version=1.0.0",
    "@type": "Graph",
    "version": "1.0.0",
    "creator": {
      "@type": "Role",
      "roleName": "editor",
      "creator": {
        "@id": "user:peter",
        "@type": "Person"
      }
    },
    "dateCreated": "2016-06-29T19:49:22.349Z",
    "contentChecksum": {
      "@type": "Checksum",
      "checksumAlgorithm": "nash",
      "checksumValue": "nashxAqaxNgOZS4mebiZJhOlR372Iy7C3w6a1Igc45//wlo="
    },
    "mainEntity": "scienceai:scholarlyArticleId",
    "@graph": [
      {
        "@id": "scienceai:scholarlyArticleId",
        "@type": "ScholarlyArticle",
        "review": "scienceai:reviewId"
      },
      {
        "@id": "scienceai:reviewId",
        "@type": "Review"
      }
    ]
  }
}
              

AllocateAction

Allocate actions (AllocateAction) are used to capture the production parameters (url, slug, significantLink etc.) of the future WebPage representing a published version (snapshot) of the Graph.

HTTP request body.

{
  "@context": "https://science.ai",
  "@type": "AllocateAction",
  "actionStatus": "CompletedActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "producer",
    "agent": {
      "@id": "user:peter",
      "@type": "Person"
    }
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "result": {
    "@type": "WebPage",
    "slug": "a-slug-for-the-graph"
  }
}
              

The object of an AllocateAction must be a Graph.

HTTP response body.

{
  "@context": "https://science.ai",
  "@id": "scienceai:allocateActionId",
  "@type": "AllocateAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2022-12-01T22:01Z",
  "endTime": "2022-12-01T22:01Z",
  "agent": {
    "@type": "Role",
    "roleName": "producer",
    "agent": {
      "@id": "user:peter",
      "@type": "Person"
    }
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "result": {
    "@type": "WebPage",
    "slug": "a-slug-for-the-graph"
  }
}
              

ScheduleAction

Schedule actions (ScheduleAction) are used to capture the future publication date (datePublished) of the Graph.

HTTP request body.

{
  "@context": "https://science.ai",
  "@type": "ScheduleAction",
  "actionStatus": "CompletedActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "producer",
    "agent": {
      "@id": "user:peter",
      "@type": "Person"
    }
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "scheduledTime": "2016-04-05T15:38:01.946Z"
}
              

The object of a ScheduleAction must be a Graph.

HTTP response body.

{
  "@context": "https://science.ai",
  "@id": "scienceai:scheduleActionId",
  "@type": "ScheduleAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2022-12-01T22:01Z",
  "endTime": "2022-12-01T22:01Z",
  "agent": {
    "@type": "Role",
    "roleName": "producer",
    "agent": {
      "@id": "user:peter",
      "@type": "Person"
    }
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "scheduledTime": "2016-04-05T15:38:01.946Z"
}
              

PayAction

Pay actions (PayAction) are used to collect article processing charges (APC).

HTTP request body to specify article processing fees for the Graph.

{
  "@context": "https://science.ai",
  "@type": "PayAction",
  "actionStatus": "PotentialActionStatus",
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "priceSpecification": {
    "@type": "PriceSpecification",
    "price": 59,
    "priceCurrency": "USD"
  }
}
              

The object of a PayAction must be a Graph.

HTTP response body.

{
  "@context": "https://science.ai",
  "@id": "scienceai:payActionId",
  "@type": "PayAction",
  "actionStatus": "PotentialActionStatus",
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "priceSpecification": {
    "@type": "PriceSpecification",
    "price": 59,
    "priceCurrency": "USD"
  }
}
              
HTTP response body received after an agent completed the PayAction.

{
  "@context": "https://science.ai",
  "@type": "PayAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2022-12-01T22:01Z",
  "endTime": "2022-12-01T22:01Z",
  "agent": {
    "@type": "Role",
    "roleName": "author",
    "agent": {
      "@id": "user:peter",
      "@type": "Person"
    }
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "priceSpecification": {
    "@type": "PriceSpecification",
    "price": 59,
    "priceCurrency": "USD"
  }
}
              

CreateOfferAction

A CreateOfferAction is used to create commercial offers (Offer) of a Graph.

HTTP request body.

{
  "@context": "https://science.ai",
  "@type": "CreateOfferAction",
  "actionStatus": "CompletedActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "producer",
    "agent": {
      "@id": "user:peter",
      "@type": "Person"
    }
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "result": {
    "@type": "Offer",
    "priceSpecification": {
      "@type": "PriceSpecification",
      "price": 59,
      "priceCurrency": "USD"
    }
  }
}
              
HTTP response body.

{
  "@context": "https://science.ai",
  "@id": "scienceai:createOfferActionId",
  "@type": "CreateOfferAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2022-12-01T22:01Z",
  "endTime": "2022-12-01T22:01Z",
  "agent": {
    "@type": "Role",
    "roleName": "producer",
    "agent": {
      "@id": "user:peter",
      "@type": "Person"
    }
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "result": {
    "@id": "scienceai:offerId",
    "@type": "Offer",
    "priceSpecification": {
      "@type": "PriceSpecification",
      "price": 59,
      "priceCurrency": "USD"
    }
  }
}
              

Messages and Notifications

CommunicateAction

Communicate actions (CommunicateAction) are used to relay messages from one user (or Audience) (the agent) to another (the recipient).

HTTP request body.

{
  "@context": "https://science.ai",
  "@type": "CommunicateAction",
  "actionStatus": "ActiveActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": {
      "@id": "user:peter",
      "@type": "Person"
    }
  },
  "recipient": {
    "@type": "Role",
    "roleName": "reviewer",
    "recipient": {
      "@id": "user:lea",
      "@type": "Person"
    }
  },
  "object": {
    "@id": "scienceai:actionId",
    "@type": "ReviewAction"
  },
  "instrument": {
    "@type": "EmailMessage",
    "text": "A custom email body"
  }
}

              
HTTP response body.

{
  "@context": "https://science.ai",
  "@id": "scienceai:communicateActionId",
  "@type": "CommunicateAction",
  "startTime": "2022-12-01T22:01Z",
  "actionStatus": "ActiveActionStatus",
  "agent": {
    "@type": "Role",
    "roleName": "editor",
    "agent": {
      "@id": "user:peter",
      "@type": "Person"
    }
  },
  "recipient": {
    "@type": "Role",
    "roleName": "reviewer",
    "recipient": {
      "@id": "user:lea",
      "@type": "Person"
    }
  },
  "object": {
    "@id": "scienceai:actionId",
    "@type": "ReviewAction"
  },
  "instrument": {
    "@type": "EmailMessage",
    "text": "A custom email body"
  }
}
              

The actionStatus of the CommunicateAction will only be set to CompletedActionStatus once the email has been successfully sent by science.ai.

Annotations

CommentAction

Comment actions (CommentAction) provide a way for users to create comments (Comment) about a Graph, a CreativeWork, or an Action.

HTTP request body to issue a Comment about a specific part (indicated by a hasSelector) of a CreativeWork

{
  "@context": "https://science.ai",
  "@type": "CommentAction",
  "actionStatus": "CompletedActionStatus",
  "object": {
    "@type": "TargetRole",
    "object": "scienceai:graphId",
    "hasSelector": {
      "@type": "WebVerseSelector",
      "nodeId": "scienceai:encodingId",
      "webVerseKey": "HcbUid",
      "webVerseHash": "3433ded23256",
      "webVerseId": "id",
      "startOffset": 0,
      "endOffset": 10
    }
  },
  "agent": {
    "@type": "Role",
    "roleName": "user",
    "agent": {
      "@id": "user:peter",
      "@type": "Person"
    }
  },
  "resultComment": {
    "@type": "Comment",
    "text": "Interesting!"
  }
}
              

The object of the CommentAction must be a Graph, a CreativeWork, or an Action. Note that additional context can be provided with a TargetRole (see selectors).

HTTP response body.

{
  "@context": "https://science.ai",
  "@id": "scienceai:commentActionId",
  "@type": "CommentAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2022-12-01T22:01Z",
  "endTime": "2022-12-01T22:01Z",
  "object": {
    "@type": "TargetRole",
    "object": "scienceai:graphId",
    "hasSelector": {
      "@type": "WebVerseSelector",
      "nodeId": "scienceai:encodingId",
      "webVerseKey": "HcbUid",
      "webVerseHash": "3433ded23256",
      "webVerseId": "id",
      "startOffset": 0,
      "endOffset": 10
    }
  },
  "agent": {
    "@type": "Role",
    "roleName": "user",
    "agent": {
      "@id": "user:peter",
      "@type": "Person"
    }
  },
  "resultComment": {
    "@id": "scienceai:commentId",
    "@type": "Comment",
    "about": {
      "@type": "TargetRole",
      "about": "scienceai:creativeWorkId",
      "hasSelector": {
        "@type": "WebVerse",
        "webVerseKey": "HcbUid",
        "webVerseHash": "3433ded23256",
        "webVerseId": "id",
        "encoding": "scienceai:encodingId",
        "startOffset": 0,
        "endOffset": 10
      }
    },
    "text": "Interesting!",
    "dateCreated": "2022-12-02T22:01Z"
  }
}
              

TagAction

Tag actions (TagAction) are used to tag / classify an object (or part of an object).

HTTP request body

{
  "@context": "https://science.ai",
  "@type": "TagAction",
  "agent": {
    "@type": "Role",
    "agent": "user:peter",
    "roleName": "editor"
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "result": {
    "@type": "Tag",
    "name": "A tag"
  }
}
              

The object of a TagAction must be a Graph or a CreativeWork.

HTTP response body

{
  "@context": "https://science.ai",
  "@id": "scienceai:tagActionId",
  "@type": "TagAction",
  "actionStatus": "CompletedActionStatus",
  "startTime": "2022-12-01T22:01Z",
  "endTime": "2022-12-03T22:01Z",
  "agent": {
    "@type": "Role",
    "agent": "user:peter",
    "roleName": "editor"
  },
  "object": {
    "@id": "scienceai:graphId",
    "@type": "Graph"
  },
  "result": {
    "@id": "scienceai:tagId",
    "@type": "Tag",
    "name": "A tag"
  }
}
              

Event reference

PublicationEvent

Publication Events (PublicationEvent) are used to announce the publication of creative works.

Example of a Publication Event.

{
  "@context": "https://sciencea.ai",
  "@id": "scienceai:eventId",
  "@type": "PublicationEvent",
  "startDate": "2022-12-01T22:01Z",
  "endDate": "2022-12-01T22:01Z",
  "workFeatured": {
    "@type": "Dataset",
    "name": "dataset",
    "description": "abstract",
    "isPartOf": {
      "@id": "scienceai:journalId",
      "@type": "Periodical",
      "name": "Journal of hypertext"
    },
    "author": {
      "@id": "user:ted",
      "@type": "Person",
      "name": "Ted Nelson"
    }
  },
  "recordedIn": "scienceai:graphId"
}
            

ProgressEvent

Progress Events (ProgressEvent) are used to provide information about the progress status of an ongoing action.

Example of a Progress Event.

{
  "@context": "https://science.ai",
   "@type": "ProgressEvent",
   "superEvent": "scienceai:subEventId1",
   "startDate": "2020-01-01T21:05:20.262Z",
   "endDate": "2020-01-01T21:05:20.262Z",
   "progress": {
     "@type": "QuantitativeValue",
     "minValue": 0,
     "maxValue": 100,
     "value": 10
   }
}