Skip to main content

Metadata Schema

Standard frontmatter (YAML metadata) fields used across all EGI documentation. Consistent metadata improves searchability, organization, and automated processing.

Quick Start

Copy the appropriate template below and replace placeholder values. All dates use YYYY-MM-DD format.

Why Metadata Matters​

  • Search: Helps users find relevant documents
  • Organization: Enables automatic categorization
  • Context: Provides document history and ownership
  • Automation: Enables scripts to process documents
  • Discovery: Surfaces related documentation

Universal Fields​

These fields are used across all document types:

Required Fields​

title: "Document Title"
description: "Brief description of the document content (1-2 sentences)"

Rules:

  • title: Clear, descriptive title (avoid generic terms)
  • description: 1-2 sentences, used in search results and previews
author: "Author Name"
date_created: YYYY-MM-DD
last_updated: YYYY-MM-DD
tags: [tag1, tag2, tag3]

Rules:

  • author: Full name of primary author
  • date_created: Date document was first created
  • last_updated: Date of last significant update
  • tags: 3-5 relevant tags for discoverability

Optional Universal Fields​

id: unique-document-id
sidebar_position: 1
sidebar_label: "Custom Label"

Rules:

  • id: Unique identifier (kebab-case), used for linking
  • sidebar_position: Number controlling sidebar order
  • sidebar_label: Override title in sidebar navigation

Document Type: SOP​

Standard Operating Procedures

---
title: "[Action] [System/Process]"
description: "Brief description of what this SOP covers"
category: sop
tags: [sop, system-name, process-type]
author: "Author Name"
date_created: YYYY-MM-DD
last_updated: YYYY-MM-DD
version: "1.0"
status: draft | active | deprecated
reviewed_by: "Reviewer Name"
approved_by: "Approver Name"
next_review: YYYY-MM-DD
---

Additional Rules:

  • version: Semantic versioning (1.0, 1.1, 2.0)
  • status: Current document state
    • draft - Under development
    • active - Currently in use
    • deprecated - No longer recommended
  • reviewed_by: Person who reviewed for accuracy
  • approved_by: Person who approved for use
  • next_review: Date document should be reviewed

Example:

---
title: "Deploy Production Website"
description: "Standard procedure for deploying changes to the production website"
category: sop
tags: [sop, deployment, website, production]
author: "Jane Smith"
date_created: 2024-01-15
last_updated: 2024-03-20
version: "2.1"
status: active
reviewed_by: "John Doe"
approved_by: "Tech Lead"
next_review: 2024-06-20
---

Document Type: System Profile​

System documentation and overview

---
title: "[System Name] Profile"
description: "Brief description of the system"
category: system-profile
tags: [system, profile, system-type]
author: "Author Name"
date_created: YYYY-MM-DD
last_updated: YYYY-MM-DD
version: "1.0"
system_owner: "Owner Name"
system_criticality: low | medium | high | critical
tech_stack: [Next.js, PostgreSQL, Vercel]
---

Additional Rules:

  • system_owner: Person responsible for the system
  • system_criticality: Business impact level
  • tech_stack: Array of main technologies used

Example:

---
title: "FPD Dashboard System Profile"
description: "Field project dashboard for tracking project locations and status"
category: system-profile
tags: [system, profile, dashboard, internal-tool]
author: "John Doe"
date_created: 2023-06-10
last_updated: 2024-03-15
version: "3.0"
system_owner: "Jane Smith"
system_criticality: high
tech_stack: [Next.js, PostgreSQL, Vercel, PostHog]
---

Document Type: Runbook​

Operational procedures for incidents

---
title: "[System] [Scenario] Runbook"
description: "Procedures for handling [scenario]"
category: runbook
tags: [runbook, system-name, incident-type]
author: "Author Name"
date_created: YYYY-MM-DD
last_updated: YYYY-MM-DD
system: "System Name"
severity: P0 | P1 | P2 | P3 | P4
on_call: "On-call contact or rotation"
---

Additional Rules:

  • system: Which system this runbook covers
  • severity: Typical severity of incidents this addresses
  • on_call: Who to contact or where to find on-call info

Example:

---
title: "API Server Downtime Runbook"
description: "Procedures for responding to API server outages"
category: runbook
tags: [runbook, api, downtime, incident]
author: "DevOps Team"
date_created: 2023-09-01
last_updated: 2024-03-10
system: "Company API"
severity: P0
on_call: "See PagerDuty rotation"
---

Document Type: Execution Brief​

Project planning document

---
title: "[Project Name] Execution Brief"
description: "Brief description of the project"
category: execution-brief
tags: [project, brief, project-type]
author: "Author Name"
date_created: YYYY-MM-DD
last_updated: YYYY-MM-DD
status: draft | active | completed
project_lead: "Name"
start_date: YYYY-MM-DD
target_date: YYYY-MM-DD
---

Additional Rules:

  • status: Project status (draft, active, completed)
  • project_lead: Primary person responsible
  • start_date: Project start date
  • target_date: Target completion date

Document Type: Incident Report​

Post-incident analysis

---
title: "[Date] - [Service] Incident Report"
description: "Brief description of the incident"
category: incident-report
tags: [incident, postmortem, service-name]
author: "Author Name"
date_created: YYYY-MM-DD
incident_date: YYYY-MM-DD
severity: P0 | P1 | P2 | P3 | P4
status: draft | under review | published
duration: "X hours Y minutes"
affected_users: number or percentage
---

Additional Rules:

  • incident_date: When incident occurred
  • severity: Incident severity level
  • status: Report status
  • duration: How long incident lasted
  • affected_users: Impact scope

Document Type: Checklist​

Procedural checklists

