Introspections

Utility object for annotation-based introspection, providing methods to process annotations for descriptions, ignore markers, and name overrides.

This object provides a configurable mechanism for recognizing annotations from multiple frameworks (kt-schema, Jackson, LangChain4j, Koog, kotlinx.serialization, etc.) Configuration is loaded from kt-schema.properties on the classpath.

Annotation name matching

Every configured annotation name is a glob pattern (* matches any run of characters, ? a single character; a plain literal name is just a pattern that matches itself), compiled via the shared me.kpavlov.kt.schema.generator.core.globToRegex matcher — the same one used by KSP's include/exclude package filters. Patterns are matched in two ways depending on their format:

• Simple names (no dots): Matched case-insensitively against the annotation's simple name. Example: "Description" matches @Description, @description, @DESCRIPTION; "Json*" matches @JsonIgnore, @JsonIgnoreType, @JsonProperty, etc.

• Fully qualified names (contains dots): Matched case-sensitively against the annotation's qualified name. Example: "kotlinx.serialization.SerialName" matches only @kotlinx.serialization.SerialName, not a different @SerialName from another package.

Configuration

The annotation detection behavior is controlled by properties in kt-schema.properties:

• introspector.annotations.description.names: Comma-separated list of annotation names to recognize as description providers (e.g., "Description,LLMDescription,P")

• introspector.annotations.description.attributes: Comma-separated list of annotation parameter names that contain description text (e.g., "value,description")

• introspector.annotations.ignore.names: Comma-separated list of annotation names to recognize as ignore markers (e.g., "SchemaIgnore,JsonIgnoreType,JsonIgnore")

• introspector.annotations.name.names: Comma-separated list of annotation names to recognize as name-override providers (e.g., "kotlinx.serialization.SerialName")

• introspector.annotations.name.attributes: Comma-separated list of annotation parameter names that contain name-override text (e.g., "value")

Customizing Configuration

To add support for custom annotations, create kt-schema.properties in your project's src/main/resources/ directory (or src/commonMain/resources/ for multiplatform projects):

introspector.annotations.description.names=Description,MyCustomDescription
introspector.annotations.description.attributes=value,description,text

Your project's properties file will take precedence over the library's default configuration.

See also