RdfProperty class

Maps a Dart class property to an RDF predicate.

This core annotation defines how properties are serialized to RDF and deserialized to Dart objects. Any property that should participate in RDF serialization must use @RdfProperty with a predicate IRI that identifies the relationship in the RDF graph.

NOTE: Only public properties are supported. Private properties (with underscore prefix) cannot be used with RDF mapping.

The annotation can be applied to:

• Instance fields: Compatible with all type-annotated fields (mutable, final, and late)
• Getters and setters: Follow these rules:
  • With include: true (default): Requires both getter and setter for full serialization/deserialization
  • With include: false (read-only from RDF): Requires only a setter as the value is only deserialized

RdfProperty handles data conversion in these ways:

• Automatic type mapping:

  • Standard Dart types (String, int, bool, DateTime, etc.) → RDF literals
  • Types with annotations (@RdfIri, @RdfLiteral, @RdfGlobalResource, @RdfLocalResource) → use their generated mappers
  • Types with registered mappers → handled according to their registration

• Custom mapping overrides: For specialized cases, specify exactly one of:

  • iri: Converts values to IRI references
  • localResource: Maps nested objects without assigned IRIs (using anonymous identifiers)
  • globalResource: Maps nested objects as resources with their own IRIs
  • literal: Applies custom literal serialization

• Default value handling:

  • Provides fallbacks when properties are missing during deserialization
  • Optional compact serialization by excluding properties matching defaults
  • Enables non-nullable fields to work with potentially missing data

• Collection handling: Lists, Sets and Maps receive flexible treatment:

  • Default behavior: Each item generates a separate triple with the same predicate
  • Custom collection mappers: Use collection parameter for structured RDF collections (rdf:List, rdf:Seq, etc.)
  • Item mapping: Apply iri, literal, globalResource, or localResource to individual items
  • Map collections: Use RdfMapEntry, RdfMapKey, and RdfMapValue for key-value pairs

Basic Usage

// Basic literal properties with default serialization
@RdfProperty(SchemaBook.name)
final String title;

// Optional property (nullable type makes it not required during deserialization)
@RdfProperty(
  SchemaBook.author,
  iri: IriMapping('http://example.org/author/{authorId}')
)
String? authorId;

// Property that will be read from RDF but not written back during serialization
@RdfProperty(SchemaBook.modified, include: false)
DateTime lastModified;

// A setter that updates the lastModified field internally
set updateLastModified(DateTime value) {
  lastModified = value;
}

// A completely separate property without RDF mapping - no annotation needed
bool get isRecentlyModified =>
  DateTime.now().difference(lastModified).inDays < 7;

// Non-nullable property with default value (won't cause error if missing)
@RdfProperty(SchemaBook.status, defaultValue: 'active')
final String status;

// Property with default that will be included in serialization even if equal to default
@RdfProperty(
  SchemaBook.rating,
  defaultValue: 0,
  includeDefaultsInSerialization: true
)
final int rating;

Advanced Mapping Scenarios

These examples demonstrate how to override the default mapping behavior when needed.

IRI Mapping

// Override: String property value converted to an IRI using a template
@RdfProperty(
  Dcterms.creator,
  iri: IriMapping('{+baseUri}/profile/{userId}')
)
final String userId;

In the example above:

• {userId} is a property-specific placeholder that refers directly to the property's value
• {+baseUri} is a context variable that must be provided through one of three methods:
  1. Via a global provider function in initRdfMapper (e.g., baseUriProvider: () => 'https://example.com') The generator will automatically add a required parameter to initRdfMapper.
  2. Via another property in the same class annotated with @RdfProvides('baseUri') This is preferred for context variables that are already available in the class.
  3. Via the parent resource's IRI, when the parent's IriStrategy specifies providedAs parameter This is useful for hierarchical structures where children need the parent's IRI.
• The + prefix (e.g., {+baseUri}) indicates variables that may contain URI-reserved characters like slashes, which should not be percent-encoded when substituted

For instance, if userId contains "jsmith", and baseUri resolves to "https://example.com", this will generate an IRI: "https://example.com/profile/jsmith"

