Adac Library — Usage Guide

Adac is the core .NET library for working with ADAC (Archival Digital Asset Container) files. It provides services for creating, reading, validating, and verifying .adac containers — self-describing, ZIP-based archival packages designed for long-term digital preservation.

The library is the foundation used by both the CLI and the REST API.

Table of Contents

• Prerequisites
• Installation
• Quick Start
• Service Registration
• Services
  • IAdacContainerWriter — Creating Containers
  • IAdacContainerReader — Reading and Extracting
  • IAdacValidator — Validating Containers
  • IAdacFixityService — Fixity and Checksums
• Models
  • AdacManifest
  • AdacCoreMetadata
  • AdacPackageDefinition
  • AdacChecksumManifest and AdacFixityReport
  • AdacProvenanceLog
  • AdacRegionAnnotation
  • AdacEditPipeline
  • AdacEncryptionDescriptor
• Validation
  • Validation Results
  • Validation Options
• Constants
• Typical Workflows
• Project Structure
• License

Prerequisites

• .NET 10 SDK or later.

Installation

Add a project reference from your application:

dotnet add reference path/to/Adac/Adac.csproj

Or, if the library is published as a NuGet package:

dotnet add package Adac

Quick Start

using Adac.Extensions;
using Adac.Models;
using Adac.Services;
using Adac.Validation;
using Microsoft.Extensions.DependencyInjection;

// 1. Set up DI
ServiceCollection services = new();
services.AddAdacCore();
using ServiceProvider sp = services.BuildServiceProvider();

// 2. Create a container
IAdacContainerWriter writer = sp.GetRequiredService<IAdacContainerWriter>();

AdacPackageDefinition package = new()
{
    Description = "Scanned photograph",
    CreatedBy = "my-app/1.0",
    CoreMetadata = new AdacCoreMetadata
    {
        Title = "Family portrait, 1923",
        Format = "TIFF",
    },
    Masters =
    {
        new AdacMasterSource
        {
            Id = "master_0001",
            SourceFilePath = @"C:\scans\photo.tif",
        },
    },
};

await writer.CreateAsync( @"C:\archives\photo.adac", package );

// 3. Read it back
IAdacContainerReader reader = sp.GetRequiredService<IAdacContainerReader>();

AdacManifest manifest = await reader.ReadManifestAsync( @"C:\archives\photo.adac" );
AdacCoreMetadata metadata = await reader.ReadCoreMetadataAsync( @"C:\archives\photo.adac" );

Console.WriteLine( $"Title: {metadata.Title}" );
Console.WriteLine( $"Masters: {manifest.Masters.Count}" );

// 4. Validate
IAdacValidator validator = sp.GetRequiredService<IAdacValidator>();
AdacValidationResult result = await validator.ValidateAsync( @"C:\archives\photo.adac" );

Console.WriteLine( result.IsValid ? "VALID" : "INVALID" );

// 5. Verify fixity
IAdacFixityService fixity = sp.GetRequiredService<IAdacFixityService>();
AdacFixityReport report = await fixity.VerifyAsync( @"C:\archives\photo.adac" );

Console.WriteLine( report.IsValid ? "Checksums OK" : "Checksum mismatch detected" );

Service Registration

All ADAC services are registered with a single extension method call:

using Adac.Extensions;

services.AddAdacCore();

This registers the following services as singletons (all implementations are stateless and thread-safe):

The method returns the IServiceCollection for chaining:

builder.Services
    .AddAdacCore()
    .AddLogging();

Services

IAdacContainerWriter — Creating Containers

Creates a new .adac container from an AdacPackageDefinition. The writer generates the manifest, core metadata, checksum manifest, and the full directory structure automatically.

IAdacContainerWriter writer = sp.GetRequiredService<IAdacContainerWriter>();

AdacPackageDefinition package = new()
{
    Description = "Two-page letter",
    CreatedBy = "my-app/1.0",
    CoreMetadata = new AdacCoreMetadata
    {
        Title = "Wartime correspondence, 1945",
        Format = "TIFF",
        Tags = ["correspondence", "wartime"],
        Rights = new AdacRights
        {
            Statement = "Public domain",
            License = "CC0-1.0",
        },
    },
    Masters =
    {
        new AdacMasterSource
        {
            Id = "master_0001",
            SourceFilePath = @"C:\scans\page_001.tif",
        },
        new AdacMasterSource
        {
            Id = "master_0002",
            SourceFilePath = @"C:\scans\page_002.tif",
        },
    },
};

