semantic-graphql
Advanced tools
Semantic GraphQL provides an API to convert any RDF, RDFS and OWL-based ontologies into GraphQL objects.
The library does not deal with data, only with terminology. Therefore resolving data/resources is up to you.
Table of contents:
Runs on Node v6 or higher.
npm install semantic-graphql --save
Semantic-graphql makes no assumption about the shape of your data and only passes it around. You have to provide six functions to resolve it in different ways. See the resolvers section.
const resolvers = { /* Choose how to resolve data */ };
Once your resolvers are written you can create a SemanticGraph. In the graph all the triples defining RDF, RDFS and OWL are included by default.
const SemanticGraph = require('semantic-graphql');
const _ = new SemanticGraph(resolvers, config);
Now you can add your own triples. Only statements defining your terminology (classes + properties) will be used, so you shouldn't add your individuals as it will only consume memory.
_.addTriple({
subject: 'http://foo.com#MyClass',
predicate: 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type',
object: 'http://www.w3.org/2002/07/owl#Class',
});
// From a string or a file. Multiple formats are available.
_.parse(string);
_.parseFile('/path/to/ontology.ttl');
When Semantic-graphql translates a rdf:Property to a GraphQLFieldConfig, the resulting type will be wrapped in a GraphQLList unless the property is a owl:FunctionalProperty. Therefore you may have to do some adjustments in order to prevent that. Almost anything can be overriden, see the override section.
// We do not want rdfs:label to resolve arrays
_['http://www.w3.org/2000/01/rdf-schema#label'].isGraphqlList = false;
Now you can start building your GraphQL schema however you want.
const schema = new GraphQLSchema({
query: new GraphQLObjectType({
name: 'Query',
fields: {
myField: {
// GraphQL objects are created on demand using the API
type: _.getObjectType('http://foo.com#MyClass'),
resolve: /* ... */,
},
resource: {
// The rdfs:Resource interface allows you to query any data
type: _.getInterfaceType('http://www.w3.org/2000/01/rdf-schema#Resource'),
args: {
id: { type: new GraphQLNonNull(GraphQLString) },
},
resolve: /* ... */,
},
},
}),
});
Have a look at the examples folder to see a complete setup.
class SemanticGraph {
constructor(resolvers: Resolvers, config: ?SemanticGraphConfig),
[subject: Iri]: object,
# Public methods:
addTriple: AddTripleFn,
parse: ParseFn,
parseFile: ParseFileFn,
getObjectType: GetObjectTypeFn,
getInterfaceType: GetInterfaceTypeFn,
getEdgeType: GetEdgeTypeFn,
getConnectionType: GetConnectionTypeFn,
addFieldOnObjectType: AddFieldOnObjectTypeFn,
extendFieldOnObjectType: ExtendFieldOnObjectTypeFn,
# When the relay option is on:
nodeField: GraphQLFieldConfig,
nodeInterface: GraphQLInterfaceType,
}
type SemanticGraphConfig = {
prefixes?: PrefixConfig,
# Activates the Relay features
relay?: boolean,
# Your reprefered locale when inferring names and descriptions from rdfs:label and rdfs:comment
locale?: string = 'en',
# Prevents the id field to be automatically added to every GraphlQLFieldConfigMap
preventIdField?: boolean,
}
To prevent GraphQL names collisions, you can edit the name directly (see the override section) or specifify prefixes for ontology namespaces. The names of the generated GraphQL objects will be prefixed. RDF, RDFS and OWL ontologies are by default prefixed with "Rdf", "Rdfs" and "Owl". So a fragment on rdfs:Resource should be "on RdfsResource".
type PrefixConfig = {
[prefix: string]: Iri,
}
# Must represent a valid IRI
type Iri = string
type AddTripleFn(triple: Triple) => undefined
type Triple = {
subject: Iri,
predicate: Iri,
object: Iri | string,
}
Appends a triple to the graph. No-op if the subject or predicate IRI is invalid, or if the triple already exists.
Will be removed someday
Will be removed someday
type GetObjectTypeFn = (classIri: Iri) => GraphQLObjectType
Returns the GraphQLObjectType corresponding to a given individual of rdfs:Class or its sub-classes (like owl:Class). Throws if the IRI is not found in the graph.
type GetInterfaceTypeFn = (classIri: Iri) => GraphQLInterfaceType
type GetEdgeTypeFn = (classIri: Iri) => ?RelayEdgeType
Returns a value only when the relay: true option is on.
type GetConnectionTypeFn = (classIri: Iri) => ?RelayConnectionType
Returns a value only when the relay: true option is on.
type AddFieldOnObjectTypeFn = (
classIri: Iri,
fieldName: string,
graphqlFieldConfig: GraphQLFieldConfig
) => Iri
Adds a custom field "fieldName" on the GraphQLObjectType and GraphQLInterfaceType representing "classIri". Throws if "classIri" is not found in the graph. Returns a random IRI referencing the new virtual rdf:Property.
type AddFieldOnObjectTypeFn = (
classIri: Iri,
propertyIri: Iri,
graphqlFieldConfig: PseudoGraphQLFieldConfig
) => undefined
Similar to overriding a field using _['http://foo.com/someProperty'].graphqlFieldConfigExtension = /* ... */ but only for a particular class, not for all of the classes on the property's domain.
A PseudoGraphQLFieldConfig is just a GraphQLFieldConfig where every key is optional. The other keys will be infered.
Throws if "classIri" is not found in the graph.
type Resolvers = {
resolveSourceId: ResolveSourceIdFn,
resolveSourceTypes: ResolveSourceTypesFn,
resolveSourcePropertyValue: ResolveSourcePropertyValueFn,
resolveResource: ResolveResourceFn,
resolveResources: ResolveResourcesFn,
resolveResourcesByPredicate: ResolveResourcesByPredicateFn,
}
type ResolverOutput<x> = x | Array<x> | Promise<x> | Promise<Array<x>>
type ResolveSourceIdFn = (
source?: any,
context?: any,
info?: GraphQLResolveInfo
) => ?ID | ?Promise<ID>
Must be sync if you use Relay.
See globalIdField source code
type ResolveSourceTypesFn = (
source?: any,
info?: GraphQLResolveInfo
) => Iri | Array<Iri>
Must be sync. See this GraphQL issue.
type ResolveSourcePropertyValueFn = (
source?: any,
propertyIri?: Iri,
context?: any,
info?: GraphQLResolveInfo
) => ?ResolverOutput<any>
type ResolveResourceFn = (
resourceIri?: Iri,
context?: any,
info?: GraphQLResolveInfo
) => ?ResolverOutput<any>
type ResolveResourcesFn = (
resourceIris?: Array<Iri>,
context?: any,
info?: GraphQLResolveInfo
) => ?ResolverOutput<any>
type ResolveResourcesByPredicateFn = (
typeIri?: Array<Iri>,
predicateIri?: Iri,
value?: any,
context?: any,
info?: GraphQLResolveInfo
) => ?ResolverOutput<any>
To override anything there is no method: you directly set the library's internals.
_['http://the.resource.to/be#altered'].key = value;
If "key" is already present, the library will use the underlying value and won't try to create it.
| Resource type | key | value type |
|---|---|---|
| any | graphqlName | String |
| any | graphqlDescription | String |
| class | graphqlFieldConfigMap | GraphQLFieldConfigMap |
| class | graphqlObjectType | GraphQLObjectType |
| class | graphqlInterfaceType | GraphQLInterfaceType |
| class | relayConnectionDefinitions | { edgeType, connectionType } |
| property | isGraphqlList | Boolean |
| property | isRelayConnection | Boolean |
| property | graphqlFieldConfig | GraphQLFieldConfig |
| property | graphqlFieldConfigExtension | partial GraphQLFieldConfig, to modify only parts of it |
| property | shouldAlwaysUseInverseOf | Boolean |
| property | shouldNeverUseInverseOf | Boolean |
Note that the following overrides must be performed before invoking getObjectType or getInterfaceType or getEdgeType or getConnectionType since those methods create the GraphQL objects you want to override.
Examples:
_['http://foo.com#worksForCompany'].graphqlName = 'company';
// Now the field name for foo:worksForCompany will be 'company'
// Partial modifications to fields are achieved using
_['http://foo.com#worksForCompany'].graphqlFieldConfigExtension = {
args: /* Look Ma', arguments! */
resolve: customResolveFn,
};
// Completly overriding a GraphQLObject can be done with
_['http://foo.com/MyClass'].graphqlObjectType = new GraphQLObjectType({ /* ... */});
By using the relay: true option:
_.nodeField and _.nodeInterface object are available_.getConnectionType and _.getEdgeType methods are availableSee the Relay example.
The following features will not be implemented due to their incomptability with GraphQL:
Yes, thank you. Please lint, update/write tests and add your name to the package.json file before you PR.
Semantic GraphQL is released under the MIT License.
GraphQL is released by Facebook, inc. under the BSD-license with an additional patent grant.
0.5.1
Bug fixes:
owl:inverseOf inference that broke the feature in some cases.FAQs
Create GraphQL schemas from RDF ontologies
The npm package semantic-graphql receives a total of 16 weekly downloads. As such, semantic-graphql popularity was classified as not popular.
We found that semantic-graphql demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Create React App is officially deprecated due to React 19 issues and lack of maintenance—developers should switch to Vite or other modern alternatives.
Security News
Oracle seeks to dismiss fraud claims in the JavaScript trademark dispute, delaying the case and avoiding questions about its right to the name.
Security News
The Linux Foundation is warning open source developers that compliance with global sanctions is mandatory, highlighting legal risks and restrictions on contributions.