Modelling Conventions

Modelling Conventions

Overview

This is the shared modelling-craft layer: the conventions, anti-patterns, and guardrails that are true of a good model whatever representation renders it — a conceptual model, a UML class diagram, a LinkML schema, or an OWL ontology. It exists for the same reason cosmic-python exists: one home for the craft that many skills reuse, so the rules are stated once and cited everywhere.

It carries principles, not mechanics. The concrete syntax that realises a principle in a given representation (LinkML slots:, UML association classes, OWL owl:ObjectProperty) belongs to the skill that owns that representation — this skill states what good looks like and why, and delegates how to the consuming skill.

Two principles here are load-bearing across every downstream skill; the rest of the craft supports them.

The two load-bearing principles

1. Decouple attributes from classes — model them as reusable, first-class properties

An attribute is not owned by a class. It is a concept in its own right — a property with its own meaning, definition, and identity — that classes reference. Define it once; reference it from every class that needs it. The moment the same attribute (same meaning) appears on a second class, redefining it inline is duplication that will drift.

Why it matters: reuse keeps meaning single-sourced, makes the model smaller and more consistent, and is exactly what lets a formal/semantic target (OWL/SHACL) treat properties as the first-class citizens they already are. See references/naming-and-identity.md.

2. Identify everything by a stable URI — implicit by default

Every modelled element — class, property, enumeration value — is identifiable by a stable URI, minted once at authoring time and never changed when the element is renamed or moved. Keep it implicit: derive it from a minted namespace + the element's name rather than writing an explicit URI literal, and make it explicit only when a specific value is required (reusing a published vocabulary term, for instance).

Why it matters: a model where everything is identified can be rendered to OWL and SHACL naturally and completely — no retrofitting identity later. Identity is a modelling decision, not a serialization detail.

The craft around them

• Naming — intention-revealing, consistent, singular-noun classes; the model's names become the project's ubiquitous language. Details and the per-representation casing table: references/naming-and-identity.md.
• Anti-patterns — free strings where a controlled set belongs, god-classes, validation buried in code instead of the model, flattening everything onto one class. See references/anti-patterns.md.
• Editor guardrails — the checks a modeller applies while working, before generating anything: references/editor-guardrails.md.

Boundary & Related Skills

This skill OWNS: representation-agnostic modelling conventions, modelling anti-patterns, the editor-guiding guardrails, and the two principles above (reusable properties; URI-everywhere) stated as principles.

This skill DELEGATES:

• The living conceptual model, UML conceptual data modelling, terminology, and the model-source decision → ../conceptual-modelling/SKILL.md.
• LinkML mechanics that realise these principles (top-level slots:, the URI-as-datatype artifice, generation) → ../linkml-engineering/SKILL.md.
• Representation-specific mechanics generally (UML profiles, OWL axioms) → the skill owning that representation. Nothing representation-specific belongs here.

Related: conceptual-modelling, linkml-engineering, architecture, cosmic-python (the same reuse-layer pattern for code).