await writer.CreateAsync( @"C:\archives\letter.adac", package );

Tracking progress

Pass an IProgress<AdacOperationProgress> to receive phase-by-phase updates:

Progress<AdacOperationProgress> progress = new( p =>
{
    Console.WriteLine( $"[{p.Phase}] ({p.Current}/{p.Total}) {p.CurrentFile}" );
} );

await writer.CreateAsync( @"C:\archives\letter.adac", package, progress );

Output:

[CopyingMasters] (1/2) page_001.tif
[CopyingMasters] (2/2) page_002.tif
[WritingChecksums] (1/1) provenance/checksums.json

Cancellation

All async methods accept an optional CancellationToken:

using CancellationTokenSource cts = new( TimeSpan.FromSeconds( 30 ) );
await writer.CreateAsync( outputPath, package, cancellationToken: cts.Token );

IAdacContainerReader — Reading and Extracting

Reads metadata, lists entries, and extracts files from existing containers.

Reading metadata

IAdacContainerReader reader = sp.GetRequiredService<IAdacContainerReader>();

// Manifest (required)
AdacManifest manifest = await reader.ReadManifestAsync( "archive.adac" );

// Core metadata (required)
AdacCoreMetadata metadata = await reader.ReadCoreMetadataAsync( "archive.adac" );

// Provenance log (optional — may be null)
AdacProvenanceLog? log = await reader.ReadProvenanceLogAsync( "archive.adac" );

// Checksum manifest (optional — may be null)
AdacChecksumManifest? checksums = await reader.ReadChecksumsAsync( "archive.adac" );

// Region annotation (optional — may be null)
AdacRegionAnnotation? regions = await reader.ReadRegionAnnotationAsync(
    "archive.adac", "regions/master_0001.regions.json" );

// Edit pipeline (optional — may be null)
AdacEditPipeline? edits = await reader.ReadEditPipelineAsync(
    "archive.adac", "edits/master_0001.edits.json" );

Listing entries

IReadOnlyList<string> entries = await reader.ListContentsAsync( "archive.adac" );

foreach ( string entry in entries )
{
    Console.WriteLine( entry );
}
// manifest.json
// metadata/core.json
// master/master_0001.tif
// provenance/log.json
// provenance/checksums.json

Extracting files

// Extract a single entry by its container-relative path
await reader.ExtractFileAsync( "archive.adac", "metadata/core.json", @"C:\output\core.json" );

// Extract a single master by ID
await reader.ExtractMasterAsync( "archive.adac", "master_0001", @"C:\output" );

// Extract all masters
await reader.ExtractAllMastersAsync( "archive.adac", @"C:\output\masters" );

IAdacValidator — Validating Containers

Validates a container against the ADAC 1.0 specification and returns structured findings.

Default validation (structure + checksums)

IAdacValidator validator = sp.GetRequiredService<IAdacValidator>();

AdacValidationResult result = await validator.ValidateAsync( "archive.adac" );

if ( result.IsValid )
{
    Console.WriteLine( "Container is valid." );
}
else
{
    foreach ( AdacValidationEntry entry in result.Errors )
    {
        Console.WriteLine( $"[{entry.Code}] {entry.Message}" );
    }
}

Custom validation options

AdacValidationOptions options = new()
{
    VerifyChecksums = false,            // Skip SHA-256 verification (faster)
    WarnOnMissingProvenanceLog = true,  // Warn if provenance/log.json is absent
    WarnOnMissingChecksums = true,      // Warn if provenance/checksums.json is absent
};

AdacValidationResult result = await validator.ValidateAsync( "archive.adac", options );

Inspecting findings by severity

// All findings
foreach ( AdacValidationEntry entry in result.Entries )
{
    Console.WriteLine( $"[{entry.Severity}] {entry.Code}: {entry.Message}" );
}

// Errors only
foreach ( AdacValidationEntry error in result.Errors )
{
    Console.WriteLine( $"ERROR: {error.Code} — {error.Message}" );
}

// Warnings only
foreach ( AdacValidationEntry warning in result.Warnings )
{
    Console.WriteLine( $"WARN: {warning.Code} — {warning.Message}" );
}

IAdacFixityService — Fixity and Checksums

Provides SHA-256 checksum computation, manifest generation, and container-level verification.

Verifying a container

IAdacFixityService fixity = sp.GetRequiredService<IAdacFixityService>();

AdacFixityReport report = await fixity.VerifyAsync( "archive.adac" );

