Java
Create a Nanopublication
Prerequisite for creating/publishing
To create and publish nanopublications, you need to first make sure you have a local keypair. To create such a keypair, run just once:
NanopubCreator npCreator = new NanopubCreator(true);
final ValueFactory vf = SimpleValueFactory.getInstance();
final IRI anne = vf.createIRI("https://example.com/anne");
npCreator.addAssertionStatement(anne, RDF.TYPE, vf.createIRI("https://schema.org/Person"));
npCreator.addProvenanceStatement(PROV.WAS_ATTRIBUTED_TO, anne);
npCreator.addPubinfoStatement(RDF.TYPE, vf.createIRI("http://purl.org/nanopub/x/ExampleNanopub"));
Nanopub np = npCreator.finalizeNanopub(true);
Sign a Nanopublication
Prerequisite for signing/publishing
Before you can sign and publish you should setup your profile, check if it is properly set by running np profile in your terminal.
Publish a Nanopublication
Prerequisite for creating/publishing
To create and publish nanopublications, you need to first make sure you have a local keypair. To create such a keypair, run just once:
Publish to the Test Server
Publish to the Production Server
Verification of unpublished Nanopublications
Besides strict syntactical requirements a nanopub has to fulfill to be published there are a bunch of best practices, which should be honored. With the command line tool you can use
to see a list of issues. To ensure you only publish nanopubs that meet all best practices
use the flag --strict when publishing:
In the java API you can use
Best Practices
The best practices that are verified are the following:
- The creation timestamp of the nanopub is not in the future and not older than one hour.
- The nanopub has a label.
- The nanopub has a type.
- The nanopub uses an assertion template and a provenance template.
- The nanopub has a signer and the signer is also a creator of the nanopub.
- The nanopub contains the graph uris: …Head, …assertion, …provenance, and …pubinfo.
- The nanopub consists of below than 1200 triples and is smaller than 10MB.
Reading a Template
A template is a nanopublication that describes how nanopublications of a certain kind are
structured: the statements they consist of, the placeholders to be filled in, and the
constraints on the values. Template reads one:
// Fetches the template nanopublication from the network:
Template template = new Template("https://w3id.org/np/RAEzjboN_ipuwsFnvhqAl9Fy7fZl34cGZ1QhJ-7cbbGGM");
// Or from a nanopublication at hand, such as a file that is not published yet:
Template template = new Template(new NanopubImpl(new File("my-template.trig")));
for (IRI statement : template.getStatementIris()) {
IRI subject = template.getSubject(statement);
IRI predicate = template.getPredicate(statement);
Value object = template.getObject(statement);
boolean optional = template.isOptionalStatement(statement);
if (object instanceof IRI placeholder && template.isPlaceholder(placeholder)) {
String label = template.getLabel(placeholder);
String regex = template.getRegex(placeholder); // null if unconstrained
boolean isLiteral = template.isLiteralPlaceholder(placeholder);
}
}
A grouped statement is one entry of getStatementIris(), and getStatementIris(group)
lists its members. getStatementErrors() reports statements that cannot produce valid
nanopublications.
Reading a template needs no network access. Only the possible values of a restricted-choice
placeholder that are kept in another nanopublication (nt:possibleValuesFrom) are fetched,
when getPossibleValues(placeholder) is first called. Pass a NanopubResolver to decide
where nanopublications come from, or NanopubResolver.NONE to never fetch any:
getDescription() and getStatementDescription(statement) return the text as published.
It may contain HTML and is not sanitized.
Checking a Nanopublication against its Templates
A nanopublication names the templates it was made from in its publication info.
TemplateComplianceChecker retrieves them and checks whether the nanopublication is what filling
them in would give:
TemplateComplianceChecker checker = new TemplateComplianceChecker();
ComplianceReport report = checker.check(nanopub);
if (!report.isCompliant()) {
for (ComplianceIssue issue : report.getErrors()) {
System.out.println(issue.graph() + ": " + issue.message());
}
}
An error is, for instance, a statement of a template that is not optional and has no triples, a
triple of the assertion that belongs to no statement, or a value that breaks a constraint of its
placeholder. report.getWarnings() has what does not keep the nanopublication from complying,
such as a triple of the publication info that no template has a statement for. A checker keeps
the templates it has retrieved, so use one for many nanopublications.
The classes underneath can be used on their own. TemplateMatcher assigns the triples of one
graph to the statements of one template, PlaceholderMatcher checks a single value against a
placeholder, and BindingContext holds the values bound:
BindingContext context = BindingContext.forNanopub(template, nanopub);
TemplateMatch match = new TemplateMatcher(template).match(nanopub.getAssertion(), context);
match.getMissingStatements(); // statements that are not optional and have no triples
match.getUnusedTriples(); // triples that belong to no statement
match.getViolations(); // values that break a constraint
Value name = context.get(placeholderIri);
Filling a Template
TemplateFiller makes a nanopublication from templates and the values of their placeholders, as
the publishing form of Nanodash does. A FillRequest names the templates and gives the values,
each under the name of its placeholder:
FillRequest request = new FillRequest("https://w3id.org/np/RAEFAt-QcFK0ZhqfvlsmS10BnzGJA0xwOICZXkO-ai87k")
.set("query", "get-things")
.set("title", "Get things")
.set("description", "Returns three things.")
.set("endpoint", "https://w3id.org/np/l/nanopub-query-1.1/repo/full")
.set("license", "http://www.apache.org/licenses/LICENSE-2.0")
.set("sparql", "select * where { ?s ?p ?o } limit 3")
.setCreator(creatorIri);
try {
Nanopub nanopub = new TemplateFiller().fill(request); // not signed
} catch (TemplateFillException ex) {
ex.getProblems().forEach(System.out::println);
}
The nanopublication gets the template links, the introduced and embedded resources, the types and the label that the form would give it. Its provenance and publication info are made from the templates the request names, and otherwise from the default provenance template of the assertion template, or “Attributed to myself/others”, and from the templates for the creator and the license.
A value is written as it would be typed into the form: an IRI in full, a name that is minted
within the nanopublication, or the text of a literal. A statement that is repeated takes the
values name, name__1, name__2 and so on; request.getValues().add("name", "...") gives the
next one. Nothing is made if something is wrong: TemplateFillException lists all values that are
missing or break a constraint, all names no placeholder answers to, and all values that would be
lost because the statement they belong to is left out.
A request has the parameters of a link to the publishing form of Nanodash, and is read from and
written as one with FillRequest.fromUrl, fromJson, toQueryString and toJson.
To make a new version of a nanopublication, read its request back, change it, and say what the new nanopublication is to the old one:
ComplianceReport report = new TemplateComplianceChecker().check(published);
FillRequest request = FillRequest.of(report)
.set("title", "Get three things")
.setSource(FillRequest.Mode.SUPERSEDE, published.getUri().stringValue());
Nanopub newVersion = new TemplateFiller().fill(request);
With SUPERSEDE and OVERRIDE the resources the old nanopublication introduces keep their IRIs
and the root definition stays; with DERIVE everything is minted anew. The request that is read
back does not have the link the nanopublication itself has to an earlier version. Read it only
from a nanopublication that complies with its templates (report.isCompliant()), as content the
templates do not account for is not in it.