Copyright (C) 2025 The Open Library Foundation
This software is distributed under the terms of the Apache License, Version 2.0. See the file "LICENSE" for more information.
This software uses the following BSD-3-Clause licensed software library:
This software uses the following Weak Copyleft (Eclipse Public License 1.0 / 2.0) licensed software libraries:
Lib-linked-data-rdf4ld is a Java library designed for converting RDF files with BIBFRAME records to Linked Data Graphs and vice versa.
The library supports mapping for the following top-level resources by default:
- Instance - instance of a bibliographic resource
- Hub - hub entity connecting related works and instances
mvn clean installThe library API accepts a MappingProfile parameter to define which top-level resources and what mapping rules should be processed during conversion.
The default mapping profile (used when no custom profile is provided) includes:
- Instance as a top-level resource
- Hub as a top-level resource
You can either use the default profile or provide a custom MappingProfile to specify different top-level resources.
@Service
public class MyService {
private final Rdf4LdService rdf4LdService;
public MyService(Rdf4LdService rdf4LdService) {
this.rdf4LdService = rdf4LdService;
}
public void convertBibframe2RdfToLinkedDataGraph() {
InputStream rdfInputStream = ...;
var contentType = "application/ld+json";
// Uses default profile with Instance and Hub as top resources
var result = rdf4LdService.mapBibframe2RdfToLd(rdfInputStream, contentType);
// Process the result as needed
}
}@Service
public class MyService {
private final Rdf4LdService rdf4LdService;
public MyService(Rdf4LdService rdf4LdService) {
this.rdf4LdService = rdf4LdService;
}
public void convertWithCustomProfile() {
Resource linkedDataGraph = ...;
var rdfFormat = RDFFormat.JSONLD;
var customProfile = new MappingProfile(/* custom configuration */);
var result = rdf4LdService.mapLdToRdf(linkedDataGraph, rdfFormat, customProfile);
// Process the result as needed
}
}The built artifacts for this module are available. See configuration for repository access.
The primary mechanism to map between Linked Data and BIBFRAME is through configuration profiles in JSON, found under src/main/resources/mappingProfile/bibframe2.0. The JSON schema for these files is defined in the model/ subdirectory.
The library uses JSON-based configuration files to define the transformation rules between BIBFRAME and Linked Data formats. These configuration profiles define:
- Resource type mappings
- Property mappings
- Predicate (edge) mappings
- Label configurations
Mapping profiles are organized by resource type and are loaded by MappingProfileReader class. The reader provides separate collections for:
- Instance mappings - for BIBFRAME Instance resources
- Hub mappings - for Hub resources that connect related entities
In general, the expectation when using configuration profiles is that the overall graph shape is nearly identical independent of vocabulary specifics, with only the terms changing (though properties can become predicates, altering the shape). For more complex transformations, you can add a new Java class that supplements the configuration profile.
Define the new mapping and add it to the directory above. Also update org.folio.rdf4ld.util.MappingProfileReader, defining a new static constant pointing to the added file and adding it to the appropriate instance, and/or hub section.
Top level. Matches a Linked Data resource by the incoming predicate and optionally by its set of types, either as an exact match or a required subset. Leave out the type set entirely if not relevant.
See typeSet, partialTypesMatch, predicate.
Top level. Matches a BIBFRAME resource by the incoming predicate and optionally by its full set of types.
Not implemented
Top level, can be used recursively. Add mappings for properties and outgoing predicates.
See label, properties, outgoingEdges.
An array of Linked Data properties to use as a BIBFRAME label. Use constants from the PropertyDictionary. Defaults to LABEL and LABEL_RDF when not set.
An array of property mappings.
See ldProperty, bfProperty, edgeParentBfDef, outgoingEdgeParentLdDef, incomingEdgeParentLdDef.
An array of predicate mappings.
See ldResourceDef, bfResourceDef, resourceMapping.
An array of types to match against. For ldResourceDef, you can use the constants from the ResourceTypesDictionary. For bfResourceDef, use the full term URIs.
Set to true to indicate a matching types set is not exhaustive. Other types can be used outside of the defined types set and still match. The default is false, which indicates an exact match of the set of types is required; additional types on a candidate would result in no match.
An incoming predicate to match against. For ldResourceDef, you can use the constants from the PredicateDictionary. For bfResourceDef, use the full term URI.
Match a Linked Data property. Use the constants from the PropertyDictionary.
Match a BIBFRAME property. Use the full term URI.
An ldResourceDef. Instead of transforming to a BIBFRAME property with a value, transform into a predicate with a resource as described by the ldResourceDef, and the new resource will have a bfProperty property.
See ldResourceDef.
Not implemented
Not implemented
The class must be annotated as an @RdfMapperDefinition. The annotation can take types and predicate arguments, at least one of which must be present. types should be one or more ResourceTypesDictionary values to match a candidate resource against, predicate should be one value from PredicateDictionary to match against.
The class must implement RdfMapperUnit or an abstract subclass of it, overriding mapToLd and mapToBibframe. Each can build on work done by a configuration profile. It may be useful to call BaseRdfMapperUnit's implementation of these methods, which both do a generic copy from one model to the other, following any directives in the configuration profile. You can then further modify the profile output to better fit the desired end state, or you can leave out the base call and build the output from scratch.