@verisav/graphql-rdf-vocabularies

Expose RDF/OWL vocabularies (Turtle, JSON-LD) via GraphQL.
Parse TTL files, then query classes and properties with optional language. Used in production at Verisav for the DPP, RMA, and WTY vocabularies.

Use this package to serve your own ontologies over GraphQL with minimal setup.

Install

npm install @verisav/graphql-rdf-vocabularies graphql

Quick start

1. Put your Turtle vocabularies in a folder, e.g.:

   ./vocabularies/
     dpp/
       dpp.ttl
     my-ontology/
       my-ontology.ttl

2. Create a parser and build the schema:

import { VocabularyParser, buildGraphQLSchema } from '@verisav/graphql-rdf-vocabularies'
import { createYoga } from 'graphql-yoga'

const parser = new VocabularyParser({
  basePath: join(process.cwd(), 'vocabularies'),
  vocabularyFiles: {
    dpp: 'dpp.ttl',
    'my-ontology': 'my-ontology.ttl',
  },
})

const schema = buildGraphQLSchema(parser)
const yoga = createYoga({ schema })

// Serve: e.g. export default yoga (Next.js) or yoga.handle (Node)

3. Query via GraphQL:

query {
  vocabularies {
    id
    title(lang: "en")
    classes {
      name
      label(lang: "fr")
    }
  }
  vocabulary(id: "dpp") {
    id
    properties {
      name
      type
      domain
    }
  }
}

API

VocabularyParser(config)

• config.basePath – Directory containing one folder per vocabulary (e.g. vocabularies/).
• config.vocabularyFiles – Map of vocabulary id → filename (e.g. { dpp: 'dpp.ttl' }).

Methods:

• parseVocabulary(id: string): Promise<ParsedVocabulary> – Parse and cache one vocabulary.
• `clearCache(): void – Clear in-memory cache.
• getVocabularyIds(): string[] – List configured vocabulary ids.

buildGraphQLSchema(parser: VocabularyParser): GraphQLSchema

Builds a GraphQL schema with:

• Query.vocabularies – List all vocabularies (metadata + classes + properties).
• Query.vocabulary(id) – One vocabulary by id.
• Query.classes(vocabularyId) – All classes of a vocabulary.
• Query.class(vocabularyId, name) – One class by name.
• Query.properties(vocabularyId) – All properties.
• Query.property(vocabularyId, name) – One property by name.

Fields title, description, label, comment accept an optional lang argument (e.g. en, fr).

Turtle requirements

Your TTL files should use standard RDF/OWL terms:

• Classes: rdf:type owl:Class, rdfs:label, rdfs:comment, rdfs:subClassOf.
• Properties: rdf:type owl:ObjectProperty or owl:DatatypeProperty, rdfs:label, rdfs:comment, rdfs:domain, rdfs:range.
• Ontology metadata: dc:title, dc:description, dc:creator, owl:versionInfo, etc.

The parser reads from the default graph; it does not support named graphs.

References

• Verisav DPP vocabulary
• Verisav GraphQL API (live)
• N3.js (Turtle parsing)
• GraphQL

License

MIT