Console.WriteLine( $"Valid:    {report.IsValid}" );
Console.WriteLine( $"Total:   {report.TotalFiles}" );
Console.WriteLine( $"Passed:  {report.VerifiedFiles}" );
Console.WriteLine( $"Failed:  {report.FailedFiles}" );
Console.WriteLine( $"Missing: {report.MissingFiles}" );

foreach ( AdacFixityMismatch m in report.Mismatches )
{
    if ( m.IsMissing )
    {
        Console.WriteLine( $"  MISSING: {m.Path}" );
    }
    else
    {
        Console.WriteLine( $"  MISMATCH: {m.Path}" );
        Console.WriteLine( $"    expected: {m.ExpectedChecksum}" );
        Console.WriteLine( $"    actual:   {m.ActualChecksum}" );
    }
}

Generating a checksum manifest

AdacChecksumManifest manifest = await fixity.GenerateManifestAsync( "archive.adac" );

foreach ( AdacFileChecksum file in manifest.Files )
{
    Console.WriteLine( $"{file.Checksum}  {file.Path}" );
}

Computing individual checksums

// From a file path
string hash = await fixity.ComputeChecksumAsync( @"C:\scans\photo.tif" );

// From a stream
using FileStream stream = File.OpenRead( @"C:\scans\photo.tif" );
string hash2 = await fixity.ComputeChecksumAsync( stream );

Models

AdacManifest

Represents the container manifest (manifest.json) — the single source of truth describing the contents and structure of an ADAC container.

AdacMasterEntry

AdacDerivativeEntry

AdacCoreMetadata

Represents the core metadata record (metadata/core.json) describing the digital artifact using Dublin Core-inspired fields.

AdacRights

AdacTechnicalMetadata

AdacAdministrativeMetadata

AdacPackageDefinition

Defines everything needed to create a new ADAC container. Pass an instance to IAdacContainerWriter.CreateAsync.

AdacMasterSource

AdacDerivativeSource

AdacOperationProgress

Reported during container creation via IProgress<AdacOperationProgress>.

AdacChecksumManifest and AdacFixityReport

AdacChecksumManifest

Represents the fixity manifest (provenance/checksums.json).

Each AdacFileChecksum contains:

AdacFixityReport

Returned by IAdacFixityService.VerifyAsync.

Each AdacFixityMismatch contains:

AdacProvenanceLog

Represents the provenance log (provenance/log.json) — a chronological record of actions taken on the artifact.

Each AdacProvenanceEvent contains:

Example — creating a container with provenance:

AdacPackageDefinition package = new()
{
    CreatedBy = "my-app/1.0",
    CoreMetadata = new AdacCoreMetadata { Title = "Deed of sale" },
    Masters = { new AdacMasterSource { Id = "master_0001", SourceFilePath = "deed.tif" } },
    ProvenanceLog = new AdacProvenanceLog
    {
        Events =
        {
            new AdacProvenanceEvent
            {
                Id = "evt-001",
                Type = "scan",
                Timestamp = DateTimeOffset.UtcNow,
                Actor = "Digitization Lab",
                Software = "Epson Scan v5.0",
            },
        },
    },
};

AdacRegionAnnotation

Represents region annotations (regions/<master>.regions.json) that annotate spatial, temporal, or volumetric parts of a master artifact.

Each AdacRegion contains:

AdacEditPipeline

Represents non-destructive edit instructions (edits/<master>.edits.json) stored as transformation parameters rather than altered pixels.

Each AdacEditOperation contains:

AdacEncryptionDescriptor

Describes that a stored file was pre-encrypted before being placed into the container. ADAC never performs encryption or decryption — this is purely informational metadata.

Example — packaging a pre-encrypted master:

AdacMasterSource encryptedMaster = new()
{
    Id = "master_0001",
    SourceFilePath = @"C:\vault\photo.tif.enc",
    Encryption = new AdacEncryptionDescriptor
    {
        Algorithm = "AES-256-GCM",
        KeyId = "vault://keys/archive-2025",
        OriginalMediaType = "image/tiff",
    },
};

SHA-256 fixity checksums cover the ciphertext, which is the correct behavior — the container verifies integrity of what is stored, not the original plaintext.

Validation

Validation Results

AdacValidationResult is returned by IAdacValidator.ValidateAsync and contains:

Each AdacValidationEntry contains:

Validation Options

Constants

The AdacConstants class in the Adac.Constants namespace exposes all well-known paths and values defined by the ADAC 1.0 specification:

