Repository files navigation

This is a Java implementation of theJSON-LD 1.0 specification and theJSON-LD-API 1.0 specification.

<dependency>    <groupId>com.github.jsonld-java</groupId>    <artifactId>jsonld-java</artifactId>    <version>0.13.5</version></dependency>

// Open a valid json(-ld) input fileInputStreaminputStream =newFileInputStream("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).ObjectjsonObject =JsonUtils.fromInputStream(inputStream);// Create a context JSON map containing prefixes and definitionsMapcontext =newHashMap();// Customise context...// Create an instance of JsonLdOptions with the standard JSON-LD optionsJsonLdOptionsoptions =newJsonLdOptions();// Customise options...// Call whichever JSONLD function you want! (e.g. compact)Objectcompact =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 theJSON-LD API Specification are accessible via thecom.github.jsonldjava.core.JsonLdOptions class, and eachJsonLdProcessor.* 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, ormight require additional proxy configuration or authentication.

JSONLD-Java uses theApache HTTPComponents Client for these network connections,based on theSystemDefaultHttpClient which readsstandard Java properties likehttp.proxyHost.

The default HTTP Client is wrapped with aCachingHttpClient to provide asmall memory-based cache (1000 objects, max 128 kB each) of regularly accessed contexts.

Your application might be parsing JSONLD documents which always use the sameexternal@context IRIs. Although the default HTTP cache (see above) willavoid repeated downloading of the same contexts, your application would stillinitially be vulnerable to network connectivity.

To bypass this issue, and even facilitate parsing of such documents in anoffline state, it is possible to provide a 'warmed' cache populatedfrom the classpath, e.g. loaded from a JAR.

In your application, simply add a resourcejarcache.json to the root of yourclasspath together with the JSON-LD contexts to embed. (Note that you mighthave to recursively embed any nested contexts).

The syntax ofjarcache.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 alsocore/src/test/resources/jarcache.json).

This will mean that any JSON-LD document trying to import the@contexthttp://www.example.com/context will instead be givencontexts/example.jsonld loaded as a classpath resource.

TheX-Classpath location is an IRI reference resolved relative to thelocation of thejarcache.json - so if you have multiple JARs with ajarcache.json each, then theX-Classpath will be resolved within thecorresponding JAR (minimizing any conflicts).

Additional HTTP headers (such asContent-Type above) can be included,although these are generally ignored by JSONLD-Java.

Unless overridden injarcache.json, thisCache-Control header isautomatically injected together with the currentDate, meaning that theresource loaded from the JAR will effectively never expire (the real HTTPserver will never be consulted by the Apache HTTP client):

Date: Wed, 19 Mar 2014 13:25:08 GMTCache-Control: max-age=2147483647

The mechanism for loadingjarcache.json relies onThread.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 shouldnormally be set correctly. If not, try:

ClassLoaderoldContextCL =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 methodThread.currentThread().setContextClassLoader(oldContextCL);}

To disable all remote document fetching, when using the default DocumentLoader, set thefollowing 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 IRIsthat are not available as file URIs on the classpath. In this case, thejarcache.jsonapproach will not work. Instead you can inject the literal context file strings throughtheJsonLdOptions object, as follows:

// Inject a context document into the options as a literal stringDocumentLoaderdl =newDocumentLoader();JsonLdOptionsoptions =newJsonLdOptions();// ... the contents of "contexts/example.jsonld"StringjsonContext ="{\"@context\": { ... } }";dl.addInjectedDoc("http://www.example.com/context",jsonContext);options.setDocumentLoader(dl);InputStreaminputStream =newFileInputStream("input.json");ObjectjsonObject =JsonUtils.fromInputStream(inputStream);Mapcontext =newHashMap();Objectcompact =JsonLdProcessor.compact(jsonObject,context,options);System.out.println(JsonUtils.toPrettyString(compact));

To customize the HTTP behaviour (e.g. to disable the cache or provideauthenticationcredentials),you may want to create and configure your ownCloseableHttpClient instance, which canbe passed to aDocumentLoader instance usingsetHttpClient(). This documentloader can then be inserted intoJsonLdOptions usingsetDocumentLoader()and passed as an argument toJsonLdProcessor arguments.

Example of inserting a credential provider (e.g. to load a@context protectedby HTTP Basic Auth):

