Kastor Gen Examples

Practical examples and use cases demonstrating Kastor Gen capabilities.

Runnable Gradle modules (clone the Kastor repo; these paths are not separate pages on this documentation site):

  • examples/hello-codegen — minimal codegen pipeline. @file:Rdf(shacl = "person-shape.ttl") makes the KSP processor generate a Person interface and PersonWrapper; main materializes RDF data as a Person. Run: ./gradlew :examples:hello-codegen:run
  • examples/dcat-us — generates one interface + wrapper per node shape of the DCAT-US 3.0 SHACL shapes (with a JSON-LD context that disambiguates vcard:Address / locn:Address). Run: ./gradlew :examples:dcat-us:runGeneratedExample (generated types), :examples:dcat-us:run (plain RDF API), :examples:dcat-us:runManualExample (hand-written classes)
  • examples/hello-world — RDF-only starter

Generated sources are written under each module’s build/generated/ksp/main/kotlin and are not checked in. Requires JDK 21+.

Table of Contents

Quick Start Examples

Simple Person Model

@Rdf(iri = "http://xmlns.com/foaf/0.1/Person")
interface Person {
    @Rdf(iri = "http://xmlns.com/foaf/0.1/name")
    val name: List<String>
    
    @Rdf(iri = "http://xmlns.com/foaf/0.1/age")
    val age: List<Int>
    
    @Rdf(iri = "http://xmlns.com/foaf/0.1/mbox")
    val email: List<String>
}

fun main() {
    val repo = Rdf.memory()
    repo.add {
        val person = iri("http://example.org/person")
        person - FOAF.name - "Alice Johnson"
        person - FOAF.age - 30
        person - FOAF.mbox - "alice@example.com"
    }
    
    val personRef = RdfRef(iri("http://example.org/person"), repo.defaultGraph)
    val person: Person = personRef.asType()
    
    println("Name: ${person.name.firstOrNull()}")
    println("Age: ${person.age.firstOrNull()}")
    println("Email: ${person.email.firstOrNull()}")
}

Organization with Employees

@Rdf(iri = "http://example.org/Organization")
interface Organization {
    @Rdf(iri = "http://example.org/name")
    val name: List<String>
    
    @Rdf(iri = "http://example.org/employee")
    val employees: List<Person>
}

fun main() {
    val repo = Rdf.memory()
    repo.add {
        val org = iri("http://example.org/org")
        val alice = iri("http://example.org/alice")
        val bob = iri("http://example.org/bob")
        
        // Organization
        org - RDF.type - Organization
        org - iri("http://example.org/name") - "Acme Corp"
        org - iri("http://example.org/employee") - alice
        org - iri("http://example.org/employee") - bob
        
        // Alice
        alice - RDF.type - FOAF.Person
        alice - FOAF.name - "Alice Johnson"
        alice - FOAF.age - 30
        
        // Bob
        bob - RDF.type - FOAF.Person
        bob - FOAF.name - "Bob Smith"
        bob - FOAF.age - 25
    }
    
    val orgRef = RdfRef(iri("http://example.org/org"), repo.defaultGraph)
    val org: Organization = orgRef.asType()
    
    println("Organization: ${org.name.firstOrNull()}")
    println("Employees:")
    org.employees.forEach { employee ->
        println("  - ${employee.name.firstOrNull()} (age ${employee.age.firstOrNull()})")
    }
}

Example Categories

1. Basic Examples

  • Simple domain models
  • Property mapping
  • Basic materialization
  • Side-channel access

2. Domain Modeling

  • Complex hierarchies
  • Polymorphic collections
  • Temporal data
  • Business rules

3. RDF Integration

  • Graph traversal
  • Custom queries
  • RDF manipulation
  • Inference

4. Validation

  • SHACL shapes
  • Custom validation
  • Error handling
  • Performance optimization

5. Performance

  • Caching strategies
  • Batch operations
  • Async processing
  • Memory optimization

6. Integration Patterns

  • Repository pattern
  • Service layer
  • Web APIs
  • Database integration

Getting Started

  1. Choose an example that matches your use case
  2. Copy the code and adapt it to your needs
  3. Add dependencies to your project
  4. Run the example to see it in action
  5. Modify and extend as needed

Contributing Examples

We welcome contributions of new examples! Please:

  1. Follow the existing structure
  2. Include clear comments
  3. Add appropriate error handling
  4. Test your examples
  5. Update this README

Need Help?