RdfLiteral class

Marks a Dart class or enum as representing an RDF literal term.

This annotation is used for value types that need custom serialization beyond simple Dart primitives:

• Value objects with validation logic (e.g., ratings, percentages, identifiers)
• Objects with formatted string representations (e.g., temperatures, currencies)
• Custom types with specific RDF serialization requirements

When you annotate a class with @RdfLiteral, a mapper is created that handles the conversion between your Dart class and RDF literal values.

Usage Options

You can define how your class is mapped in several ways:

1. Simple value objects - Use @RdfLiteral() and mark a property with @RdfValue()
2. Custom conversion methods - Use @RdfLiteral.custom() and specify class methods
3. External mappers - Use .namedMapper(), .mapper(), or .mapperInstance()

Property-Level Usage

You can also apply this as part of an @RdfProperty annotation to override serialization for a specific property:

@RdfGlobalResource(...)
class Product {
  @RdfProperty(
    ProductSchema.price,
    literal: LiteralMapping.namedMapper('priceMapper')
  )
  final Price price;
}

Examples

Simple value with validation:

@RdfLiteral()
class Rating {
  @RdfValue() // Value to use for serialization
  final int stars;

  Rating(this.stars) {
    if (stars < 0 || stars > 5) {
      throw ArgumentError('Rating must be between 0 and 5 stars');
    }
  }
}

Custom conversion methods:

@RdfLiteral.custom(
  toLiteralTermMethod: 'formatCelsius',
  fromLiteralTermMethod: 'parse',
  datatype: Xsd.string
)
class Temperature {
  final double celsius;
  Temperature(this.celsius);

  LiteralContent formatCelsius() => LiteralContent('$celsius°C');

  static Temperature parse(LiteralContent term) =>
    Temperature(double.parse(term.value.replaceAll('°C', '')));
}

Example with automatic value delegation:

@RdfLiteral()
class Rating {
  @RdfValue() // The 'stars' property value will be used as the literal value
  final int stars;

  Rating(this.stars) {
    if (stars < 0 || stars > 5) {
      throw ArgumentError('Rating must be between 0 and 5 stars');
    }
  }
}

Example with custom conversion methods:

@RdfLiteral.custom(
  toLiteralTermMethod: 'toRdf',
  fromLiteralTermMethod: 'fromRdf',
  datatype: Xsd.string
)
class Temperature {
  final double celsius;

  Temperature(this.celsius);

  LiteralContent toRdf() => LiteralContent('$celsius°C');

  static Temperature fromRdf(LiteralContent term) =>
    Temperature(double.parse(term.value.replaceAll('°C', '')));
}

Enum Usage

@RdfLiteral can be applied to enums to generate automatic literal mappers:

@RdfLiteral() // Uses enum constant names as literal values
enum BookFormat {
  hardcover, // → "hardcover"
  paperback, // → "paperback"
  ebook,     // → "ebook"
}

@RdfLiteral(XSD.string) // With explicit datatype
enum Priority {
  @RdfEnumValue('H') // Custom value override
  high,              // → "H"

  @RdfEnumValue('M')
  medium,            // → "M"

  low,               // → "low" (uses enum name)
}

When applied to enums, the generator creates a LiteralTermMapper<EnumType> that automatically handles conversion between enum constants and RDF literals. By default, the enum constant name is used as the literal value, but this can be overridden using the @RdfEnumValue annotation on individual constants.

Enum Validation Rules:

• Each enum constant with @RdfEnumValue must have a unique custom value
• Custom values cannot be empty or contain only whitespace
• The enum itself must be annotated with @RdfLiteral

Integration with Properties:

@RdfGlobalResource(...)
class Product {
  // Uses the enum's default @RdfLiteral mapping
  @RdfProperty(ProductSchema.format)
  final BookFormat format;

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