Objectinput =JsonUtils.fromInputStream(..);DocumentLoaderdocumentLoader =newDocumentLoader();CredentialsProvidercredsProvider =newBasicCredentialsProvider();credsProvider.setCredentials(newAuthScope("localhost",443),newUsernamePasswordCredentials("username","password"));CacheConfigcacheConfig =CacheConfig.custom().setMaxCacheEntries(1000)        .setMaxObjectSize(1024 *128).build();CloseableHttpClienthttpClient =CachingHttpClientBuilder        .create()// allow caching        .setCacheConfig(cacheConfig)// Wrap the local JarCacheStorage around a BasicHttpCacheStorage        .setHttpCacheStorage(newJarCacheStorage(null,cacheConfig,newBasicHttpCacheStorage(cacheConfig)))....// Add in the credentials provider        .setDefaultCredentialsProvider(credsProvider);// When you are finished setting the properties, call build        .build();documentLoader.setHttpClient(httpClient);JsonLdOptionsoptions =newJsonLdOptions();options.setDocumentLoader(documentLoader);// .. and any other optionsObjectrdf =JsonLdProcessor.toRDF(input,options);

Thejsonld-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.gitchmod +x ./jsonldplayground

run the following to get usage details:

./jsonldplayground --help

jsonld-java uses maven to compile. From the basejsonld-java module runmvn clean install to install the jar into your local maven repository.

mvntest

or

mvntest -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 theJSON-LD Implementation Report document can be regenerated using the following command:

mvntest -pl core -Dtest=JsonLdProcessorTest -Dreport.format=<format>

Current possible values for<format> include JSON-LD (application/ld+json orjsonld), NQuads (text/plain,nquads,ntriples,nq ornt) and Turtle (text/turtle,turtle orttl).* 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.

• Eclipse RDF4J
• Apache Jena
• RDF2GO
• Apache Clerezza

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

<projectxmlns="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.5</version>  </parent>  <modelVersion>4.0.0</modelVersion>  <artifactId>jsonld-java-{your module}</artifactId>  <version>0.13.5-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 tojsonld-java-{module id}, where{module id} usually represents the RDF library you're integrating (e.g.jsonld-java-jena)
• project/name : set this toJSONLD 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 needs

For Example: Follow the first few steps in the section above to import the wholejsonld-java project or only your new module into eclipse.

The interfacecom.github.jsonldjava.core.RDFParser is used to parse RDF from the library into the JSONLD-Java internal RDF format. See the documentation inRDFParser.java for details on how to implement this interface.

The interfacecom.github.jsonldjava.core.JSONLDTripleCallback is used to generate a representation of the JSON-LD input in the RDF library. See the documentation inJSONLDTripleCallback.java for details on how to implement this interface.

A JSONLD RDF parser is a class that can parse your frameworks' RDF modeland generate JSON-LD.

There are two ways to use yourRDFParser implementation.

Register your parser with theJSONLD class and setoptions.format when you callfromRDF

JSONLD.registerRDFParser("format/identifier",newYourRDFParser());Objectjsonld =JSONLD.fromRDF(yourInput,newOptions("") {{format ="format/identifier" }});

or pass an instance of yourRDFParser into thefromRDF function

Objectjsonld =JSONLD.fromRDF(yourInput,newYourRDFParser());

A JSONLD triple callback is a class that can populate your framework'sRDF model from JSON-LD - being called for each triple (technically quad).

Pass an instance of yourTripleCallback toJSONLD.toRDF

ObjectyourOutput =JSONLD.toRDF(jsonld,newYourTripleCallback());

Your framework might have its own system of readers and writers, whereyou should register JSON-LD as a supported format. Remember that herethe "parse" direction is opposite of above, a 'reader' may be a classthat 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 aREADME.md file with instrutions on how to use your module.

Once you'vecommitted your code, andpushed it into your github fork you can issue aPull 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.

• Release 0.13.6
• Bump Jackson-databind version to latest for security update

• Release 0.13.5
• Bump Jackson and Guava versions to latest for security updates

• Release 0.13.4
• Switch test logging from log4j to logback (Patch by @ansell)
• Improve Travis CI build Performance (Patch by @YunLemon)

• Release 0.13.3
• Fix @type when subject and object are the same (Reported by @barthanssens, Patch by @umbreak)
• Ignore @base if remote context is not relative (Reported by @whikloj, Patch by @dr0i)
• Fix throwing recursive context inclusion (Patch by @umbreak)

• Release 0.13.2
• Fix Guava dependency shading (Reported by @ggrasso)
• Fix @context issues when using a remote context (Patch by @umbreak)
• Deprecate Context.serialize (Patch by @umbreak)

• Release 0.13.1
• Fix java.net.URI resolution (Reported by @ebremer and @afs, Patch by @dr0i)
• Shade Guava failureaccess module (Patch by @peacekeeper)
• Don't minimize Guava class shading (Patch by @elahrvivaz)
• Follow link headers to @context files (Patch by @dr0i and @fsteeg)