Local Resource (Anonymous Resource) Mapping

// Automatic: Person class is already annotated with @RdfLocalResource or implemented and registered manually
@RdfProperty(SchemaBook.author)
final Person author;

// Override: Use custom mapper for this specific relationship
@RdfProperty(
  SchemaBook.publisher,
  localResource: LocalResourceMapping.namedMapper('customPublisherMapper')
)
final Publisher publisher;

Global Resource Mapping

// Automatic: Organization class is already annotated with @RdfGlobalResource or implemented and registered manually
@RdfProperty(SchemaBook.publisher)
final Organization publisher;

// Override: Use custom mapper for this specific relationship
@RdfProperty(
  SchemaBook.publisher,
  globalResource: GlobalResourceMapping.namedMapper('specialPublisherMapper')
)
final Publisher publisher;

Custom Literal Serialization

// Override: Use custom serialization for a property with special formatting needs
@RdfProperty(
  SchemaBook.price,
  literal: LiteralMapping.namedMapper('priceMapper')
)
final Price price;

Contextual Property Mapping

// Properties that need access to parent object/subject during mapping
class Document<T> {
  @RdfProperty(FoafDocument.primaryTopic)
  final String documentIri;

  // Property mapped with access to parent context
  @RdfProperty(
    FoafDocument.primaryTopic,
    contextual: ContextualMapping.namedProvider("primaryTopic")
  )
  final T primaryTopic;
}

// Mapper instantiation with SerializationProvider
final mapper = DocumentMapper<Person>(
  primaryTopic: SerializationProvider.iriContextual((IriTerm iri) =>
      PersonMapper(documentIriProvider: () => iri.value)),
);

Collection Handling

// Default behavior: Automatically uses UnorderedItemsMapper for standard collections
@RdfProperty(SchemaBook.authors)
final List<Person> authors; // Each Person is fully mapped with its own set of triples

// Using structured RDF collections (preserves order)
@RdfProperty(SchemaBook.chapters, collection: rdfList)
final List<Chapter> chapters; // Creates rdf:List structure

// Custom collection with explicit item type
@RdfProperty(
  SchemaBook.metadata,
  collection: CollectionMapping.withItemMappers(CustomCollectionMapper),
  itemType: MetadataEntry
)
final CustomCollection metadata;

// Structured RDF collections (different types)
@RdfProperty(SchemaBook.authors, collection: rdfSeq)
final List<Person> authors; // Creates rdf:Seq structure

@RdfProperty(SchemaBook.genres, collection: rdfBag)
final List<String> genres; // Creates rdf:Bag structure

Implemented types

• RdfAnnotation

Constructors

RdfProperty(IriTerm predicate, {bool include = true, dynamic defaultValue, bool includeDefaultsInSerialization = false, IriMapping? iri, LocalResourceMapping? localResource, LiteralMapping? literal, GlobalResourceMapping? globalResource, CollectionMapping? collection = const CollectionMapping.auto(), Type? itemType, ContextualMapping? contextual})

Creates an RDF property mapping annotation.

const

Properties

collection → CollectionMapping?

Specifies a custom collection mapper for handling collection properties.

final

contextual → ContextualMapping?

Optional contextual mapping configuration.

final

defaultValue → dynamic

Optional default value for this property.

final

globalResource → GlobalResourceMapping?

Specifies how to treat the property's value as an RDF resource with its own IRI.

final

hashCode → int

The hash code for this object.

no setter, inherited

include → bool

Whether to include this property during serialization to RDF.

final

includeDefaultsInSerialization → bool

Whether to include properties with default values during serialization.

final

iri → IriMapping?

Specifies how to treat the property's value as an IRI reference.

final

itemType → Type?

Explicitly specifies the item type for collection mapping.

final

literal → LiteralMapping?

Specifies custom literal conversion for the property value.

final

localResource → LocalResourceMapping?

Specifies how to treat the property's value as a nested anonymous resource.

final

predicate → IriTerm

The RDF predicate (IRI) for this property, e.g., SchemaBook.name.

final

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited