CollectionMapping class

Configures mapping details for collection properties in RDF.

This class is used within the @RdfProperty annotation to customize how collections (List, Set, Iterable, Map) as well as further custom collection or container classes are serialized in RDF. Collection mapping controls the overall structure and behavior of how collection data is represented in the RDF graph.

Default Collection Behavior

Unlike other mapping properties (iri, literal, globalResource, localResource) which default to registry lookup when not specified, collections have different default behavior:

When no collection parameter is specified on collection properties:

• List<T> defaults to CollectionMapping.auto() (uses UnorderedItemsListMapper)
• Set<T> defaults to CollectionMapping.auto() (uses UnorderedItemsSetMapper)
• Iterable<T> defaults to CollectionMapping.auto() (uses UnorderedItemsMapper)
• Map<K,V> defaults to CollectionMapping.auto() (uses entry-based mapping with @RdfMapEntry)
• Each item generates a separate triple with the same predicate
• Order is not preserved in RDF representation
• NOT serialized as structured RDF Collections (rdf:List, rdf:Seq, etc.)

To use registry-based mapper lookup (matching other mapping properties), explicitly specify collection: CollectionMapping.fromRegistry().

Collection vs Item Mapping

It's important to understand the distinction:

• Collection mapping (this class): Controls how the collection structure itself is serialized
• Item mapping (iri, literal, globalResource, localResource): Controls how individual items are serialized

These work together - the collection mapper handles the overall RDF structure, while item mappers handle the conversion of individual elements.

Well-Known Collection Mappers

For common RDF collection structures, use the predefined global constants instead of the verbose CollectionMapping.withItemMappers() syntax:

Recommended (using global constants):

@RdfProperty(SchemaBook.chapters, collection: rdfList)
@RdfProperty(SchemaBook.authors, collection: rdfSeq)
@RdfProperty(SchemaBook.topics, collection: rdfBag)
@RdfProperty(SchemaBook.formats, collection: rdfAlt)

Not recommended (verbose syntax), but equivalent:

@RdfProperty(SchemaBook.chapters, collection: CollectionMapping.withItemMappers(RdfListMapper))
@RdfProperty(SchemaBook.authors, collection: CollectionMapping.withItemMappers(RdfSeqMapper))

Available global constants:

• rdfList - Ordered RDF List structure (rdf:first/rdf:rest/rdf:nil)
• rdfSeq - RDF Sequence structure for numbered sequences
• rdfBag - RDF Bag structure for unordered collections
• rdfAlt - RDF Alternative structure for alternative values
• unorderedItems - Multiple triples (same as default auto behavior)
• unorderedItemsList - Multiple triples for List<T> specifically
• unorderedItemsSet - Multiple triples for Set<T> specifically

Examples

class Book {
  // Default: Multiple triples, one per chapter
  @RdfProperty(SchemaBook.chapters)
  final List<Chapter> chapters;

  // Structured RDF List (preserves order)
  @RdfProperty(SchemaBook.orderedChapters, collection: rdfList)
  final List<Chapter> orderedChapters;

  // RDF Sequence structure
  @RdfProperty(SchemaBook.authorSequence, collection: rdfSeq)
  final List<Person> authorSequence;

  // Default collection with custom item mapping
  @RdfProperty(
    SchemaBook.contributorIds,
    iri: IriMapping('{+baseUri}/person/{contributorId}')
  )
  final List<String> contributorIds; // Each ID → IRI, separate triples

  // Custom collection mapper
  @RdfProperty(
    SchemaBook.keywords,
    collection: CollectionMapping.mapper(StringListMapper)
  )
  final List<String> keywords; // Entire list handled as single value
}

Inheritance

• Object
• BaseMapping<Mapper>
• CollectionMapping

Constructors

CollectionMapping.auto()

Creates automatic collection mapping behavior.

const

CollectionMapping.fromRegistry()

Creates registry-based collection mapping.

const

CollectionMapping.mapper(Type mapperType)

Creates a reference to a collection mapper that will be instantiated from the given type.

const

CollectionMapping.mapperInstance(Mapper instance)

Creates a reference to a directly provided collection mapper instance.

const

CollectionMapping.namedMapper(String name)

Creates a reference to a named collection mapper that will be injected at runtime.

const

CollectionMapping.withItemMappers(Type mapperType)

Creates a reference to a collection mapper that will be instantiated from the given type.

const

Properties

factory → Type?

final

hashCode → int

The hash code for this object.

no setter, inherited

isAuto → bool

final

mapper → MapperRef<Mapper>?

Provides a MapperRef if a custom mapper is specified.

no setter, inherited

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