HOWTO Write and publish a Nanopublication

What is a nanopublication?

This is an α version

I am presently working on this article, and it is a very early alpha version. If you happen to read it before I am finished, please forgive the sketchiness. You are very welcome to contribute and to criticize though! Just ➕ open an issue on GitHub.

I have been working on a thing called YAML-LD, and I want to tell the world what it is. I like infographics, so I might draw the following Mermaid diagram.

graph LR
    yaml-ld("YAML-LD") --- rdf-type(("is a")) ---> knowledge-representation-language("Knowledge Representation Language")
    click yaml-ld "https://json-ld.github.io/yaml-ld/spec/"
    click knowledge-representation-language "https://w3id.org/fair/fip/terms/Knowledge-representation-language"
    click rdf-type "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"

    yaml-ld --- rdfs-label(("label")) ---> label[["YAML-LD"]]
    click rdfs-label "http://www.w3.org/2000/01/rdf-schema#"

    classDef predicate fill:none,stroke:none,stroke-width:0px;
    class rdfs-label predicate
    class rdf-type predicate

This graph obviously says that:

• YAML-LD is named "YAML-LD"
  (well that was unexpected),
• and it is a knowledge representation language,
  whatever that might be.

It does not concern us very much what these are. In your case, you might wish to inform the world about any other fact, like:

• Mosquitoes bite humans,
• TRAPPIST-1 system has 7 planets,
• Pluto is not a planet,
• or even that,
  • even though John Doe says that every dinosaur is a reptile,
  • that statement is false,
    • because
      • Chicken is a dinosaur
      • Chicken is a bird, not a reptile.

All of these statements can be drawn as graphs similar to the above. Let's do so.

Install prerequisites

In a Python 3.10+ environment, run:

pip install iolanta git+https://github.com/iolanta-tech/nanopub-py.git

Write an Assertion

Create a new file, called yaml-ld.yamlld, and run, in a separate terminal:

iolanta yaml-ld.yamlld

yaml-ld.yamlld

# This file is empty so far ∅

As you can see on the right, Iolanta has certain difficulties visualizing this document. Well, that's because there is nothing to visualize. The line starting from # is a comment in YAML, it is only written for a human reader; computer ignores it entirely.

Step

We are going to write something about YAML-LD; let's refer to it properly: as a URL. We can use the address of the current YAML-LD specification draft.

yaml-ld.yamlld

"@id": https://json-ld.github.io/yaml-ld/spec/

Here, @id is a keyword that identifies the thing we are going to talk about.

Info

"@id" has to be in quotes, this is because @ is a reserved character in YAML. More on that later.

However... Iolanta still cannot visualize this document, why is this?

Step

Ahem. Yes, indeed, I am sorry. The problem now is that the graph we have described only has one node, but no edges.

graph TD
    yaml-ld("https://json-ld.github.io/yaml-ld/spec/")

    click yaml-ld https://json-ld.github.io/yaml-ld/spec/

This degenerated form is not really a graph and is not quite supported by Iolanta, unfortunately. We need to say something about the thing that we had stated. Otherwise there's no semantics to talk about, no knowledge to express. Let's do that.

yaml-ld.yamlld

"@id": https://json-ld.github.io/yaml-ld/spec/
"http://www.w3.org/2000/01/rdf-schema#label": YAML-LD

And it works!

This display shows what is called a triple. Here,

• YAML-LD (red) is the subject,
• label is the predicate,
• and YAML-LD (black) is the object.

Subject and Predicate here are clickable, since they are URLs. Object is a string, or a Literal, and is therefore not clickable.

YAML-LD subject

Label predicate

As you can see, quite a bit of information is available about each. That's because files accessible via each of those URLs contain information about the concepts the URLs stand for.

That's called Linked Data.

Step

You will rightfully exclaim:

Exclamation © you

Are you saying I will have to type

http://www.w3.org/2000/01/rdf-schema#label

each time I want to specify a human readable label of something?

No, not really. Let's define a context.

yaml-ld.yamlld

"@context":
  rdfs: http://www.w3.org/2000/01/rdf-schema#

"@id": https://json-ld.github.io/yaml-ld/spec/
rdfs:label: YAML-LD

Context is the part of the document where we describe how to interpret this document as a Knowledge Graph. In this example, we introduce a shortcut, rdfs, which stands for RDFS ontology. In the body of the document we can refer to that ontology using that shorthand.

Short form (CURIE)	Full Form
rdfs:label	http://www.w3.org/2000/01/rdf-schema#label
rdfs:seeAlso	http://www.w3.org/2000/01/rdf-schema#seeAlso
rdfs:Class	http://www.w3.org/2000/01/rdf-schema#Class

Step

Let's reduce our typing effort a bit more.

yaml-ld.yamlld

"@context":
  "@import": https://json-ld.org/contexts/dollar-convenience.jsonld
  rdfs: http://www.w3.org/2000/01/rdf-schema#

$id: https://json-ld.github.io/yaml-ld/spec/
rdfs:label: YAML-LD

We import a context which remaps @id to $id, which does not have to be quoted. Cool, right?!

Draw the owl!

With the examples we've looked through, you will easily read the following YAML-LD statement.

yaml-ld.yamlld

"@context":
  "@import": https://json-ld.org/contexts/dollar-convenience.jsonld
  dc: http://purl.org/dc/terms/
  rdfs: http://www.w3.org/2000/01/rdf-schema#
  fip: https://w3id.org/fair/fip/terms/

$id: https://json-ld.github.io/yaml-ld/spec/
$type: fip:Knowledge-representation-language
dc:description: |
  A set of conventions built on top of YAML, which outlines how to serialize
  Linked Data as YAML based on JSON-LD syntax, semantics, and APIs.
rdfs:label: YAML-LD

At any rate, Iolanta is always ready to help by visualizing it. Each of the links is clickable, leading you to further information about the concepts involved.

Make it a valid Nanopublication

pyld expand yaml-ld.yamlld | np create --output-format json-ld from-assertion --input-format json-ld > np.yaml-ld.jsonld

Publish!

np publish np.yaml-ld.trig