Dzaleka Metadata Standard (DMS)

An open-source metadata specification and toolkit for describing, organising, and sharing digital heritage content from Dzaleka Refugee Camp.

What is DMS?

The Dzaleka Metadata Standard (DMS) is an open-source metadata specification and toolkit designed to describe, organise, and share digital heritage content from Dzaleka Refugee Camp in Malawi.

It provides a standardised, interoperable, and reusable schema for heritage items such as stories, photos, documents, audio, and events.

🧭 Purpose

The purpose of DMS is to:

• Enable consistent metadata creation for heritage assets
• Support discoverability, interoperability, and reuse of heritage data
• Provide tools to validate, manage, and export metadata
• Serve as an open standard for heritage documentation

DMS helps both technical systems and community contributors work with heritage content in a structured way.

📦 What DMS Includes

📌 Metadata Schema

A machine-readable specification defining fields, types, and constraints for heritage metadata.

Available formats:

• JSON Schema — dms/data/schema/dms.json (Draft 2020-12)
• YAML Schema — dms/data/schema/dms.yaml
• JSON-LD / RDF — dms/data/schema/dms.jsonld for semantic web / linked data use

🛠️ Python Tools & Web UI

A suite of tools for creating, validating, and converting metadata records. Includes a command-line interface and a local web workspace built with Kumo. See Quick Start below.

📖 Documentation

Field definitions, best practices, and tutorials for metadata entry. See Documentation.

📁 Example Records

Sample records covering stories, photos, documents, audio, and events. See Examples.

Quick Start

Installation

# Clone the repository
git clone https://github.com/Dzaleka-Connect/Dzaleka-Metadata-Standard.git
cd dzaleka-metadata-standard

# Install the CLI tools
pip install -e .

# Optional: full-screen terminal workspace
pip install -e ".[tui]"

The terminal workspace

In a real terminal, run dms with no arguments — the same way you would open Grok Build. It starts a full-screen, keyboard-first workspace for browsing local records, validation, vocabularies, and schema fields. Nothing is uploaded, and nothing on disk is changed.

dms
dms tui --dir examples/
dms tui --light

/ focuses search, Ctrl+P opens the command palette, Ctrl+T toggles the night and day themes, and Q quits. Use dms init, dms validate, and dms web when you need to create or edit records.

The Web UI

To create, validate, and manage records in a browser, start the local workspace:

dms web --port 8080 --dir records/

The DMS workspace includes a schema-driven editor, searchable records, JSON import, JSON/JSON-LD downloads, and a Vocabulary workspace for term lookups and structured references. Unsaved drafts are protected when switching to another record.

The Sources workspace can read published Dzaleka Services collections — including the Encyclopedia API — and prepare local drafts for review. Loading a collection is opt-in; local record contents are never uploaded. Review consent and reuse rights before sharing.

React and Kumo assets are bundled with the Python package. Node.js and a CDN connection are not needed to run the installed app. This is a localhost workspace, not an authenticated public hosting service. Rights metadata does not enforce filesystem access.

This also exposes a local vocabulary API at http://127.0.0.1:8080/api/taxonomy for DMS term lookups, deprecations, change logs, and JSON-LD/Turtle/RDF/XML output.

Create a Record via CLI

# Interactive wizard
dms init

# Skip type selection prompt
dms init --type poem

# Save to specific file
dms init --output my-record.json

Validate a Record

# Single file
dms validate examples/story.json

# All files in a directory
dms validate --dir examples/

Search & Analyze

# Search records by type, subject, or free-text
dms search --dir records/ --type poem -q "displacement"

# View collection analytics (types, languages, completion)
dms stats --dir records/

# Generate a browsable HTML catalogue of your collection
dms report --dir records/ --output catalogue.html

Interoperability Tools

# Export record(s) as JSON-LD for semantic web
dms export examples/story.json

# Convert CSV batch to JSON records
dms convert csv2json examples/batch.csv

# Compare two records field-by-field
dms diff record_v1.json record_v2.json

View Schema Info

dms info

Schema Overview

A DMS record describes a single heritage item with these fields:

All fields map to Dublin Core for broad interoperability, with Dzaleka-specific extensions for camp areas and access levels.

Repository Structure

├── dms/                 Python CLI tools
│   ├── cli.py           Command entry points
│   ├── terminal.py      Full-screen terminal workspace
│   ├── validator.py     Schema validation engine
│   ├── generator.py     Interactive record creator
│   ├── converter.py     CSV ↔ JSON converter
│   └── taxonomy.py      Local vocabulary service and serializers
│
│   data/schema/         Schema definitions
│   ├── dms.json         JSON Schema (Draft 2020-12)
│   ├── dms.yaml         YAML version
│   └── dms.jsonld       JSON-LD context for linked data
│
│   data/taxonomy/       DMS vocabulary files
│   └── types.json       Curated heritage item type vocabulary
│
├── docs/                Documentation
│   ├── field-guide.md   Field definitions & guidelines
│   ├── best-practices.md Metadata entry best practices
│   ├── semantic-tagging.md Controlled vocabularies and richer subject metadata
│   ├── taxonomy-api.md  Local vocabulary API endpoints and formats
│   └── getting-started.md Installation & tutorial
│
├── examples/            Sample records
│   ├── story.json       Oral history
│   ├── photo.json       Photograph
│   ├── document.json    Administrative record
│   ├── audio.json       Music recording
│   ├── event.json       Community event
│   ├── site.json        Heritage site (Site Register)
│   ├── mural.json       Public artwork (Art Catalogue)
│   ├── poem.json        Poetry
│   └── batch.csv        CSV batch import example
│
└── tests/               Test suite

Examples

The examples/ directory contains sample records for common heritage item types:

• story.json — "Journey to Dzaleka: A Story of Hope" (oral history)
• photo.json — "Market Day at Dzaleka" (daily life photography)
• document.json — "Community School Registration Records, 2018"
• audio.json — "Traditional Songs of the Great Lakes Region"
• event.json — "World Refugee Day Celebration 2024"
• site.json — "Dzaleka Health Centre" (from Site Register)
• mural.json — "Child Early Marriage Awareness Mural" (from Art Catalogue)
• poem.json — "Home Is a Word I Carry" (poetry)
• batch.csv — Records in CSV format for batch import

Documentation

• Field Guide — Detailed definitions for every schema field
• Best Practices — Guidelines for quality metadata entry
• Semantic Tagging — DMS guidance for controlled vocabularies and richer subject metadata
• Taxonomy API — Query vocabularies, terms, deprecations, and semantic formats
• Getting Started — Installation and first steps tutorial

Interoperability

DMS is designed to work with existing standards and systems. The dms.jsonld context enables linked data publishing with mappings to:

Additional format support:

• CSV — Import/export for spreadsheet-based workflows
• JSON Schema — Machine-readable validation for any language or platform

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Areas where you can help:

• 📝 Adding example records from the Dzaleka community
• 🌐 Translating documentation into Swahili, French, or Kinyarwanda
• 🔧 Improving the CLI tools
• 📖 Writing guides for specific use cases
• 🐛 Reporting bugs and suggesting improvements

License

• Code (Python tools): MIT License
• Schema & Documentation: Creative Commons Attribution 4.0

Acknowledgments

• The Dzaleka refugee community for their heritage, stories, and resilience
• Dublin Core Metadata Initiative for the foundational metadata standard
• All contributors and volunteers who help preserve Dzaleka's digital heritage

Preserving heritage. Empowering community. Building the future.