RootResource class

Annotation for top-level RDF resources with CRDT synchronization.

Marks a Dart class as a root resource that will be synchronized across storage backends (Solid Pods, Google Drive, local directories) using state-based CRDTs for conflict-free collaboration.

Basic Example

@RootResource(
  IriTerm('https://schema.org/Note'),
  MergeContract('https://myapp.example.com/mappings/note-v1#'),
)
class Note {
  @RdfProperty(Schema.name)
  @CrdtLwwRegister()
  String? title;

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

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

Resource Identification

Each resource instance is identified by an IRI (Internationalized Resource Identifier) using a configurable strategy:

  • Fragment-based IRIs (default): Resources live as fragments within framework-owned RDF documents (e.g., https://pod.example/notes/xyz.ttl#it).
  • Custom strategies: Configure via iriStrategy parameter using RootIriStrategy with RootIriConfig options.

CRDT Mapping Configuration

The crdt parameter controls property-level merge strategies:

Automatic generation (recommended):

MergeContract(
  'https://myapp.example.com/mappings/note-v1#',
  label: 'Note CRDT Mapping',  // Optional metadata
)

The builder scans CRDT annotations on properties and generates merge rules.

External CRDT mapping (for shared/standard vocabularies):

MergeContract.external('https://vocab.example.org/mappings/standard-note-v1#')

References a manually authored CRDT mapping document (must be provided via assets).

Property-Level CRDT Types

Properties must use CRDT annotations to define merge behavior:

  • @CrdtLwwRegister() - Last-Write-Wins (single value, default)
  • @CrdtOrSet() - Observed-Remove Set (multi-value, re-addable)
  • @CrdtImmutable() - Write-once, never changes

Default is LWW if no annotation present.

Indexing

Configure default FullIndex via fullIndex parameter:

@RootResource(
  IriTerm('https://schema.org/Note'),
  MergeContract('https://myapp.example.com/mappings/note-v1#'),
  fullIndex: FullIndex(policy: RootResourceFetchPolicy.onRequest),
)

Use FullIndex.disabled() when only GroupIndex applies.

Code Generation

The generator processes this annotation to create:

  • CRDT mapping documents with merge rules (if crdt.generate == true)
  • Resource configuration entries for LocordaConfig
  • RDF serialization/deserialization code (Dart ↔ RDF mapping)
  • Type-safe access to indexed properties

See Also

Inheritance
Implemented types

Constructors

RootResource(AppVocab vocab, {MergeContract mergeContract = const MergeContract(), RootIriStrategy iriStrategy = const RootIriStrategy(), FullIndex fullIndex = const FullIndex(), String? comment, String? label, List<(IriTerm, RdfObject)> metadata = const [], IriTerm? subClassOf})
Generated vocabulary + generated merge contract.
const
RootResource.external(IriTerm classIri, String mergeContractIri, {RootIriStrategy iriStrategy = const RootIriStrategy(), FullIndex fullIndex = const FullIndex()})
External vocabulary + external merge contract.
const
RootResource.externalContract(AppVocab vocab, String mergeContractIri, {RootIriStrategy iriStrategy = const RootIriStrategy(), FullIndex fullIndex = const FullIndex(), String? comment, String? label, List<(IriTerm, RdfObject)> metadata = const [], IriTerm? subClassOf})
Generated vocabulary + external merge contract.
const
RootResource.externalVocab(IriTerm classIri, String mergeContractAppBaseUri, {MergeContract mergeContract = const MergeContract(), RootIriStrategy iriStrategy = const RootIriStrategy(), FullIndex fullIndex = const FullIndex()})
External vocabulary + generated merge contract.
const

Properties

classIri → IriTerm?
The RDF class IRI for this resource.
finalinherited
comment → String?
Optional description for this class in define mode.
finalinherited
contract → MergeContract?
final
contractAppBaseUri → String?
final
direction → MapperDirection?
Specifies whether this mapper should handle serialization, deserialization, or both.
finalinherited
explicitClassIri → IriTerm?
final
explicitContractIri → String?
final
fragment → String?
The fragment identifier for vocabulary generation mode.
finalinherited
fullIndex → FullIndex
Configuration for the default FullIndex.
final
generateContract → bool
final
generatorVocab → AppVocab?
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