IIIF.Manifest.Serializer.Net Documentation

Complete production-quality documentation for the IIIF Presentation API 2.0 manifest serialization library.

Documentation Structure

All 27 README files have been created following the comprehensive template with:

• ✅ Anchor-linked table of contents
• ✅ 2-5 sentence overview with IIIF context
• ✅ Files table (file | types | LOC | responsibility)
• ✅ Types & Members table
• ✅ Per-type details
• ✅ Mermaid diagrams (class hierarchies, sequence flows)
• ✅ Realistic IIIF examples with JSON output
• ✅ Cross-linked See Also sections

Documentation Index

Core Folders

1. Helpers – Utility methods for collections, JSON parsing, date handling, manifest metadata
2. Shared – Foundation types: TrackableObject, BaseItem, BaseNode, BaseContent hierarchies
3. Nodes – IIIF domain model: Manifest, Sequence, Canvas, Structure, annotations
4. Properties – IIIF metadata properties: Label, Description, Metadata, Service, etc.

Shared Foundation (8 READMEs)

• Shared/Trackable – TrackableObject pattern with ModifiedProperties tracking
• Shared/BaseItem – @context/@id/@type/service foundation
• Shared/BaseNode – 15+ metadata fields (label, description, thumbnail, etc.)
• Shared/Content – BaseContent hierarchy for annotations
• Shared/Content/Resources – BaseResource foundation for content resources
• Shared/Exceptions – Custom JSON validation exceptions
• Shared/FormatableItem – Items with format field
• Shared/ValuableItem – Simple string property wrappers

Nodes Domain Model (6 READMEs)

• Nodes/Manifest – Top-level IIIF resource with sequences, structures
• Nodes/Sequence – Ordered canvas collection with viewing direction
• Nodes/Canvas – Painting surface with dimensions, images
• Nodes/Structure – Hierarchical navigation (ranges)
• Nodes/Content – Annotation types overview

Content Annotations (8 READMEs)

• Nodes/Content/Image – Painting annotations linking ImageResource
• Nodes/Content/Image/Resource – Image resources with IIIF Image Service
• Nodes/Content/Embedded – Embedded text annotations
• Nodes/Content/Embedded/Resource – Text resources with chars/language
• Nodes/Content/Segment – Region annotations with selectors
• Nodes/Content/Segment/Resource – Segment resources
• Nodes/Content/Segment/Selector – xywh region selectors
• Nodes/Content/OtherContent – External annotation list links

Properties Metadata (9 READMEs)

• Properties/Description – Multi-language descriptions
• Properties/Metadata – Label-value metadata pairs
• Properties/Metadata/MetadataValue – Individual metadata values
• Properties/Rendering – Alternative format links (PDF, EPUB)
• Properties/Service – IIIF Image API service descriptors
• Properties/Tile – Deep-zoom tile specifications
• Properties/Within – Parent collection links
• Properties/Interfaces – IDimenssionSupport, IViewingDirectionSupport

Architecture Overview

TrackableObject Pattern

All domain types inherit from TrackableObject<T> which provides:

• SetPropertyValue: Reflection-based immutable property mutation
• ModifiedProperties: Dictionary tracking changed fields
• INotifyPropertyChanged/INotifyPropertyChanging: Change notification events

manifest.AddLabel(new Label("Title"))
        .SetThumbnail(thumbnail)
        .AddSequence(sequence); // Fluent chaining

JsonConverter Hierarchy

Custom converters enforce IIIF validation:

• TrackableObjectJsonConverter → clears ModifiedProperties, forces indented formatting
• BaseItemJsonConverter → validates @context/@id/@type required fields
• BaseNodeJsonConverter → parses 15+ metadata fields
• Domain converters → enforce resource/on/dimension requirements

IIIF Domain Model

Manifest (top-level)
  └─ Sequence (ordered views)
       └─ Canvas (painting surface with dimensions)
            ├─ Image (painting annotation)
            │    └─ ImageResource (with Service for deep-zoom)
            ├─ EmbeddedContent (text annotations)
            ├─ Segment (region annotations with Selector)
            └─ OtherContent (external annotation lists)

Key Features

1. IIIF Presentation API 2.0 Compliance: Full spec implementation with validation
2. Immutable Properties: All mutations through fluent SetPropertyValue pattern
3. Change Tracking: ModifiedProperties dictionary for dirty field detection
4. Single-or-Array Serialization: Converters emit arrays only when count > 1
5. Multi-Language Support: Description, MetadataValue with @value/@language
6. IIIF Image Service: Deep-zoom via Service/Tile with scaleFactors
7. Flexible Annotations: Image painting, embedded text, segment regions
8. Hierarchical Navigation: Structure/Range with canvas/range collections

Quick Start Example

using IIIF.Manifest.Serializer.Net;

// Create manifest
var manifest = new Manifest(
    "https://example.org/manifest",
    new Label("16th Century Manuscript")
).SetViewingDirection(ViewingDirection.RightToLeft);

// Add sequence with canvas
var sequence = new Sequence("https://example.org/seq1");
var canvas = new Canvas(
    "https://example.org/canvas/1",
    new Label("Folio 1r"),
    2000,  // height
    1500   // width
);

// Add image with IIIF Image Service
var imageResource = new ImageResource(
    "https://example.org/image.jpg",
    "image/jpeg"
).SetHeight(2000).SetWidth(1500);

var service = new Service(
    "http://iiif.io/api/image/2/context.json",
    "https://example.org/iiif/img1",
    "http://iiif.io/api/image/2/level1.json"
).AddTile(new Tile(512, new[] { 1, 2, 4, 8 }));

imageResource.SetService(service);

var image = new Image(
    "https://example.org/anno/1",
    imageResource,
    canvas.Id
);

canvas.AddImage(image);
sequence.AddCanvas(canvas);
manifest.AddSequence(sequence);

// Serialize to JSON
string json = JsonConvert.SerializeObject(manifest);

Documentation Standards

Each README includes:

1. Anchor TOC – Quick navigation to all sections
2. Overview – 2-5 sentences explaining purpose and IIIF context
3. Files Table – File paths, primary types, LOC, responsibilities
4. Types & Members Table – Type, kind, summary, inheritance, key members
5. Per-Type Details – Focused explanations of each type's role
6. Mermaid Diagrams – Class hierarchies and sequence flows
7. Examples – Realistic C# code with JSON output
8. See Also – Cross-links to parent/sibling/related documentation

Target Frameworks

• netstandard2.0 – Broad compatibility
• net451 – Legacy .NET Framework support

Dependencies

• Newtonsoft.Json – JSON serialization with custom converters

Build & Test

# Build library
dotnet build IIIF.Manifest.Serializer.Net.sln

# Run sample/benchmark
dotnet run --project src/IIIF.Manifest.Serializer.Net.Test

Contributing

When extending the library:

1. Inherit from appropriate base – TrackableObject → BaseItem → BaseNode → domain type
2. Use SetPropertyValue – All mutations through helper to track ModifiedProperties
3. Create custom JsonConverter – Validate required tokens, parse/write fields
4. Follow fluent pattern – Return this from all setters for chaining
5. Update documentation – Maintain README consistency across all folders

License

See LICENSE file in repository root.

---

Documentation Generated: Complete production-quality documentation set for IIIF.Manifest.Serializer.Net
Total README Files: 27
Coverage: All folders with comprehensive sections, diagrams, examples, cross-links