Knowledge Graphs — Entity Model Starter & Tagging Rules

Purpose and hunger

Teams need a simple, reliable entity model and tagging practice so people and systems can find decisions, experiments, evidence, and owners without chasing scattered files or ambiguous tags. This starter model balances usefulness with low friction: enough structure to be searchable and joinable, but lightweight enough for fast adoption and iterative governance.

Design principles

• Practical first: start with a small set of entities and attributes that solve common discovery needs.
• Explicit relationships: make why items are related explicit (e.g., “decision A was informed by experiment E”).
• Governed tags: tags are useful only when they’re consistently applied and owned.
• Incremental: treat the model and tags as living — refine based on usage metrics and user feedback.

Core entities (starter set)

Use these as the canonical types in your lightweight knowledge graph.

• Person
  • Required attributes: id, displayName, email (or directory id)
  • Optional: roleTitle, teamId, managerId
• Team / Role
  • Required: id, name
  • Optional: parentTeamId, function
• Decision
  • Required: id, title, decisionDate, status (proposed/approved/retired), ownerId
  • Optional: summary, rationale, impact, tags
• Experiment
  • Required: id, title, startDate, endDate (if complete), ownerId, outcome (success/partial/fail/unknown)
  • Optional: hypothesis, metrics, relatedDecisionIds, tags
• Artifact (documents, dashboards, code repos, reports)
  • Required: id, title, artifactType, location/URL, createdDate, ownerId
  • Optional: version, tags
• Project / Initiative
  • Required: id, name, startDate, sponsorId
  • Optional: status, tags

Core relationships (examples)

• Person —memberOf—> Team
• Decision —ownedBy—> Person (or Team)
• Experiment —informs—> Decision
• Artifact —documents—> Decision or Experiment
• Project —contains—> Experiment / Decision / Artifact
• Decision —supersedes—> Decision (for decision history)

Tagging rules (practical and enforceable)

Tags should be treated as lightweight metadata with governance. Use these rules to avoid folksonomy sprawl.

1. Canonical tag list: maintain a short, curated list of canonical tags (project, customer, product, domain, compliance, priority). Limit free‑form tags to user notes only.
2. Tag identifiers: tags have a stable id and a human label; avoid relying on label text alone (use slugs like product:payments).
3. Ownership: each tag has an owner (person or role) responsible for scope and synonyms.
4. Synonym mapping: map common synonyms to canonical tags (e.g., HQ, headquarters → location:headquarters).
5. Lifecycle: tags may be proposed, approved, deprecated; deprecated tags map automatically to canonical replacements where possible.
6. Minimum tagging: require at least one canonical tag for Decisions and Experiments (for discoverability). Optional tags may include impacted product, customer segment, and priority.

Automated tag propagation patterns

Automating sensible propagation reduces manual effort while keeping context intact. Apply these patterns conservatively and make rules visible to users.

• Project → Child artifacts: when an Artifact is created within a Project, inherit the Project's canonical tags (project id, product, sponsor).
• Decision ← Experiment: experiments that inform an approved Decision should propagate key experiment tags (metrics, customer cohort) onto the Decision's metadata as supporting evidence tags.
• Artifact → Linked artifacts: a finalized artifact (e.g., design doc) can push its version tag to related artifacts it replaces or updates.
• Authority last-write: for conflicting tags, preserve the tag authored by the Decision owner or Project sponsor unless a governance override occurs.

Simple example queries (teams)

Below are concise examples for a property graph (e.g., Neo4j / Cypher) and a relational fallback (SQL-ish pseudo queries). Adapt field and label names to your implementation.

Cypher (property graph) — find decision history and related experiments

-- Decisions related to Decision D123 and experiments that informed them
MATCH (d:Decision {id: 'D123'})-[:supersedes*0..]->(prev:Decision)
OPTIONAL MATCH (e:Experiment)-[:informs]->(prev)
RETURN prev.id AS decisionId, prev.title AS title, collect(e.id) AS experiments

SQL (relational join, simplified)

SELECT d.id, d.title, array_agg(e.id) AS experiments
FROM decisions d
LEFT JOIN experiment_decision ed ON ed.decision_id = d.id
LEFT JOIN experiments e ON e.id = ed.experiment_id
WHERE d.id = 'D123' OR d.supersedes = 'D123'
GROUP BY d.id, d.title;

Starter JSON-LD example (artifact linking to decision)

{
  "@context": "http://schema.org",
  "@type": "CreativeWork",
  "id": "artifact:A456",
  "name": "Payment API design doc",
  "creator": "person:P10",
  "about": ["decision:D123"],
  "tags": ["product:payments", "project:Q3-replatform"]
}

Governance checklist (practical rollout)

• Pick owners for the entity model and canonical tag list.
• Define a minimum metadata template for Decisions and Experiments and enforce during creation.
• Publish simple UI examples so users see how to tag when creating artifacts.
• Implement one or two propagation rules (Project→Artifact, Experiment→Decision) and monitor results for two sprints.
• Measure adoption: percent of Decisions with required tags, search success rate for common queries.
• Review tag usage monthly and retire or merge low‑value tags.

Common pitfalls and how to avoid them

• No owners: tags without owners become noisy — assign clear stewardship.
• Too many entities at once: avoid building a giant ontology at the start; iterate from the starter set.
• Over-automation: aggressive tag propagation can surface irrelevant tags — start small and make rules visible.
• Ambiguous identifiers: use stable ids (slugs, GUIDs) rather than free text in relationships and APIs.

Next steps for teams

1. Copy this starter model and map it to your existing metadata fields (wiki pages, document metadata, ticketing tags).
2. Pick a pilot area (one product team or project) and require the minimum metadata on new Decisions and Experiments for 6–8 weeks.
3. Collect feedback, tune the tag list, add one propagation rule, and measure discovery improvements.

Want a downloadable starter JSON schema or an interactive model builder (entity templates you can adapt)? See Capability Enhancements below for suggestions your platform team can implement.