LiteralMapping class

Configures mapping details for literal values in RDF at the property level.

This class is used within the @RdfProperty annotation to customize how objects are serialized as literal values in RDF. Unlike class-level mappings configured with @RdfLiteral, these mappings are scoped to the specific property where they are defined and are not registered globally.

In RDF, literal values represent simple data values like strings, numbers, or dates. This mapping is typically used for:

• Value objects with special formatting requirements
• Custom data types that need specialized serialization logic
• Properties that need different literal representation than their default type
• Context-specific formatting (e.g., currencies that need different formats in different contexts)

Important: Mappers configured through LiteralMapping are only used by the specific ResourceMapper whose property annotation references them. They are not registered in the global mapper registry and won't be available for use by other mappers or for direct lookup.

Example:

@RdfProperty(
  SchemaBook.price,
  literal: LiteralMapping.namedMapper('formattedPriceMapper')
)
final Price price;

Without this override, the property would use the default mapper registered for the Price class, which might be configured with @RdfLiteral at the class level. The key difference is that the class-level mapper is globally registered (unless registerGlobally: false is specified), while this property-level mapping is only used for this specific property.

Property Type Support

For all property types, there must be a registered mapper available:

• Primitive types: Built-in mappers (String, int, double, bool, etc.)
• Annotated types: Generated mappers from @RdfLiteral annotations
• Custom types: Explicitly registered mappers

The LiteralMapping.withLanguage() and LiteralMapping.withType() constructors delegate to the registered mapper for the property's type and then apply additional processing (language tag or datatype override).

Examples

@RdfGlobalResource(...)
class Product {
  // Uses registered mapper for BookFormat enum
  @RdfProperty(ProductSchema.format)
  final BookFormat format;

  // Override with custom mapper for this property
  @RdfProperty(
    ProductSchema.priority,
    literal: LiteralMapping.namedMapper('customPriorityMapper')
  )
  final Priority priority;

  // Apply language tag to registered mapper result
  @RdfProperty(
    ProductSchema.condition,
    literal: LiteralMapping.withLanguage('en')
  )
  final BookFormat condition;

  // Apply custom datatype to registered mapper result
  @RdfProperty(
    ProductSchema.urgency,
    literal: LiteralMapping.withType(Xsd.string)
  )
  final Priority urgency;
}