Step 1. Add the JitPack repository to your build file
Add it in your root build.gradle at the end of repositories:
allprojects {
repositories {
...
maven { url 'https://jitpack.io' }
}
}
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
Add it in your build.sbt at the end of resolvers:
resolvers += "jitpack" at "https://jitpack.io"
Add it in your project.clj at the end of repositories:
:repositories [["jitpack" "https://jitpack.io"]]
Step 2. Add the dependency
dependencies {
implementation 'com.github.jsonld-java:jsonld-java:0.13.4'
}
<dependency>
<groupId>com.github.jsonld-java</groupId>
<artifactId>jsonld-java</artifactId>
<version>0.13.4</version>
</dependency>
libraryDependencies += "com.github.jsonld-java" % "jsonld-java" % "0.13.4"
:dependencies [[com.github.jsonld-java/jsonld-java "0.13.4"]]
JSONLD-Java is looking for a maintainer
This is a Java implementation of the JSON-LD 1.0 specification and the JSON-LD-API 1.0 specification.
<dependency>
<groupId>com.github.jsonld-java</groupId>
<artifactId>jsonld-java</artifactId>
<version>0.13.4</version>
</dependency>
// Open a valid json(-ld) input file
InputStream inputStream = new FileInputStream("input.json");
// Read the file into an Object (The type of this object will be a List, Map, String, Boolean,
// Number or null depending on the root object in the file).
Object jsonObject = JsonUtils.fromInputStream(inputStream);
// Create a context JSON map containing prefixes and definitions
Map context = new HashMap();
// Customise context...
// Create an instance of JsonLdOptions with the standard JSON-LD options
JsonLdOptions options = new JsonLdOptions();
// Customise options...
// Call whichever JSONLD function you want! (e.g. compact)
Object compact = JsonLdProcessor.compact(jsonObject, context, options);
// Print out the result (or don't, it's your call!)
System.out.println(JsonUtils.toPrettyString(compact));
The Options specified by the JSON-LD API Specification are accessible via the com.github.jsonldjava.core.JsonLdOptions
class, and each JsonLdProcessor.*
function has an optional input to take an instance of this class.
Parsing JSON-LD will normally follow any external @context
declarations.
Loading these contexts from the network may in some cases not be desirable, or
might require additional proxy configuration or authentication.
JSONLD-Java uses the Apache HTTPComponents Client for these network connections,
based on the SystemDefaultHttpClient which reads
standard Java properties like http.proxyHost
.
The default HTTP Client is wrapped with a CachingHttpClient to provide a small memory-based cache (1000 objects, max 128 kB each) of regularly accessed contexts.
Your application might be parsing JSONLD documents which always use the same
external @context
IRIs. Although the default HTTP cache (see above) will
avoid repeated downloading of the same contexts, your application would still
initially be vulnerable to network connectivity.
To bypass this issue, and even facilitate parsing of such documents in an offline state, it is possible to provide a 'warmed' cache populated from the classpath, e.g. loaded from a JAR.
In your application, simply add a resource jarcache.json
to the root of your
classpath together with the JSON-LD contexts to embed. (Note that you might
have to recursively embed any nested contexts).
The syntax of jarcache.json
is best explained by example:
[
{
"Content-Location": "http://www.example.com/context",
"X-Classpath": "contexts/example.jsonld",
"Content-Type": "application/ld+json"
},
{
"Content-Location": "http://data.example.net/other",
"X-Classpath": "contexts/other.jsonld",
"Content-Type": "application/ld+json"
}
]
(See also core/src/test/resources/jarcache.json).
This will mean that any JSON-LD document trying to import the @context
http://www.example.com/context
will instead be given
contexts/example.jsonld
loaded as a classpath resource.
The X-Classpath
location is an IRI reference resolved relative to the
location of the jarcache.json
- so if you have multiple JARs with a
jarcache.json
each, then the X-Classpath
will be resolved within the
corresponding JAR (minimizing any conflicts).
Additional HTTP headers (such as Content-Type
above) can be included,
although these are generally ignored by JSONLD-Java.
Unless overridden in jarcache.json
, this Cache-Control
header is
automatically injected together with the current Date
, meaning that the
resource loaded from the JAR will effectively never expire (the real HTTP
server will never be consulted by the Apache HTTP client):
Date: Wed, 19 Mar 2014 13:25:08 GMT
Cache-Control: max-age=2147483647
The mechanism for loading jarcache.json
relies on
Thread.currentThread().getContextClassLoader()
to locate resources from the classpath - if you are running on a command line,
within a framework (e.g. OSGi) or Servlet container (e.g. Tomcat) this should
normally be set correctly. If not, try:
ClassLoader oldContextCL = Thread.currentThread().getContextClassLoader();
try {
Thread.currentThread().setContextClassLoader(getClass().getClassLoader());
JsonLdProcessor.expand(input); // or any other JsonLd operation
} finally {
// Restore, in case the current thread was doing something else
// with the context classloader before calling our method
Thread.currentThread().setContextClassLoader(oldContextCL);
}
To disable all remote document fetching, when using the default DocumentLoader, set the following Java System Property to "true" using:
System.setProperty("com.github.jsonldjava.disallowRemoteContextLoading", "true");
You can also use the constant provided in DocumentLoader for the same purpose:
System.setProperty(DocumentLoader.DISALLOW_REMOTE_CONTEXT_LOADING, "true");
Note that if you override DocumentLoader you should also support this setting for consistency and security.
Your application might be parsing JSONLD documents which reference external @context
IRIs
that are not available as file URIs on the classpath. In this case, the jarcache.json
approach will not work. Instead you can inject the literal context file strings through
the JsonLdOptions
object, as follows:
// Inject a context document into the options as a literal string
DocumentLoader dl = new DocumentLoader();
JsonLdOptions options = new JsonLdOptions();
// ... the contents of "contexts/example.jsonld"
String jsonContext = "{ \"@context\": { ... } }";
dl.addInjectedDoc("http://www.example.com/context", jsonContext);
options.setDocumentLoader(dl);
InputStream inputStream = new FileInputStream("input.json");
Object jsonObject = JsonUtils.fromInputStream(inputStream);
Map context = new HashMap();
Object compact = JsonLdProcessor.compact(jsonObject, context, options);
System.out.println(JsonUtils.toPrettyString(compact));
To customize the HTTP behaviour (e.g. to disable the cache or provide
authentication
credentials),
you may want to create and configure your own CloseableHttpClient
instance, which can
be passed to a DocumentLoader
instance using setHttpClient()
. This document
loader can then be inserted into JsonLdOptions
using setDocumentLoader()
and passed as an argument to JsonLdProcessor
arguments.
Example of inserting a credential provider (e.g. to load a @context
protected
by HTTP Basic Auth):
Object input = JsonUtils.fromInputStream(..);
DocumentLoader documentLoader = new DocumentLoader();
CredentialsProvider credsProvider = new BasicCredentialsProvider();
credsProvider.setCredentials(
new AuthScope("localhost", 443),
new UsernamePasswordCredentials("username", "password"));
CacheConfig cacheConfig = CacheConfig.custom().setMaxCacheEntries(1000)
.setMaxObjectSize(1024 * 128).build();
CloseableHttpClient httpClient = CachingHttpClientBuilder
.create()
// allow caching
.setCacheConfig(cacheConfig)
// Wrap the local JarCacheStorage around a BasicHttpCacheStorage
.setHttpCacheStorage(
new JarCacheStorage(null, cacheConfig, new BasicHttpCacheStorage(
cacheConfig)))....
// Add in the credentials provider
.setDefaultCredentialsProvider(credsProvider);
// When you are finished setting the properties, call build
.build();
documentLoader.setHttpClient(httpClient);
JsonLdOptions options = new JsonLdOptions();
options.setDocumentLoader(documentLoader);
// .. and any other options
Object rdf = JsonLdProcessor.toRDF(input, options);
The jsonld-java-tools repository contains a simple application which provides command line access to JSON-LD functions
git clone git@github.com:jsonld-java/jsonld-java-tools.git
chmod +x ./jsonldplayground
run the following to get usage details:
./jsonldplayground --help
jsonld-java
uses maven to compile. From the base jsonld-java
module run mvn clean install
to install the jar into your local maven repository.
mvn test
or
mvn test -pl core
to run only core package tests
The JSONLD-Java project uses custom Eclipse formatting and cleanup style guides to ensure that Pull Requests are fairly simple to merge.
These guides can be found in the /conf directory and can be installed in Eclipse using "Properties>Java Code Style>Formatter", followed by "Properties>Java Code Style>Clean Up" for each of the modules making up the JSONLD-Java project.
If you don't use Eclipse, then don't worry, your pull requests can be cleaned up by a repository maintainer prior to merging, but it makes the initial check easier if the modified code uses the conventions.
Once you have made a change to fix a bug or add a new feature, you should commit and push the change to your fork.
Then, you can open a pull request to merge your change into the master branch of the main repository.
The Implementation Reports documenting the conformance of JSONLD-Java with JSONLD-1.0 are available at:
https://github.com/jsonld-java/jsonld-java/tree/master/core/reports
Implementation Reports conforming to the JSON-LD Implementation Report document can be regenerated using the following command:
mvn test -pl core -Dtest=JsonLdProcessorTest -Dreport.format=<format>
Current possible values for <format>
include JSON-LD (application/ld+json
or jsonld
), NQuads (text/plain
, nquads
, ntriples
, nq
or nt
) and Turtle (text/turtle
, turtle
or ttl
). *
can be used to generate reports in all available formats.
This is the base package for JSONLD-Java. Integration with other Java packages are done in separate repositories.
Create a GitHub repository for your module under your user account, or have a JSONLD-Java maintainer create one in the jsonld-java organisation.
Here is the basic outline for what your module's pom.xml should look like
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<parent>
<groupId>com.github.jsonld-java</groupId>
<artifactId>jsonld-java-parent</artifactId>
<version>0.13.4</version>
</parent>
<modelVersion>4.0.0</modelVersion>
<artifactId>jsonld-java-{your module}</artifactId>
<version>0.13.4-SNAPSHOT</version>
<name>JSONLD Java :: {your module name}</name>
<description>JSON-LD Java integration module for {RDF Library your module integrates}</description>
<packaging>jar</packaging>
<developers>
<developer>
<name>{YOU}</name>
<email>{YOUR EMAIL ADDRESS}</email>
</developer>
</developers>
<dependencies>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>jsonld-java</artifactId>
<version>${project.version}</version>
<type>jar</type>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>${project.groupId}</groupId>
<artifactId>jsonld-java</artifactId>
<version>${project.version}</version>
<type>test-jar</type>
<scope>test</scope>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-jdk14</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
</project>
Make sure you edit the following:
project/artifactId
: set this to jsonld-java-{module id}
, where {module id}
usually represents the RDF library you're integrating (e.g. jsonld-java-jena
)project/name
: set this to JSONLD Java :: {Module Name}
, wher {module name}
is usually the name of the RDF library you're integrating.project/description
project/developers/developer/...
: Give youself credit by filling in the developer field. At least put your <name>
in (see here for all available options).project/dependencies/...
: remember to add any dependencies your project needsFor Example: Follow the first few steps in the section above to import the whole jsonld-java
project or only your new module into eclipse.
The interface com.github.jsonldjava.core.RDFParser
is used to parse RDF from the library into the JSONLD-Java internal RDF format. See the documentation in RDFParser.java
for details on how to implement this interface.
The interface com.github.jsonldjava.core.JSONLDTripleCallback
is used to generate a representation of the JSON-LD input in the RDF library. See the documentation in JSONLDTripleCallback.java
for details on how to implement this interface.
A JSONLD RDF parser is a class that can parse your frameworks' RDF model and generate JSON-LD.
There are two ways to use your RDFParser
implementation.
Register your parser with the JSONLD
class and set options.format
when you call fromRDF
JSONLD.registerRDFParser("format/identifier", new YourRDFParser());
Object jsonld = JSONLD.fromRDF(yourInput, new Options("") {{ format = "format/identifier" }});
or pass an instance of your RDFParser
into the fromRDF
function
Object jsonld = JSONLD.fromRDF(yourInput, new YourRDFParser());
A JSONLD triple callback is a class that can populate your framework's RDF model from JSON-LD - being called for each triple (technically quad).
Pass an instance of your TripleCallback
to JSONLD.toRDF
Object yourOutput = JSONLD.toRDF(jsonld, new YourTripleCallback());
Your framework might have its own system of readers and writers, where you should register JSON-LD as a supported format. Remember that here the "parse" direction is opposite of above, a 'reader' may be a class that can parse JSON-LD and populate an RDF Graph.
It's helpful to have a test or two for your implementations to make sure they work and continue to work with future versions.
Write a README.md
file with instrutions on how to use your module.
Once you've commit
ted your code, and push
ed it into your github fork you can issue a Pull Request so that we can add a reference to your module in this README file.
Alternatively, we can also host your repository in the jsonld-java organisation to give it more visibility.
Cache-Control: private
(Patch by @HansBrende)JSONLDException
to JsonLdError
JSONLDProcessor
to JsonLdApi
JSONLD
to JsonLdProcessor
ActiveContext
to Context
Options
to JsonLdOptions
Context
classcom.github.jsonld-java
to match github domain.Context
class is a Map
and many of the options are stored as values of the map. These could be made into variables, whice should speed things up a bit (the same with the termDefinitions variable inside the Context).