RdfIri class

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

This annotation is used for classes that represent identifiers or references that should be serialized as IRIs (Internationalized Resource Identifiers) in RDF graphs:

• URIs and URLs
• ISBNs, DOIs, and other standardized identifiers
• Domain-specific identifiers with structured formats

When you annotate a class with @RdfIri, a mapper is created that handles the conversion between your Dart class and IRI terms.

Property Requirements

For classes with @RdfIri (enum support see below) using the default constructor:

• All properties used for serialization/deserialization must be annotated with @RdfIriPart
• Any property without @RdfIriPart will be ignored during mapping
• The class must be fully serializable/deserializable using only the @RdfIriPart properties
• Derived or computed properties (not needed for serialization) don't need annotations

Important: When using external mappers (via .namedMapper(), .mapper(), or .mapperInstance()), the @RdfIriPart annotations are ignored. In this case, your custom mapper implementation is fully responsible for the serialization/deserialization logic.

IRI Generation

The IRI is computed using:

1. An optional template pattern with variables in curly braces, e.g., urn:isbn:{value}
2. Properties annotated with @RdfIriPart that provide values for these variables
3. For the simplest case without a template, the property marked with @RdfIriPart is used directly as the complete IRI

Usage Options

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

1. Template-based - @RdfIri('prefix:{value}')
2. Direct value - @RdfIri() (uses the @RdfIriPart property value as-is)
3. External mappers - .namedMapper(), .mapper(), or .mapperInstance()

By default, the generated mapper is registered globally in initRdfMapper. Set registerGlobally to false if this mapper should not be registered automatically. This is useful when the mapper requires constructor parameters that are only available at runtime and should be provided via @RdfProvides annotations in the parent class.

Examples

Template-based IRI:

@RdfIri('urn:isbn:{value}')
class ISBN {
  @RdfIriPart() // 'value' is inferred from property name
  final String value;

  ISBN(this.value);
  // Serialized as: urn:isbn:9780261102217
}

Direct value as IRI:

@RdfIri()
class AbsoluteUri {
  @RdfIriPart()
  final String uri;

  AbsoluteUri(this.uri);
  // Uses the value directly as IRI: 'https://example.org/resource/123'
}

Advanced Template Patterns

All @RdfIri templates support a powerful placeholder system with context variables and reserved expansion, applicable to both classes and enums:

Template Variable Types

• {value} - Property values from @RdfIriPart annotations
• {variable} - Context variables (percent-encoded)
• {+variable} - Reserved expansion (preserves URI structure like /)

Context Variable Resolution

Context variables are resolved from:

• Providers passed to the constructor of the generated Mapper.
• Global providers in initRdfMapper() are automatically passed to the generated Mapper constructor (when registerGlobally: true)

General Template Examples

Classes with context variables:

@RdfIri('{+baseUri}/users/{userId}/profile')
class UserProfile {
  @RdfIriPart('userId')
  final String userId;

  UserProfile(this.userId);
}

// When registerGlobally is true (default), this adds required providers:
final rdfMapper = initRdfMapper(
  baseUriProvider: () => 'https://api.example.org',
);

Multi-part class IRIs:

@RdfIri('{+baseUri}/collections/{collection}/{item}')
class CollectionItem {
  @RdfIriPart('collection')
  final String collection;

  @RdfIriPart('item')
  final String item;

  CollectionItem(this.collection, this.item);
}

Enums with context variables:

@RdfIri('{+baseUri}/categories/{category}/{value}')
enum ProductCategory {
  electronics, // → <https://example.org/categories/products/electronics>
  clothing,    // → <https://example.org/categories/products/clothing>
}

// Same provider setup applies to enums:
final rdfMapper = initRdfMapper(
  baseUriProvider: () => 'https://example.org',
  categoryProvider: () => 'products',
);

Enum Usage

@RdfIri can be applied to enums to generate automatic IRI mappers:

@RdfIri('http://example.org/formats/{value}')
enum BookFormat {
  @RdfEnumValue('hardcover-type')
  hardcover, // → <http://example.org/formats/hardcover-type>

  paperback, // → <http://example.org/formats/paperback>
}

@RdfIri('http://vocab.org/status/{value}')
enum Status {
  active,   // → <http://vocab.org/status/active>
  inactive, // → <http://vocab.org/status/inactive>
}

Advanced Enum Templates

Enums also support the full template system with context variables:

@RdfIri('{+baseUri}/categories/{category}/{value}')
enum ProductCategory {
  electronics, // → <https://example.org/categories/products/electronics>
  clothing,    // → <https://example.org/categories/products/clothing>
}

// When registerGlobally is true (default), this adds required providers to initRdfMapper:
final rdfMapper = initRdfMapper(
  baseUriProvider: () => 'https://example.org',
  categoryProvider: () => 'products',
);

For enums, the {value} placeholder is replaced with either:

• The custom value from @RdfEnumValue('custom') annotation
• The enum constant name (default)

When applied to enums, the generator creates an IriTermMapper<EnumType> that automatically handles conversion between enum constants and IRI terms. This is particularly useful for representing controlled vocabularies or taxonomies as IRIs in RDF.

Enum Validation Rules:

• Each enum constant with @RdfEnumValue must have a unique custom value
• Custom values must be valid IRI path segments (no spaces, proper encoding)
• The enum itself must be annotated with @RdfIri
• Template must contain {value} placeholder when used with enums
• Additional context variables are supported and follow the same resolution rules as class mappings

Integration with Properties:

@RdfGlobalResource(...)
class Product {
  // Uses the enum's default @RdfIri mapping
  @RdfProperty(ProductSchema.condition)
  final ItemCondition condition;

  // Override with custom mapper for this property
  @RdfProperty(
    ProductSchema.format,
    iri: IriMapping.namedMapper('customFormatMapper')
  )
  final BookFormat format;
}