• Release 0.13.0
• Bump Jackson versions to latest for security updates (Patch by @afs)
• Do not canonicalise XSD Decimal typed values (Patch by @jhg023)
• Bump dependency and plugin versions

• Release 0.12.5
• Bump Jackson versions to latest for security updates (Patches by @afs)
• IRI resolution fixes (Patch by @fsteeg)

• Release 0.12.4
• Bump Jackson version to 2.9.8
• Add a regression test for a past framing bug
• Throw error on empty key
• Add regression tests for workarounds to Text/URL dual definitions
• Persist JsonLdOptions through normalize/toRDF

• Release 0.12.3
• Fix NaN/Inf/-Inf raw value types on conversion to RDF
• Added fix for wrong rdf:type to @type conversion (Path by @umbreak)
• Open up Context.getTypeMapping and Context.getLanguageMapping for reuse

• W3c json ld syntax 34 allow container set on aliased type (Patch by @dr0i)
• Release 0.12.2

• handle omit graph flag (Patch by @eroux)
• Release 0.12.1
• Make pruneBlankNodeIdentifiers false by default in 1.0 mode and always true in 1.1 mode (Patch by @eroux)
• Fix issue with blank node identifier pruning when @id is aliased (Patch by @eroux)
• Allow wildcard {} for @id in framing (Patch by @eroux)

• Fix tests setup for schema.org with HttpURLConnection that break because of the inability of HttpURLConnection to redirect from HTTP to HTTPS

• Release 0.12.0
• Encapsulate RemoteDocument and make it immutable

• Fix performance issue caused by not caching schema.org and others that useCache-Control: private (Patch by @HansBrende)
• Cache classpath scans for jarcache.json to fix a similar performance issue
• Add internal shaded dependency on Google Guava to use maintained soft and weak reference maps rather than adhoc versions
• Make JsonLdError a RuntimeException to improve its use in closures
• Bump minor version to 0.12 to reflect the API incompatibility caused by JsonLdError and protected field change and hiding in JarCacheStorage

• Fix resource leak in JsonUtils.fromURL on unsuccessful requests (Patch by @plaplaige)

• Ignore UTF BOM (Patch by @christopher-johnson)

• Release 0.11.1
• Fix @embed:@always support (Patch by @dr0i)

• Release 0.11.0

• Add implicit "flag only" subframe to fix incomplete list recursion (Patch by @christopher-johnson)
• Support pruneBlankNodeIdentifiers framing option in 1.1 mode (Patch by @fsteeg and @eroux)
• Support new @embed values (Patch by @eroux)

• Add injection of contexts directly into DocumentLoader (Patch by @ryankenney)
• Fix N-Quads content type (Patch by @NicolasRouquette)
• Add JsonUtils.fromJsonParser (Patch by @dschulten)

• Make literals compare consistently (Patch by @stain)
• Release 0.10.0

• Propagate causes for JsonLdError instances where they were caused by other Exceptions
• Remove schema.org hack as it appears to work again now...
• Remove deprecated and unused APIs
• Bump version to 0.10.0-SNAPSHOT per the removed/changed APIs

• Release 0.9.0
• Fixes schema.org support that is broken with Apache HTTP Client but works with java.net.URL

• Fix reported NPE in JsonLdApi.removeDependents

• Release 0.8.3
• Fix @base in remote contexts corrupting the local context

• Support @default inside of sets for framing

• Fix ConcurrentModificationException in the implementation of the Framing API

• Re-release version 0.8.2 with the refactoring work actually in it. 0.8.1 is identical in functionality to 0.8.0
• Release version 0.8.1
• Refactor JSONUtils and DocumentLoader to move most of the static logic into JSONUtils, and deprecate the DocumentLoader versions

• Release version 0.8.0

• Replace deprecated HTTPClient code with the new builder pattern
• Chain JarCacheStorage to any other HttpCacheStorage to simplify the way local caching is performed
• Bump version to 0.8.0-SNAPSHOT as some interface method parameters changed, particularly, DocumentLoader.setHttpClient changed to require CloseableHttpClient that was introduced in HttpClient-4.3

• Bump dependencies to latest versions, particularly HTTPClient that is seeing more use on 4.5/4.4 than the 4.2 series that we have used so far
• Performance improvements for serialisation to N-Quads by replacing string append and replace with StringBuilder
• Support setting a system property, com.github.jsonldjava.disallowRemoteContextLoading, to "true" to disable remote context loading.

• Release 0.7.0

