dzaleka-metadata-standard 1.1.0

An open-source metadata standard for documenting and sharing Dzaleka's digital heritage.

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 both a command-line interface (CLI) and a local premium Web UI (DMS Vault). 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 .

The Web UI (DMS Vault)

The easiest way to build, validate, and manage records is using the built-in local Web UI:

dms web --port 8080 --dir records/

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:

Field	Required	Description
id	✅	Unique identifier (UUID)
title	✅	Name of the item
type	✅	Category: story, photo, document, audio, video, event, map, artwork, site, poem
description	✅	Narrative context
language	✅	Language code (BCP 47)
creator	Recommended	Who created it (name, role, affiliation)
date	Recommended	When it was created or occurred
subject	Recommended	Controlled tags and keywords
subject_ref	Optional	Structured subject identifiers and scheme references
location	Recommended	Place name, area, coordinates
rights	Recommended	License, access level, holder
source	Optional	Contributor, collection, original format
format	Optional	MIME type of the digital object
technical	Optional	File-level technical metadata
relation	Optional	IDs of related records
relation_detail	Optional	Typed relationships to related records or resources
coverage	Optional	Time period covered

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
│   ├── 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:

Vocabulary	Prefix	Used for
Dublin Core	dc:, dcterms:	Core metadata fields (title, creator, subject, rights, etc.)
FOAF	foaf:	Person/Agent descriptions (foaf:name, foaf:Person, foaf:Image)
BIBO	bibo:	Bibliographic roles (bibo:editor, bibo:translator, bibo:interviewer)
Schema.org	schema:	Creative works, places, events, affiliations
W3C Geo	geo:	Geographic coordinates (geo:lat, geo:long)
SKOS	skos:	Subject vocabularies and concept schemes

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.