rdfcodegen 0.1.0

Add your description here

rdfcodegen

Generate typed code interfaces from RDF/Turtle ontologies (e.g., schema.org).

Currently supports TypeScript output. Additional language generators planned.

In this README :point_down:

• Features
• Installation
• Usage
  • Command line
  • Python API
  • Filtering specific classes
• How it works
• Roadmap
• Projects using this template
• FAQ
• Contributing

Features

rdfcodegen parses RDF/Turtle ontology files (like schema.org) and generates language-specific code with full type definitions, documentation, and inheritance.

:rocket: What it produces:

• Type-safe interfaces/classes extracted from RDFS/OWL class hierarchies.
• JSDoc/Docstring comments pulled from rdfs:comment annotations.
• Automatic dependency resolution — request one class and get all its parent types and field types transitively.
• Primitive type mapping (e.g., schema:Text → string, schema:Number → number).

:computer: Supported output languages:

• TypeScript — interface definitions with optional properties (?) and array types.
• Go (planned)
• Python (planned)

Installation

pip install rdfcodegen

Requires Python 3.9+ and rdflib.

Usage

Command line

Generate TypeScript interfaces for all schema.org types:

rdfcodegen --ttl https://schema.org/version/latest/schemaorg-current-https.ttl \
           --namespace https://schema.org/ \
           --out schema.ts

Generate only specific classes (and everything they depend on):

rdfcodegen --class schema:Person --class schema:Organization --out schema.ts

Write to stdout (-):

rdfcodegen > schema.ts

CLI options:

Option	Default	Description
--ttl	schema.org/version/latest/schemaorg-current-https.ttl	URL or path to Turtle file
--namespace	https://schema.org/	Ontology namespace URI
--out	-	Output file (- for stdout)
--class	(all classes)	Generate specific classes (repeatable)

Python API

from rdfcodegen import TypescriptGenerator

gen = TypescriptGenerator()

# Generate all types
ts_code = gen.generate(
    ttl_url="https://schema.org/version/latest/schemaorg-current-https.ttl",
    namespace_url="https://schema.org/",
)

# Generate a subset
ts_code = gen.generate(
    chosen=["schema:Person", "schema:Event"],
    ttl_url="https://schema.org/version/latest/schemaorg-current-https.ttl",
    namespace_url="https://schema.org/",
)

with open("schema.ts", "w") as f:
    f.write(ts_code)

Filtering specific classes

When you specify classes with --class (or the chosen parameter), the generator:

1. Includes the requested classes.
2. Recursively includes all parent types up the rdfs:subClassOf hierarchy.
3. Recursively includes all field types referenced via schema:rangeIncludes.
4. Skips primitive types (e.g., schema:Text, schema:Number) — these map directly to language primitives.

This ensures the generated output is always self-contained and compilable.

How it works

1. Parse — The Turtle file is loaded into an RDF graph using rdflib.
2. Discover classes — All subjects typed as rdfs:Class within the target namespace are collected.
3. Traverse hierarchy — rdfs:subClassOf relationships are followed to build the class hierarchy.
4. Collect properties — schema:domainIncludes and schema:rangeIncludes are used to determine which fields belong to which classes and what types they return.
5. Extract documentation — rdfs:comment values become JSDoc/docstring comments.
6. Resolve dependencies — If filtering is requested, a dependency graph walk collects all transitive type references.
7. Generate output — A language-specific generator (e.g., TypescriptGenerator) emits the final code.

TypeScript output example

From schema:Person, the generator produces:

// THIS FILE IS AUTOMATICALLY GENERATED. DO NOT EDIT DIRECTLY.

/**
 * A person (alive, dead, undead, or fictional).
 */
export interface SchemaPerson extends SchemaThing {
  /**
   * An additional name for a Person, can be used for a middle name.
   */
  additionalName?: string[];
  /**
   * Physical address of the item.
   */
  address?: (SchemaPostalAddress | string)[];
  /**
   * Date of birth.
   */
  birthDate?: string[];
  // ... more fields
}

Roadmap

• Typescript types generator
  • Helper function to generate JSON-LD from those structs
• Go struct generator with JSON tags
• Python dataclass/pydantic generator
• Choose other languages

Contributing

If you find a bug :bug:, please open a bug report. If you have an idea for an improvement or new feature :rocket:, please open a feature request.