• Move Tools, Clerezza and RDF2GO modules out to separate repositories. The Tools repository had a circular build dependency with Sesame, while the other modules are best located and managed in separate repositories

• Remove Sesame-2.7 module in favour of sesame-rio-jsonld for Sesame-2.8 and 4.0
• Fix bug where parsing did not fail if content was present after the end of a full JSON top level element

• Compact context arrays if they contain a single element during compaction
• Bump to Sesame-2.7.15

• Use jopt-simple for the playground cli to simplify the coding and improve error messages
• Allow RDF parsing and writing using all of the available Sesame Rio parsers through the playground cli
• Make the httpclient dependency OSGi compliant

• Fix locale sensitive serialisation of XSD double/decimal typed literals to always be Locale.US
• Bump to Sesame-2.7.14
• Bump to Clerezza-0.14

• Fix identification of integer, boolean, and decimal in RDF-JSONLD with useNativeTypes
• Release 0.5.1

• Add OSGi metadata to Jar files
• Bump to Sesame-2.7.13

• Release version 0.5.0
• Fix Jackson parse exceptions being propagated through Sesame without wrapping as RDFParseExceptions

• Fix use of Java-7 API so we are still Java-6 compatible
• Ensure that Sesame RDFHandler endRDF and startRDF are called in SesameTripleCallback

• Release version 0.4.2
• Bump to Sesame-2.7.12
• Remove Jena integration module, as it is now maintained by Jena team in their repository

• Release version 0.4
• Bump to Sesame-2.7.11
• Bump to Jackson-2.3.3
• Bump to Jena-2.11.1

• Bump RDF2GO to version 5.0.0

• Allow loading remote @context from bundled JAR cache
• Support JSON array in @context with toRDF
• Avoid exception on @context with default @language and unmapped key

• Javadoc some core classes, JsonLdProcessor, JsonLdApi, and JsonUtils
• Rename some core classes for consistency, particularly JSONUtils to JsonUtils and JsonLdTripleCallback
• Fix for a Context constructor that wasn't taking base into account

• Fix JsonLdApi mapping options in framing algorithm (Thanks Scott Blomquist @sblom)

• Release version 0.3
• Bump to Sesame-2.7.10
• Fix Jena module to use new API

• Updated to final Recommendation
• Namespaces supported by Sesame integration module
• Initial implementation of remote document loading
• Bump to Jackson-2.3.1

• updated jena writer

• Integration packages renamed com.github.jsonldjava.sesame,com.github.jsonldjava.jena etc. (Issue #76)

• Matched class names to Spec

• RenamedJSONLDException toJsonLdError
• RenamedJSONLDProcessor toJsonLdApi
• RenamedJSONLD toJsonLdProcessor
• RenamedActiveContext toContext
• RenamedOptions toJsonLdOptions

• All context related utility functions moved to be members of theContext class

• Fixed JSON-LD to Jena to handle of BNodes

• Add RDF2Go integration
• Bump Sesame and Clerezza dependency versions

• Bump to version 0.2
• Updated Turtle integration
• Added Caching of contexts loaded from URI
• Added source formatting eclipse config
• Fixed up seasame integration package names
• Replaced depreciated Jackson code

• Added Turtle RDFParser and TripleCallback
• Changed Maven groupIds tocom.github.jsonld-java to match github domain.
• Released version 0.1

• Updated core code to matchJSON-LD 1.0 Processing Algorithms and API / W3C Editor's Draft 14 May 2013
• Deprecated JSONLDSerializer in favor of the RDFParser interface to better represent the purpose of the interface and better fit in with the updated core code.
• Updated the JSONLDTripleCallback to better fit with the updated code.
• Updated the Playground tool to support updated core code.

• Changed base package names to com.github.jsonldjava
• Reverted version to 0.1-SNAPSHOT to allow version incrementing pre 1.0 while allowing a 1.0 release when the json-ld spec is finalised.
• Turned JSONLDTripleCallback into an interface.

• Updated to Sesame 2.7.0, Jena 2.10.0, Jackson 2.1.4
• Fixing a character encoding issue in the JSONLDProcessorTests
• Bumping to 1.0.1 to reflect dependency changes

• Brought the implementation up to date with the reference implementation (minus the normalization stuff)
• Changed entry point for the functions to the static functions in the JSONLD class
• Changed the JSONLDSerializer to an abstract class, requiring the implementation of a "parse" function. The JSONLDSerializer is now passed to the JSONLD.fromRDF function.
• Added JSONLDProcessingError class to handle errors more efficiently

• TheContext class is aMap 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).
• some sort of document loader interface (with a mockup for testing) is required