Implementation Options

There are three main ways to work with ZineCore2 metadata, each suited to different needs and technical capacity. Choose the approach that best fits your use case.

Quick Comparison

Option 1: Self-Host the Django Server

What it is: Download and run the open-source reference implementation on your own infrastructure.

How It Works

# Clone the repository
git clone https://github.com/ZineCore2/server.git
cd server/

# Run onboarding (interactive setup)
./onboarding.sh

# Start the server
./start.sh

# Server running at http://localhost:8000

Pros

• Full control — Your data, your servers
• Customizable — Extend models, add fields, modify behavior
• Production-ready — Battle-tested Django REST Framework
• Offline capable — Works without internet
• No usage limits — Scale as needed
• Open source — MIT licensed, modify freely

Cons

• Infrastructure required — Need servers (or cloud hosting)
• Maintenance burden — Updates, security patches, backups
• Technical expertise — Requires Python/Django knowledge
• Initial setup time — Hours to properly configure

Best For

• Institutions — Libraries, archives, universities
• Production systems — Public-facing catalogs
• Large collections — Thousands+ of records
• Custom requirements — Need to extend or modify
• Data sovereignty — Must control your data

Requirements

• Python 3.12+ with uv package manager
• PostgreSQL 16+ database
• Linux/macOS server (or Docker)
• Basic sysadmin skills (for production deployment)

Getting Started

1. Read the installation guide → Reference Implementation
2. Set up environment (database, Python, uv)
3. Configure settings (environment variables)
4. Run migrations and load vocabularies
5. Deploy with nginx + gunicorn (production) or Docker

Full Installation Guide →

Option 2: Build Your Own Implementation

What it is: Use the ZineCore2 specification (JSON Schemas, contexts, vocabularies) to build your own system in any language.

How It Works

1. Download schemas from Developer Downloads
2. Implement validation using JSON Schema libraries
3. Use vocabularies via API or static files
4. Add to your system (database, CMS, application)

Example: JavaScript/TypeScript

import Ajv from 'ajv';
import type { ZineCore2 } from './specs/types/ZineCore2';

// Load schema
const schema = await fetch('/specs/schemas/zinecore2.schema.json')
  .then(r => r.json());

// Validate records
const ajv = new Ajv();
const validate = ajv.compile(schema);

const myZine: ZineCore2 = {
  title: "My Zine",
  creator: ["creator_001"],
  subject: ["activism"],
  genre: ["political-zine"],
  date: "2024",
  language: ["en"],
  rights: "cc-by-4.0"
};

if (validate(myZine)) {
  // Save to your database
  await db.zines.insert(myZine);
} else {
  console.error(validate.errors);
}

Example: Python

import jsonschema
import requests

# Load schema
schema = requests.get('https://zinecore.org/specs/schemas/zinecore2.schema.json').json()

# Validate
my_zine = {
    "title": "My Zine",
    "creator": ["creator_001"],
    # ... more fields
}

try:
    jsonschema.validate(my_zine, schema)
    # Save to database
    db.zines.insert_one(my_zine)
except jsonschema.ValidationError as e:
    print(f"Invalid: {e.message}")

Pros

• Complete flexibility — Use any language, framework, database
• Integration — Add to existing systems
• Custom features — Build exactly what you need
• Performance — Optimize for your use case
• Standards compliant — Still interoperable via schemas

Cons

• Most work required — Build everything from scratch
• Maintain validation — Keep schemas updated
• API design — Must implement yourself
• Testing burden — Ensure compliance

Best For

• Custom integrations — Adding ZineCore2 to existing platforms
• Unique requirements — Features not in reference implementation
• Language constraints — Must use Java, Go, Ruby, etc.
• Existing infrastructure — Already have database/backend

Available Tools

Getting Started

1. Download artifacts → Downloads
2. Read specification → Specification
3. Implement validation using schema library
4. Use vocabularies via Vocabulary API
5. Test with validator → Schema Validator

Option 3: Use Just the Vocabularies

What it is: Use ZineCore2's controlled vocabularies for tagging/categorization without the full metadata structure.

How It Works

// Fetch subjects vocabulary
const subjects = await fetch('https://zinecore.org/api/vocabularies/subjects')
  .then(r => r.json());

// Use for autocomplete/tagging
const subjectCodes = subjects.terms.map(t => t.code);
// ["activism", "anarchism", "art", "feminism", ...]

// Store with your content
const myArticle = {
  title: "Understanding Zine Culture",
  tags: ["zines", "diy-culture", "publishing"],  // From subjects vocabulary
  genre: "article"
};

Pros

• Lightweight — Just use the vocabularies
• Easy integration — Works with any CMS or platform
• Standardized terms — Consistent categorization
• No complex schemas — Simple key-value tagging

Cons

• No validation — Can't verify full metadata compliance
• No relationships — Can't link creators to zines, etc.
• Limited interoperability — Not full ZineCore2 records

Best For

• Content management — WordPress, Ghost, static site generators
• Simple tagging — Blog posts, articles, websites
• Discovery — Subject/genre filtering
• Gradual adoption — Start simple, expand later

Available Vocabularies

Browse All Vocabularies →

Decision Matrix

Choose Self-Host if:

• ✅ You're an institution with IT resources
• ✅ You have a large collection (100+ records)
• ✅ You need production reliability
• ✅ You want full control over data
• ✅ You can maintain servers
• ❌ You lack technical expertise
• ❌ You want zero maintenance

Choose Build Your Own if:

• ✅ You have an existing system to integrate with
• ✅ You need features not in reference implementation
• ✅ You must use a specific language/framework
• ✅ You have development resources
• ❌ You want a quick solution
• ❌ You're just getting started

Choose Vocabularies Only if:

• ✅ You just need standardized terms
• ✅ You already have a content system
• ✅ You want lightweight integration
• ✅ You're not ready for full metadata
• ❌ You need full ZineCore2 compliance
• ❌ You need complex relationships

Hybrid Approaches

You can combine options:

Example 1: Vocabularies + Custom System

• Use ZineCore2 vocabularies for terms
• Store in your own database schema
• Export to full ZineCore2 format later

Example 2: Self-Host + Custom Extensions

• Run reference implementation
• Add custom fields to models
• Maintain ZineCore2 compliance for core fields

Example 3: Build Your Own + Vocabulary API

• Implement custom backend
• Use hosted vocabulary API for terms
• Validate with JSON Schemas

Next Steps

• Self-hosting? → Installation Guide
• Building your own? → Download Schemas
• Vocabularies only? → Vocabulary API