Additionally, AdacConstants.JsonOptions provides the shared JsonSerializerOptions (camelCase, indented, nulls omitted) used for all ADAC JSON serialization.

Typical Workflows

Create, validate, and verify

// Create
AdacPackageDefinition package = new()
{
    CreatedBy = "my-app/1.0",
    CoreMetadata = new AdacCoreMetadata { Title = "Deed of sale, 1887" },
    Masters = { new AdacMasterSource { Id = "master_0001", SourceFilePath = "deed.tif" } },
};

await writer.CreateAsync( "deed.adac", package );

// Validate structure + checksums
AdacValidationResult result = await validator.ValidateAsync( "deed.adac" );

// Verify fixity independently
AdacFixityReport report = await fixity.VerifyAsync( "deed.adac" );

Read and inspect an existing container

AdacManifest manifest = await reader.ReadManifestAsync( "archive.adac" );
AdacCoreMetadata metadata = await reader.ReadCoreMetadataAsync( "archive.adac" );

Console.WriteLine( $"ADAC Version: {manifest.AdacVersion}" );
Console.WriteLine( $"Package ID:   {manifest.Id}" );
Console.WriteLine( $"Created:      {manifest.CreatedOn}" );
Console.WriteLine( $"Title:        {metadata.Title}" );
Console.WriteLine( $"Masters:      {manifest.Masters.Count}" );

foreach ( AdacMasterEntry master in manifest.Masters )
{
    Console.WriteLine( $"  {master.Id} -> {master.File}" );
}

Extract all masters for offline processing

await reader.ExtractAllMastersAsync( "archive.adac", @"C:\working-copies" );

Create a container with derivatives and rich metadata

AdacPackageDefinition package = new()
{
    CreatedBy = "imaging-pipeline/2.0",
    CoreMetadata = new AdacCoreMetadata
    {
        Title = "Historical photograph",
        Format = "TIFF",
        Technical = new AdacTechnicalMetadata
        {
            Scanner = "Epson Expression 12000XL",
            Dpi = 600,
            BitDepth = 48,
            ColorSpace = "AdobeRGB",
        },
        Administrative = new AdacAdministrativeMetadata
        {
            Repository = "National Archives",
            AccessionNumber = "2025-001-0042",
            DigitizedBy = "Digitization Lab",
            DigitizedOn = "2025-07-15T10:30:00Z",
        },
    },
    Masters =
    {
        new AdacMasterSource
        {
            Id = "master_0001",
            SourceFilePath = @"C:\scans\photo.tif",
            XmpSourceFilePath = @"C:\scans\photo.xmp",
        },
    },
    Derivatives =
    [
        new AdacDerivativeSource
        {
            Id = "deriv_0001",
            SourceFilePath = @"C:\output\photo_access.jpg",
            SourceMasterId = "master_0001",
            Purpose = "access",
        },
    ],
};

await writer.CreateAsync( "photo.adac", package );

Project Structure

Adac/
├── Adac.csproj                        # Class library (net10.0)
├── Constants/
│   └── AdacConstants.cs               # Well-known paths, versions, JSON options
├── Extensions/
│   └── ServiceCollectionExtensions.cs # AddAdacCore() DI registration
├── Models/
│   ├── AdacManifest.cs                # Manifest and master/derivative entries
│   ├── AdacCoreMetadata.cs            # Core metadata, rights, technical, admin
│   ├── AdacPackageDefinition.cs       # Package definition and source descriptors
│   ├── AdacChecksumManifest.cs        # Checksum manifest and fixity report
│   ├── AdacProvenanceLog.cs           # Provenance log and events
│   ├── AdacRegionAnnotation.cs        # Region annotations and bounds
│   ├── AdacEditPipeline.cs            # Non-destructive edit pipelines
│   └── AdacEncryptionDescriptor.cs    # Pre-encryption metadata
├── Services/
│   ├── IAdacContainerReader.cs        # Reader interface
│   ├── AdacContainerReader.cs         # Reader implementation
│   ├── IAdacContainerWriter.cs        # Writer interface
│   ├── AdacContainerWriter.cs         # Writer implementation
│   ├── IAdacValidator.cs              # Validator interface
│   ├── AdacValidator.cs               # Validator implementation
│   ├── IAdacFixityService.cs          # Fixity service interface
│   ├── AdacFixityService.cs           # Fixity service implementation
│   └── HashingStream.cs              # Internal stream wrapper for hashing
└── Validation/
    └── AdacValidationResult.cs        # Validation results, entries, options

License

Copyright © 2026 InnoVadens, LLC. All rights reserved.