Knowledge Architecture: Minimal Metadata Specification

Purpose

This minimal metadata specification helps teams make knowledge artifacts (guides, procedures, experiments, decision records, datasets, playbooks) findable, reusable, and maintainable without creating a heavy taxonomy project. The goal is a small, practical set of fields you can apply consistently across a site, collection, or domain so content stays discoverable, traceable, and actionable.

How to use this spec

Apply this as a lightweight template when creating or importing content. Use enforcement levels (required / recommended / optional) to match local maturity. Keep vocabularies small and govern them lightly—start simple and evolve the set through usage and regular review.

Minimal fields (recommended enforcement)

1. title (required) — Clear, human-friendly title. Prefer action or outcome language for procedures and playbooks.
2. summary (required) — 1–3 sentence description of what the artifact is for and who should use it. Helps scan results and card views.
3. audience (required) — Who should read or act on this? Use concise roles or groups (e.g., PlantOperators, Managers, Educators).
4. contentType (recommended) — One of: Procedure, Policy, Playbook, Experiment, DecisionRecord, Dataset, Report, FAQ. Enables filtering and lifecycle rules.
5. topics / tags (required) — Short list of subject tags drawn from a small controlled list plus free tags. Use hierarchical topic keys where useful (e.g., Quality/OEE).
6. lifecycleStage (required) — Draft, InReview, Published, Deprecated, Archive. Drives visibility and refresh workflows.
7. owner (required) — Primary accountable person or role and a contact (email or team handle). Ownership drives maintenance and approvals.
8. contributors (recommended) — People who substantially contributed; useful for follow-up and context.
9. decisionRecordsReferenced (recommended) — Links/IDs to Decision Records that justify or constrain this artifact. Strengthens auditability and traceability.
10. relatedExperiments (optional) — Links/IDs to experiments or pilots that produced evidence for the content.
11. readTime (recommended) — Estimated minutes to read. Improves triage and engagement.
12. lastFreshnessCheck / nextReviewDate (required) — Date of last review and scheduled next review. Automate reminders where possible.
13. version (recommended) — Semantic or simple incremental version; capture changelog link when relevant.
14. permissions / visibility (required) — Who can read, comment, edit, and approve. Reference a policy (e.g., public/internal/restricted).
15. canonicalLocation / canonicalId (recommended) — If this content is a copy or variant, point to the canonical source to avoid fragmentation.

Field notes and examples

Keep values short and machine-friendly where possible (use stable keys for topics and stages). When linking to other artifacts, prefer stable IDs/URLs rather than free text.

Sample tag set and vocabulary guidance

Start with a short controlled topic list (20–50 entries) that maps to business domains. Allow 0–3 free tags per artifact for local specificity. Avoid deep rigid taxonomies at the start—use broad categories and let usage data drive refinement.

• Example high-level topics: Operations, Maintenance, Quality, Safety, HR, Training, Product, Compliance, R&D, Analytics
• Tagging rules: use singular nouns, CapitalizedCamelCase for keys, prefer existing corporate terms.

Enforcement levels and UI hints

Not every field needs coercive enforcement. Use the following pattern:

• Required — Prevent publish or display without the field (title, summary, audience, topics, lifecycleStage, owner, permissions, lastFreshnessCheck).
• Recommended — Strong UI prompt and visual hint; allow publish with override (contentType, readTime, version, contributors).
• Optional — Helpful metadata captured when available (relatedExperiments, decisionRecordsReferenced where one exists).

Governance and maintenance

• Ownership — Each artifact must have an owner responsible for reviews and lifecycle decisions.
• Review cadence — Define default cadences by contentType (e.g., Procedures: annual; Policies: biennial; Experiments: as needed). Use the nextReviewDate to schedule reminders.
• Metadata audits — Periodic automated checks for missing required fields, stale nextReviewDates, and broken links. Surface results to owners and the domain librarian.
• Change log — When content changes materially, update version and change note. Link to approval decisions when applicable.
• Onboarding — Provide templates and a short creator checklist that populates metadata automatically when possible.

Implementation patterns (capability-aware)

• Use an interactive metadata form to capture these fields on creation and edits. Render the form via the platform's Interactive Form Rendering capability so entries are consistent and accessible.
• Store submitted metadata using the Content Data Submission and JSON Storage endpoint for auditability and later reporting (search index, dashboards, exports).
• Expose metadata to search and filters: make topics, contentType, lifecycleStage, owner, and permissions indexable fields.
• Bundle this spec as a reusable Domain or Toolkit so teams can copy and adapt it to their local Hungers—preserve adaptability rather than enforcing a single enterprise standard.
• Automate freshness checks and review reminders from stored nextReviewDate, and tie decisionRecordsReferenced relations into the Decision Log so changes are traceable.

Practical next steps

1. Adopt the required fields and create an interactive metadata form template.
2. Define a small site-level topic list and map existing tags to it.
3. Run a metadata audit to tag missing required fields and contact owners to fix.
4. Set up automated reminders using nextReviewDate and require owner acknowledgement for deprecated content before archive.
5. Iterate: review tag usage quarterly and prune or expand controlled vocabularies based on actual search and reuse patterns.

Design cautions (mal-hungers)

Avoid over‑engineering. Large rigid taxonomies, requiring long forms on every content edit, or enforcing unwieldy ownership processes will choke adoption. Start small, measure, and evolve with usage signals. This spec is a pragmatic starting point—not a one-time top-down governance project.

End of specification.