SHARE.md

Suppose we want to insert the following data into SHARE:

All About Muffins (https://osf.io/juwia/)

This paper is about muffins.

about, muffins

Once all is said and done, the tables in SHARE will look like:

Note: The ids are arbitrary

CreativeWorks

id	Title	Description	is_deleted
12	All About Muffins	This paper is about muffins	FALSE

Work Identifiers

id	URI	creativework_id
47	https://osf.io/juwia/	12

Tags

id	title
1	muffins
2	about

Through Tags

id	creativework_id	tag_id
94	12	1
95	12	2

Our Payload

Note:

The following examples are in javascript for read-ability and comments.

This would be the content of the second data key, as noted in the API docs.

{
  "@graph": [{
      // This ID doesn't matter. It is only used to refer back to this
      // Node within the scope of this graph
      // See "Blank Nodes" in the JSON-LD spec
      "@id": "_:tmp_id_creativework_1",
      // @type is used to by SHARE
      // to validate the contents of this node
      // and validate any references made to other nodes
      "@type": "CreativeWork",

      // Attributes we'd like to set
      title: "All About Muffins",
      description: "This paper is about muffins",

      // Any attribute may be omitted and a default value will be set for it
      // Keep in mind, if title is omitted the work will not be inserted into SHARE's Elasticsearch index
      // is_deleted: false,

      // As a many to many relation you may optionally include "tags"
      // This field is for human read-abilty only and is discarded when actually being processed by SHARE
      // "tags": [
      //     {"@id": "_:tmp_id_throughtags_1", "@type": "throughtags"},
      //     {"@id": "_:tmp_id_throughtags_2", "@type": "throughtags"}
      // ]
  }, {
      "@id": "_:tmp_id_workidentifier_1",
      "@type": "workidentifier",

      // Our unique identifier
      uri: "https://osf.io/juwia/",

      // As a many to one relation, there is no need for a through table here
      // We just reference the work directly
      //
      // Anything that would be a foreign field is expressed as a JSON-LD reference with the addition of "@type"
      // For additional uniqueness and ease of validation
      //
      // For instance if we decided to reference a tag here, our graph would be rejected
      // creative_work: { "@id": "_:tmp_id_tag_1", "@type": "tag" }
      creative_work: { "@id": "_:tmp_id_creativework_1", "@type": "CreativeWork" }
  }, {
      "@id": "_:tmp_id_thoughtags_1",
      "@type": "throughtags"

      // Throughtags are what serve as the actual link between the work and tag
      // If we just wanted to create a tag without attaching it to anything, we'd simply omit this node
      tag: { "@id": "_:tmp_id_tag_1", "@type": "tag" },
      creativework: { "@id": "_:tmp_id_creativework_1", "@type": "CreativeWork" },
  }, {
      // Same as above
      "@id": "_:tmp_id_thoughtags_2",
      "@type": "throughtags",

      // Supposing we'd like to reference a tag that already exists and we know the id of it
      // We could reference it using the SHARE ID rather than including it as a node
      // { "@id": "AB123-ABC-ABC", "@type": "tag" }
      tag: { "@id": "_:tmp_id_tag_2", "@type": "tag" },
      creativework: { "@id": "_:tmp_id_creativework_1", "@type": "CreativeWork" }
  }, {
      "@id": "_:tmp_id_tag_1",
      "@type": "tag",

      // All graph nodes are run through some form of disambiguation
      // If the tag "about" already exists in the SHARE database the system would automatically replace all
      // references to this node to reference to the existing tag
      // This also help prevent tagging the same working with the same tag multiple times
      // as throughtags nodes are also disambiguated
      title: "about",
  }, {
      "@id": "_:tmp_id_tag_2",
      "@type": "tag",

      // Just making another tag
      title: "muffins"
}]

Now let's say we want to remove our paper from SHARE. This is done by setting the is_deleted flag, which we can do in two different ways.

If we know the SHARE ID of our paper we can reference it directly

{
  "@graph": [{
      "@id": "AB123-DEF-456",
      "@type": "CreativeWork",

      is_deleted: true
  }]
}

Or if we don't know the ID and just need to provide SHARE a way to figure out what paper we're talking about, by providing a unique identifier

{
  "@graph": [{
      "@id": "_:doesnt_matter",
      "@type": "CreativeWork",

      is_deleted: true
  }, {
    "@id": "_:also_doesnt_matter",
    "@type": "WorkIdentifier",

    // Here's the important bit. SHARE will use this identifier
    // to figure out what paper we're actually referencing
    uri: "https://osf.io/juwia/"
    creative_work: { "@id": "_:doesnt_matter", "@type": "CreativeWork" }
  }]
}