---
title: "[Process/System] Checklist"
description: "Checklist for [process]"
category: checklist
tags: [checklist, process-type]
author: "Author Name"
date_created: YYYY-MM-DD
last_updated: YYYY-MM-DD
checklist_type: migration | deployment | audit | onboarding | other
---

Additional Rules:

  • checklist_type: Type of checklist for categorization

Document Type: ADR​

Architecture Decision Record

---
title: "ADR-XXX: [Decision Title]"
description: "Brief description of the architectural decision"
category: adr
tags: [adr, architecture, decision-area]
author: "Author Name"
date_created: YYYY-MM-DD
status: proposed | accepted | deprecated | superseded
superseded_by: ADR-YYY (if applicable)
---

Additional Rules:

  • status: Decision status
    • proposed - Under discussion
    • accepted - Approved and in use
    • deprecated - No longer recommended
    • superseded - Replaced by another ADR
  • superseded_by: ADR that replaces this one

Tag Taxonomy​

Standardized tags for consistency:

Document Type Tags​

  • sop - Standard Operating Procedure
  • system - System profile
  • runbook - Operational runbook
  • incident - Incident report
  • project - Project documentation
  • adr - Architecture decision
  • checklist - Procedural checklist
  • template - Document template

Technology Tags​

  • next-js, react, node, python, typescript
  • postgresql, mongodb, redis
  • vercel, aws, cloudflare
  • docker, kubernetes

Process Tags​

  • deployment, migration, backup, monitoring
  • security, performance, testing
  • onboarding, training

System Tags​

  • website, api, dashboard, internal-tool
  • production, staging, development
  • client-facing, internal

Priority/Status Tags​

  • critical, high-priority, low-priority
  • active, deprecated, archived
  • draft, review, published

Status Values​

Standardized status values across document types:

Universal Status​

  • draft - Work in progress, not yet ready
  • review - Ready for review
  • active - Current and in use
  • deprecated - No longer recommended
  • archived - Kept for historical reference

SOP-Specific Status​

  • proposed - Suggested new procedure
  • approved - Approved but not yet active
  • active - Currently in use
  • deprecated - Being phased out
  • archived - No longer used

Project Status​

  • planning - In planning phase
  • active - Currently executing
  • on-hold - Temporarily paused
  • completed - Successfully finished
  • cancelled - Discontinued

Incident Status​

  • draft - Report being written
  • under-review - Being reviewed by team
  • published - Final and published
  • action-items-pending - Follow-ups outstanding
  • closed - All actions complete

Best Practices​

Writing Good Titles​

Good:

  • "Deploy Production Website SOP"
  • "FPD Dashboard System Profile"
  • "API Downtime Runbook"

Bad:

  • "Deployment" (too vague)
  • "The Process for Deploying" (unnecessary words)
  • "SOP-001" (not descriptive)

Writing Good Descriptions​

Good:

  • "Step-by-step procedure for deploying the production website, including pre-deployment checks and rollback procedures"
  • "Overview of the FPD Dashboard system including architecture, tech stack, deployment, and monitoring"

Bad:

  • "About deployment" (too vague)
  • "This document describes the complete comprehensive and detailed process for how we handle deployments in our organization" (too long)

Choosing Tags​

Rules:

  1. Use 3-5 tags per document
  2. Include document type tag
  3. Include system/technology tags
  4. Include process tags
  5. Don't over-tag

Good:

tags: [sop, deployment, website, vercel, production]

Bad:

tags: [sop, deployment, deploy, website, web, site, vercel, production, prod, important, critical, must-read]

Maintaining Dates​

  • Update last_updated for significant changes only
  • Don't update for typo fixes or minor edits
  • Update next_review when document is reviewed
  • Use ISO 8601 format: YYYY-MM-DD

Validation​

Required Field Check​

Every document MUST have:

  • title
  • description

Every document SHOULD have:

  • author
  • date_created
  • last_updated
  • tags (3-5 tags)

Document Type Check​

Documents of specific types MUST include type-specific required fields:

  • SOPs: category, version, status
  • System Profiles: system_owner, system_criticality
  • Runbooks: system, severity
  • Incident Reports: incident_date, severity

Automated Processing​

This metadata enables automated features:

Search & Discovery​

// Find all production SOPs
category: sop AND tags: production

// Find all critical systems
category: system-profile AND system_criticality: critical

// Find all P0 runbooks
category: runbook AND severity: P0

Stale Document Detection​

// Documents not updated in 6 months
last_updated < (today - 180 days)

// Documents past review date
next_review < today

Changelog Generation​

// Recent changes
last_updated >= (today - 30 days)
ORDER BY last_updated DESC

Examples​

Complete SOP Example​

---
title: "Rotate Database Credentials"
description: "Procedure for rotating database passwords and updating all dependent systems"
category: sop
tags: [sop, database, security, credentials]
author: "DevOps Team"
date_created: 2023-05-15
last_updated: 2024-03-20
version: "1.2"
status: active
reviewed_by: "Security Team"
approved_by: "CTO"
next_review: 2024-09-20
---

Complete System Profile Example​

---
title: "Company Website System Profile"
description: "Marketing website built with Next.js, deployed on Vercel, with PostHog analytics"
category: system-profile
tags: [system, profile, website, next-js, vercel]
author: "Web Team"
date_created: 2022-03-10
last_updated: 2024-03-18
version: "4.0"
system_owner: "Marketing Lead"
system_criticality: high
tech_stack: [Next.js 14, TypeScript, Tailwind CSS, Vercel, PostHog, Uptime Kuma]
---

Contributing​

To suggest changes to the metadata schema:

  1. Discuss with the team
  2. Consider impact on existing documents
  3. Update this schema document
  4. Update relevant templates
  5. Announce changes to documentation authors

Resources​