Processor API Reference

Complete reference for the Kastor Gen processor public API. This document only covers the public API surface - internal implementation details are not documented here.

Overview

The Kastor Gen processor is a KSP (Kotlin Symbol Processing) plugin that generates Kotlin code from:

• SHACL shapes - Defines data structure and constraints
• JSON-LD context - Provides type mappings and property definitions

Users interact with the processor through annotations - the processor classes themselves are internal implementation details.

Public API Surface

Model Classes

These data classes represent the ontology model and generation configuration:

InstanceDslRequest

Request object for generating instance DSL builders.

data class InstanceDslRequest(
    val dslName: String,
    val ontologyModel: OntologyModel,
    val packageName: String,
    val options: DslGenerationOptions = DslGenerationOptions()
)

Properties:

• dslName - Name of the DSL to generate (e.g., “skos”, “dcat”)
• ontologyModel - Combined SHACL shapes and JSON-LD context
• packageName - Target package for generated code
• options - Generation configuration options

DslGenerationOptions

Configuration options for DSL generation.

data class DslGenerationOptions(
    val validation: ValidationConfig = ValidationConfig(),
    val naming: NamingConfig = NamingConfig(),
    val output: OutputConfig = OutputConfig()
)

Nested Configurations:

ValidationConfig

data class ValidationConfig(
    val enabled: Boolean = true,
    val mode: ValidationMode = ValidationMode.EMBEDDED,
    val strict: Boolean = false,
    val validateOnBuild: Boolean = true
)

NamingConfig

data class NamingConfig(
    val strategy: NamingStrategy = NamingStrategy.CAMEL_CASE,
    val usePropertyNames: Boolean = true
)

OutputConfig

data class OutputConfig(
    val includeComments: Boolean = true,
    val includeKdoc: Boolean = true,
    val supportLanguageTags: Boolean = true,
    val defaultLanguage: String? = null
)

OntologyModel

Combined model containing SHACL shapes and JSON-LD context.

data class OntologyModel(
    val shapes: List<ShaclShape>,
    val context: JsonLdContext
)

ShaclShape

Represents a SHACL NodeShape.

data class ShaclShape(
    val shapeIri: String,
    val targetClass: String,
    val properties: List<ShaclProperty>,
    /** Target classes of parent shapes (`sh:node` on the node shape or `rdfs:subClassOf`). */
    val parentClasses: List<String> = emptyList(),
)

Blank-node node shapes get a stable synthetic shapeIri (urn:kastor:shape:<targetClass>).

ShaclProperty

Represents a property in a SHACL shape.

data class ShaclProperty(
    val path: String,
    val name: String,
    val description: String,
    val datatype: String?,
    val targetClass: String?,
    val minCount: Int?,
    val maxCount: Int?,
    // ... constraint properties (minLength, pattern, minInclusive, inValues, nodeKind, ...)
)

JsonLdContext

JSON-LD context providing type mappings.

data class JsonLdContext(
    val prefixes: Map<String, String>,
    val baseIri: Iri? = null,
    val vocabIri: Iri? = null,
    val typeMappings: Map<String, Iri>,
    val propertyMappings: Map<String, JsonLdProperty>
)

Builder Functions

dslOptions()

Creates DslGenerationOptions using a fluent DSL builder.

val options = dslOptions {
    validation {
        enabled = true
        mode = ValidationMode.EMBEDDED
        strict = false
    }
    naming {
        strategy = NamingStrategy.CAMEL_CASE
        usePropertyNames = true
    }
    output {
        supportLanguageTags = true
        defaultLanguage = "en"
        includeComments = true
    }
}

instanceDslRequest()

Creates InstanceDslRequest using a fluent DSL builder.

val request = instanceDslRequest("skos", "com.example") {
    ontologyModel = model
    options {
        validation { enabled = true }
    }
}

Extension Functions

ShaclShape.contains()

Checks if a shape contains a property with the given IRI.

operator fun ShaclShape.contains(propertyIri: String): Boolean

// Usage
if ("http://example.org/property" in shape) {
    // Property exists
}

Exception Classes

All exception classes are public for error handling:

• GenerationException - Base exception for generation errors
• MissingShapeException - Thrown when a required SHACL shape is missing
• InvalidConfigurationException - Thrown when configuration is invalid
• FileNotFoundException - Thrown when ontology files cannot be found
• ValidationException - Thrown when validation fails
• FileGenerationException - Thrown when file generation fails
• ProcessingException - Thrown when processing fails

Processor options

The processor reads these KSP options (all optional):

See Incremental Builds for the recommended build setup.

See Annotations: resolving paths.

Usage Patterns

Basic Usage

Users typically interact with the processor through annotations:

import com.geoknoesis.kastor.gen.annotations.Rdf

@Rdf(
    shacl = "ontologies/my-ontology.shacl.ttl",
    context = "ontologies/my-ontology.context.jsonld",
    packageName = "com.example.generated",
)
class OntologyGenerator

Advanced Usage

For programmatic generation (rare), users can use the public model classes:

val model = OntologyModel(
    shapes = listOf(/* ... */),
    context = JsonLdContext(/* ... */)
)

val options = dslOptions {
    validation { enabled = true }
}

val request = InstanceDslRequest(
    dslName = "skos",
    ontologyModel = model,
    packageName = "com.example",
    options = options
)

What’s NOT in the Public API

The following are internal implementation details and should not be used directly:

• ❌ Generator classes (InstanceDslGenerator, InterfaceGenerator, etc.)
• ❌ Parser classes (ShaclParser, JsonLdContextParser, etc.)
• ❌ Utility classes (NamingUtils, TypeMapper, etc.)
• ❌ Internal extension functions
• ❌ Internal sealed classes

These are subject to change without notice and are not part of the public API contract.

Version Compatibility

Built and tested with:

• Kotlin: 2.4.20
• KSP: 2.3.12
• JDK: 21+

See Also

• Annotations Reference - Annotation API
• Runtime API - Runtime interfaces
• Getting Started Tutorial - Usage guide