IndexItem class

Annotation for index item (entry) classes that represent projections of root resources within indices.

Important: IndexItem does not define a new RDF type. Index entries are framework-internal metadata structures represented as untyped fragment IRIs within shard documents. They have no explicit rdf:type triple and use predicate-based CRDT mappings instead of class-based mappings.

This is fundamentally different from RootResource, SubResource, and LocalResource, which define new semantic types with explicit rdf:type triples. IndexItem classes are framework projections for performance optimization, not domain model entities.

Usage

Use IndexItem.fullIndex for FullIndex entries and IndexItem.groupIndex for GroupIndex entries.

Example: FullIndex Entry

@RootResource(PersonalNotesVocab.Note, ...)
class Note {
  @RdfProperty(Schema.name)
  @CrdtLwwRegister()
  String? title;

  @RdfProperty(Schema.text)
  @CrdtLwwRegister()
  String? content;

  @RdfProperty(Schema.dateCreated)
  @CrdtImmutable()
  DateTime? createdAt;
}

// Index item with subset of Note properties
@IndexItem.fullIndex(IndexItemIriStrategy(Note))
class NoteIndexItem {
  @RdfProperty(Schema.name)
  String? title;

  @RdfProperty(Schema.dateCreated)
  DateTime? createdAt;

  // Note: content field omitted for performance - full data fetched on demand
}

Example: GroupIndex Entry

@GroupKey(Note, localName: 'byMonth', ...)
class NoteMonthGroupKey { ... }

@IndexItem.groupIndex(NoteMonthGroupKey, IndexItemIriStrategy(Note))
class NoteMonthIndexItem {
  @RdfProperty(Schema.name)
  String? title;

  @RdfProperty(Schema.dateCreated)
  DateTime? createdAt;
}

RDF Structure

Index entries are stored as framework-internal metadata without explicit RDF typing. Each entry is a fragment IRI (e.g., #entry-a1b2c3...) with:

  • idx:resource → IRI of the actual root resource (Immutable)
  • crdt:clockHash → Clock hash for change detection (LWW-Register)
  • Optional header properties extracted from root resource (LWW-Register)

No rdf:type triple is present. CRDT merging uses predicate-based rules.

IRI Strategy

IndexItemIriStrategy resolves to the same IRI as the root resource instance, ensuring index items and full resources are semantically identical.

Properties

  • Index item properties must be a subset of the root resource properties
  • Property annotations (@RdfProperty, types) must match exactly
  • CRDT annotations are inherited from root resource merge contract

Custom Vocabulary Properties

Index items can include properties from custom vocabularies defined for your application:

// Define custom vocabulary
const appVocab = AppVocab(
  appBaseUri: 'https://myapp.example.com/',
  vocabPath: 'vocabulary/myapp',
);

class MyAppProperties {
  static const priority = IriTerm('https://myapp.example.com/vocabulary/myapp#priority');
  static const categoryId = IriTerm('https://myapp.example.com/vocabulary/myapp#category');
}

// Root resource - generator creates vocabulary properties from fields
@RootResource(appVocab, ...)
class Task {
  @RdfProperty(Schema.name)
  String? title;

  int? priority;  // @RdfProperty.define() is optional - auto-generated as myapp:priority

  @RdfProperty.define(fragment: 'category')  // Explicit - generated as myapp:category
  String? categoryId;
}

// Index item - references the generated vocabulary
@IndexItem.fullIndex(IndexItemIriStrategy(Task))
class TaskIndexItem {
  @RdfProperty(Schema.name)
  String? title;

  @RdfProperty(MyAppProperties.priority)
  int? priority;

  @RdfProperty(MyAppProperties.categoryId)
  String? categoryId;
}

Code Generation

The generator creates deserialization-only mappers (no serialization needed) and links index items to their root resource type for proper RDF type handling.

See Also

Inheritance
Implemented types

Constructors

IndexItem.fullIndex(IndexItemIriStrategy iriStrategy)
Creates a FullIndex item annotation.
const
IndexItem.groupIndex(Type? groupKeyType, IndexItemIriStrategy iriStrategy)
Creates a GroupIndex item annotation.
const

Properties

classIri → IriTerm?
The RDF class IRI for this resource.
finalinherited
comment → String?
Optional description for this class in define mode.
finalinherited
direction → MapperDirection?
Specifies whether this mapper should handle serialization, deserialization, or both.
finalinherited
fragment → String?
The fragment identifier for vocabulary generation mode.
finalinherited
groupKeyType → Type?
The GroupKey type this item belongs to, or null for FullIndex items.
final
hashCode → int
The hash code for this object.
no setterinherited
iri → IriStrategy?
The IriStrategy annotation specifying how the IRI for this resource is constructed.
finalinherited
label → String?
Optional human-readable label for this class in define mode.
finalinherited
mapper → MapperRef<GlobalResourceMapper>?
Provides a MapperRef if a custom mapper is specified.
no setterinherited
metadata → List<(IriTerm, RdfObject)>?
Optional additional metadata triples for this class in define mode.
finalinherited
registerGlobally → bool
Controls whether the generated mapper should be registered globally in the initRdfMapper function.
finalinherited
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
subClassOf → IriTerm?
The superclass for this resource in define mode.
finalinherited
vocab → AppVocab?
The vocabulary configuration for define mode.
finalinherited

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