Semantic Checks

Semantic Checks help you maintain high-quality, consistent models by identifying potential issues in your terms and relations. These checks are primarily designed for Semantic Modeling but can be applied to other types of graphs as well.

Overview

Access semantic checks via Tools > Semantic Checks

When you select a check, you'll see a screen with the check title and two icons:

• Refresh icon: Recalculates the terms that match the check. Use this after making changes to your graph while the sidebar is open
• Select terms: Selects all matched terms (shown in the list below) in the graph

Prerequisites

Some checks require specific configuration to work properly:

• Relation Types: Map your relations to types like "Generalization" and "Attributive" in Relation Type settings
• Term Types: Classify terms as "Concept" or "Property" in the Term Details tab
• Inheritance: Enable in Document Settings for checks involving parent-child relationships

---

Plurals in name

Lists all term names that are in plural form.

Why this matters

While there might be rare exceptions or specific modeling methodologies that allow for plural terms in certain contexts, the general consensus in semantic modeling favors singular term names. This promotes a cleaner, more consistent, and less ambiguous representation of your domain knowledge:

• Focus on the Concept: Singular terms represent a distinct concept. "Customer" directly refers to the idea of a customer, with its inherent properties and relations, making the model more abstract and focused on fundamental building blocks.

• Avoid Ambiguity: Plural forms can be ambiguous. Does "Products" refer to the general concept or a specific collection of multiple instances? Using the singular "Product" clearly denotes the concept itself. Multiple instances are represented through relations (e.g., a "Customer" has many "Order" instances).

• Consistency and Predictability: Employing singular forms creates a more consistent and predictable modeling style. Once established, it becomes easier for everyone to understand terms and create new ones following the same pattern.

• Alignment with Instance Representation: In data storage and programming contexts, you typically deal with individual instances of concepts. Using singular terms aligns better with how you'll represent these individual records or objects.

• Easier Relation Naming: Singular terms lead to more natural and readable relation names. For example, Customer places Order is clearer than "Customers place Orders."

• Reduced Redundancy: When defining properties of a term, you describe characteristics of a single instance. It's more natural to say "Product has a Name" rather than "Products have a Name."

What to do

1. Review each term flagged by this check
2. Rename plural terms to their singular form (e.g., "Customers" → "Customer")
3. Verify that relations involving renamed terms still make sense
4. Update any descriptions that reference the old plural name

Modeling Principle

Think of your semantic model as a vocabulary for describing your domain. Just as you define the meaning of a single word, you define the meaning of a single concept. You then use relations to express how multiple instances of these concepts interact.

Similar Term Names

Lists terms with the same name or very similar names (Levenshtein distance < 3) that may be duplicates, typos, or need differentiation.

Why this matters

Duplicate names

• Confusion and Ambiguity: When two different terms share the same name, it becomes impossible to know which concept is being referenced in any given context. This leads to misinterpretations, errors in reasoning, and difficulties in communication. For example, discussing "Account" when it could refer to either a user account or a financial account creates confusion.

• Hindrance to Logical Reasoning: Semantic models are often used for logical inference and querying. Without unique names, it becomes difficult to formulate precise queries or draw accurate conclusions. The system cannot distinguish between identically named concepts.

• Data Integration Challenges: When mapping your semantic model to underlying data sources, duplicate term names create significant problems. How do you know which database table or data field corresponds to which concept if they share the same name?

• Tooling and Technology Limitations: Many semantic modeling tools rely on unique identifiers for terms. Duplicate names can cause errors, warnings, or unexpected behavior within these systems. This check uses edit distance algorithms to find term pairs that are nearly identical, helping you maintain a clean, professional model:

Very similar names

• Catch Typos: The most common reason for similar names is simple typing errors. Finding these helps maintain a professional, error-free model.

• Identify Near-Duplicates: Sometimes terms are accidentally created with slightly different names ("Product Info" vs "ProductInfo") when they represent the same concept.

• Highlight Ambiguity: Very similar names might indicate that two concepts need clearer differentiation. If "Account" and "Accounts" both exist, it's unclear whether they represent different concepts or if one is simply a plural form.

• Improve Searchability: Similar names can make it harder to find the right term when searching or browsing the model.

How it works

This check uses the Levenshtein edit distance algorithm:

1. Compares every term name with every other term name
2. Calculates the edit distance (number of character changes needed to transform one name into the other)
3. Flags pairs with an edit distance of less than 3
4. Calculates a similarity percentage for each pair
5. Groups results by similarity level:
   • 🔴 High (>85%): Very likely a typo or duplicate
   • 🟠 Medium (70-85%): Possibly related or needs review
   • 🟡 Low (<70%): Might be coincidentally similar

Example: "Customer" and "Costumer" have an edit distance of 1 (one letter different) and would be flagged as highly similar.

What to do

1. Review each pair, starting with high similarity matches
2. For typos:
   • Fix the misspelled term name to match the correct one
   • Merge or delete the incorrect term
3. For duplicates:
   • If both terms represent the same concept, consolidate their relations and delete one
   • Update any descriptions referencing the deleted term
4. For intentional differences:
   • Make the names more distinct to avoid confusion (e.g., "User Account" vs "Financial Account")
   • Add clarifying descriptions explaining the difference
5. Use the filter dropdown to show only high, medium, or low similarity pairs

Critical Issue

Duplicate names are a fundamental modeling error that can cause serious issues in reasoning, integration, and communication. Address these immediately.

Start with High Similarity

Filter to show only high similarity pairs (>85%) first. These are most likely typos or duplicates that need immediate attention. Then work your way down to medium and low similarity matches.

Poor Description Quality

Lists terms with descriptions that are missing, too short, repeat the term name, contain placeholder text, or have other quality issues.

Why this matters

A good description should provide meaningful context and detail about what a term represents. This check identifies descriptions that fail to meet basic quality standards, helping you improve the overall documentation of your model:

• Professional Documentation: High-quality descriptions make your model more professional and easier to understand for all stakeholders.

• Knowledge Transfer: Good descriptions help new team members quickly understand the model without requiring extensive explanation.

• Reduced Ambiguity: Detailed descriptions prevent misinterpretations and ensure everyone has the same understanding of each term.

• Future Maintainability: Well-documented models are easier to maintain and evolve over time as requirements change.

• Stakeholder Communication: Clear descriptions facilitate better communication with non-technical stakeholders and domain experts.

How it works

The quality analyzer examines multiple aspects of each description and assigns a score from 0-100 based on:

• Missing: Empty descriptions
• Too Short: Descriptions under 20 characters often lack sufficient detail
• Repeats Name: Descriptions like "Customer" for a term named "Customer" provide no additional information
• Starts with Article + Name: "A Customer" or "The Customer" without further detail is lazy documentation
• No Punctuation: Descriptions without periods or other punctuation are often incomplete thoughts
• Placeholder Text: Contains words like "TODO", "TBD", "fill in", "update this", "XXX", or "FIXME"
• Generic Phrases: Starts with vague phrases like "is a type of" or "used for" without specifics
• One Word Only: Single-word descriptions rarely provide useful context
• All Uppercase/Lowercase: Poor formatting that suggests hasty or incomplete documentation

Each term receives a quality score badge:

• 🔴 Poor (0-30): Multiple serious issues
• 🟠 Fair (31-60): Some issues that should be addressed
• 🟡 Good (61-100): Minor issues or stylistic suggestions

What to do

1. Click on terms to expand and see the specific issues identified
2. Review the current description shown in the preview
3. Rewrite the description to:
   • Provide sufficient detail
   • Explain what the term represents, not just repeat its name
   • Add proper punctuation and formatting
   • Remove placeholder text
   • Be specific about the term's role, purpose, or characteristics
4. Reference the parent term if applicable (see No parent in description)
5. Include examples when helpful to clarify the concept
6. Refresh the check to verify improvements

Good description examples:

❌ Poor: "Customer" ✅ Good: "An individual or organization that purchases products or services from the company. Customers have associated contact information, purchase history, and account status."

❌ Poor: "TODO - fill this in later" ✅ Good: "The primary classification category for organizing products in the catalog. Each category can contain multiple products and may have subcategories for more detailed organization."

❌ Poor: "a type of Account" ✅ Good: "A savings account is a type of financial account that earns interest on deposited funds. Unlike checking accounts, savings accounts typically have withdrawal limitations but offer higher interest rates."

Invest in Quality Descriptions

Good descriptions help new team members understand your model, support better communication with stakeholders, and serve as documentation for future reference. Invest time in writing clear, informative descriptions for your key terms—it pays off in long-term model maintainability.

No parent in description

Lists all terms that have a Generalization relation with a parent term, but that parent term is not mentioned in the definition.

Why this matters

Mentioning the parent term in the definition is a powerful technique for building well-structured, understandable, and logically sound semantic models. It leverages the power of hierarchical relations to organize knowledge effectively:

• Establishing a Clear Hierarchy and Context: By stating the parent term, you immediately position the current term within a broader classification. This establishes a clear "is-a" relation and provides essential context for understanding the term's fundamental nature. For example, defining "Sedan" as "a type of Car" immediately tells us that a sedan inherits all the general characteristics of a car.

• Improving Understandability and Navigation: Explicitly stating the parent term makes the model easier to understand and navigate. Users can quickly grasp the relation between different concepts and traverse the hierarchy to find related terms. It creates a more intuitive and organized structure.

• Supporting Logical Reasoning and Inference: When parent-child relations are clearly defined through definitions, it enables logical reasoning and inference within the model. For example, if we know "Sedan is a type of Car" and "Car has four wheels," we can infer that "Sedan has four wheels."

• Ensuring Consistency and Avoiding Redundancy: By anchoring a term to its parent in the definition, you reinforce the established hierarchy and reduce the risk of defining contradictory or redundant properties and relations for the child term.

How it works

This check examines terms with Generalization relations:

1. Identifies all terms that have an outgoing Generalization relation (meaning they have a parent)
2. Extracts the parent term's name from the relation
3. Searches the term's description for any mention of the parent term's name
4. Flags terms where the parent is not mentioned in the description

What to do

1. For each flagged term, click to open the term sidebar
2. Edit the description to include a reference to the parent term
3. Use one of these common patterns:
   • "A [term] is a type of [parent]..."
   • "A specialized [parent] that..."
   • "A form of [parent] which..."
4. Follow the parent reference with details that distinguish this term from its parent

Example:

• ❌ Poor: "Sedan: A vehicle with four doors and a separate trunk."
• ✅ Good: "Sedan: A type of Car with four doors, a separate trunk, and a fixed roof."

Best Practice

Start child term descriptions by referencing the parent, then explain what makes the child term unique or different from the parent. This creates clear, hierarchical documentation that mirrors your model's structure.

No relations

Lists all terms that do not have any relations (either incoming or outgoing).

Why this matters

Relations are the foundational links that define how terms connect and interact within a semantic model. They are critical for building a meaningful and useful representation of a domain:

• Consistency with Definitions: A term's relations should align with its definition. If a term is defined as an "Event," it should have relations connecting it to other events, participants, or locations. Missing relations could indicate that the term's connections have not been fully modeled, creating a gap between what the term is described as and how it's actually used within the graph.

• Structural Integrity: A term without relations is an isolated concept. Relations weave a network of meaning, showing how each term contributes to a larger, interconnected system. They provide the necessary structure to turn a simple list of terms into a functional and navigable model.

• Context and Dependency: Relations provide crucial context by defining a term's role and its dependencies on other concepts. For example, "Product" is only meaningful when related to "Price," "Customer," or "Supplier." These connections clarify its function and place within the domain.

• Navigational Pathways: In a graph-based system, relations act as pathways for exploration and analysis. By following relations, users can discover related terms, understand causal links, or trace dependencies. A term with no relations is a dead end.

• Completeness and Accuracy: A term that lacks relations may indicate an incomplete or inaccurate model. It suggests that a concept has been identified but its connections to the rest of the domain have not been fully captured.

What to do

1. Review each isolated term to determine if it's:
   • A new term that needs relations defined
   • A term that should be connected to existing terms
   • A term that might not belong in the model
2. For terms that should remain, add appropriate relations by:
   • Hovering over the term and dragging the circular arrow to another term
   • Using the "Add relation" button in the Term sidebar Relations tab
3. Delete terms that don't contribute to the model

Isolated Terms

Terms without relations are "islands" in your model. They cannot be discovered through navigation and don't contribute to the overall structure. Either connect them or remove them.

Duplicating parent relations

Lists all terms that have the same relation(s) as one of their parents.

Why this matters

Avoiding the explicit duplication of parent relations in child terms is a key principle for creating efficient, maintainable, and semantically clean models. While a child term inherits the parent's relations in a hierarchical structure, explicitly stating the same relations on the child term leads to several drawbacks:

• Redundancy and Increased Complexity: Explicitly listing the same relations on both the parent and the child term introduces unnecessary redundancy. This makes the model larger and more complex to read and understand. It clutters the definition of the child term with information that is already implicitly understood through the parent-child relation.

• Maintenance Overhead: If a relation of the parent term needs to be updated (e.g., its cardinality changes, or it's renamed), you would also need to remember to update it on every child term where it was explicitly duplicated. This significantly increases the maintenance burden and the risk of inconsistencies.

• Reduced Clarity of Specialization: The primary purpose of creating child terms is to represent more specific concepts that specialize the parent concept. If a child term simply repeats all the parent's relations, it doesn't clearly highlight the unique relations that define its specialization. The focus should be on the relations that are specific to the child term.

How it works

This check identifies duplicate relations through inheritance:

1. For each term with a Generalization relation (child term), it identifies the parent term(s)
2. Compares the child term's direct relations with the parent's relations
3. Flags any relations that appear on both the child and parent terms
4. Lists the child term along with the duplicated relation names

What to do

1. Review each flagged child term and its duplicate relations
2. For most cases, delete the duplicate relation from the child term:
   • The relation will still be visible through inheritance
   • This reduces redundancy and maintenance burden
3. Keep the child's relation only if:
   • It has different cardinality than the parent's
   • It has additional constraints specific to the child
   • There's a clear reason for overriding the parent's relation
4. Enable inheritance to see inherited relations: Settings > Document > Inherit relations

Using Inheritance

Instead of duplicating relations, leverage inheritance:

• Inheritance: Enable in Document Settings so child terms automatically inherit parent relations
• Specialization: Define only relations unique to the child term
• View inherited relations: Use the Term Sidebar's Relations tab to see both direct and inherited relations

Note: Termboard does not support relation overriding. If you need different constraints, consider restructuring your hierarchy.

Multi parent

Lists terms that have multiple parents (multiple Generalization relations), including the parent terms.

Why this matters

Multiple inheritance offers potential for more expressive models but introduces significant complexity. Understanding both advantages and disadvantages helps you make informed modeling decisions:

Advantages:

• Increased Expressiveness and Granularity: Multiple inheritance allows a term to inherit characteristics (properties and relations) from multiple distinct parent concepts. This can lead to a more nuanced and accurate representation of real-world concepts that naturally belong to more than one category. For example, a "Hybrid Car" inherits features from both "Electric Car" and "Gasoline Car."

• Reduced Redundancy (in some cases): If a concept shares characteristics with multiple independent parent concepts, multiple inheritance can avoid the need to explicitly define those shared characteristics within the child term. Instead, it inherits them from the respective parents.

• Facilitating Reusability: By inheriting from multiple parents, a child term can reuse existing definitions and relations, promoting modularity and reducing the overall size and complexity of the model.

Disadvantages:

• The "Diamond Problem" (or Inheritance Ambiguity): This is the most significant challenge. It arises when a child term inherits from two parents that, in turn, share a common ancestor. If this common ancestor defines a property or relation, it becomes ambiguous which version the child should inherit. For example:

  LivingBeing
    /   \
    Animal Plant
    \   /
      Creature  (inherits from both Animal and Plant)
  

  If Living Being has a property "hasCellStructure," does Creature inherit the animal cell structure or the plant cell structure, or both?

• Increased Complexity and Reduced Understandability: Models with multiple inheritance can become significantly more complex to understand and reason about. Tracing the inheritance paths and resolving potential conflicts can be difficult for both humans and automated systems.

• Potential for Logical Inconsistencies: If the inherited characteristics from multiple parents are contradictory, it can lead to logical inconsistencies within the model. Careful design is needed to avoid such situations.

How it works

This check identifies terms with multiple inheritance:

1. Examines all terms in the model
2. Counts the number of outgoing Generalization relations for each term
3. Flags terms that have 2 or more Generalization relations (meaning they have multiple parents)
4. Lists both the child term and all its parent terms

What to do

1. Review each term with multiple parents to determine if the multiple inheritance is intentional and necessary
2. Consider alternative modeling approaches:
   • Intermediate concepts: Create a new parent concept that combines the characteristics
   • Composition over inheritance: Use relations instead of inheritance
   • Single inheritance: Choose the most appropriate single parent
3. If keeping multiple parents, ensure:
   • Parent concepts are truly independent (no shared ancestors)
   • Inherited characteristics don't conflict
   • The model remains understandable
4. Document the rationale for multiple inheritance in the term's description

Use with Caution

Multiple inheritance should be used judiciously. Often, alternative modeling techniques like intermediate classes or carefully defined relations can achieve similar expressiveness with fewer drawbacks and less ambiguity.

Circular hierarchies

Lists the terms that are in a circular hierarchy (using the Generalization relation type).

Why this matters

Avoiding circular hierarchies in semantic modeling is crucial for maintaining logical consistency, enabling effective reasoning, and ensuring the overall integrity and understandability of the model.

A circular hierarchy occurs when a term, through a chain of generalization relations, inherits from itself. For example: Term A → Term B → Term C → Term A. This creates a logical impossibility and breaks the fundamental nature of hierarchical classification.

Why circular hierarchies are problematic:

• Logical Contradiction: A term cannot be both a parent and a child of itself, even through intermediary terms. This violates the basic principles of hierarchical classification.

• Infinite Inheritance Loops: When traversing the hierarchy to inherit properties or relations, a circular reference creates an infinite loop, making it impossible to determine what properties a term should have.

• Prevents Reasoning: Automated reasoning systems and inference engines rely on acyclic hierarchies. Circular references break these systems and prevent logical conclusions.

• Maintenance Confusion: It becomes unclear which term is the "parent" concept and which is the specialization, making the model difficult to understand and maintain.

How it works

This check detects circular inheritance paths:

1. For each term, it traces the chain of Generalization relations
2. Follows the path from child to parent to grandparent, etc.
3. Detects if the path eventually loops back to the starting term
4. Lists all terms involved in the circular path

What to do

1. Examine the circular path shown in the check results
2. Identify which generalization relation is incorrect or unnecessary
3. Remove the relation that breaks the logical hierarchy
4. Verify that the remaining hierarchy makes semantic sense and forms a proper tree structure

Example of fixing a circular hierarchy:

• Circular: Car → Vehicle → Transport → Car (incorrect)
• Fixed: Car → Vehicle → Transport (correct - forms a proper hierarchy)

Critical Error

Circular hierarchies are a fundamental modeling error that breaks logical reasoning and inheritance. This must be fixed immediately before continuing with model development.

Bidirectional Relations

Lists term pairs that have relations going in both directions, which may indicate confusion or modeling issues.

Why this matters

When two terms have relations pointing both ways (A → B and B → A), it often signals one of the following situations:

• Redundant Relations: One relation might be the inverse of the other (e.g., "Customer places Order" and "Order is placed by Customer"). While both express the same information, having both can be redundant unless you're explicitly modeling inverse relations.

• Modeling Confusion: The presence of bidirectional relations might indicate uncertainty about the proper direction of the relationship or conflicting modeling decisions.

• Different Relation Types: Sometimes the forward and backward relations represent genuinely different relationships, which is acceptable. For example, "Person works for Company" and "Company employs Person" might use different relation types.

Impact on your model:

• Model Clarity: Bidirectional relations can make the model harder to understand. It's not immediately clear whether both directions are intentional or if one is redundant.

• Maintenance Overhead: If you need to update a relation, you might need to remember to update both directions, increasing the risk of inconsistency.

• Query Complexity: When querying the model, bidirectional relations can lead to unexpected results or require more complex queries to filter duplicates.

How it works

This check identifies bidirectional relationships:

1. Examines all relations in the model
2. For each relation from term A to term B, checks if there's also a relation from term B to term A
3. Groups these bidirectional pairs together
4. Lists both terms and the relation names going in each direction

What to do

1. Review each bidirectional pair to understand why both directions exist
2. Determine the relationship type:
   • Same information (redundant): Keep only one direction, or configure proper inverse relations in Relation Types
   • Different relationships: Ensure they use different relation types or names that clearly distinguish their meanings
3. If keeping both directions:
   • Document the rationale in the term descriptions
   • Use distinct relation names or types to make the difference clear
4. If removing one direction:
   • Choose the direction that best represents the natural flow of the relationship
   • Add a reverse name in Relation Type settings for verbalization

Modeling Inverse Relations

Instead of creating bidirectional relations, use the "Reversed" column in Relation Type settings to define inverse relation names. This allows you to model a single relation that can be read in both directions (e.g., "Customer places Order" ↔ "Order is placed by Customer").

Potential Properties

Identifies terms that do not have type 'property' but are likely to represent properties rather than concepts based on their last word.

Why this matters

Semantic modeling practices encourage distinguishing between concepts (things you want to model) and properties (descriptive attributes of those things). This check helps you maintain a clearer and more consistent separation:

• Clearer Conceptual Boundaries: Properties (e.g., Name, Date, Balance) describe attributes of concepts but should not themselves be modeled as standalone concepts. A term like CustomerName is best understood as a property of Customer, not as an independent concept.

• Avoiding Over-Modeling: When property-like terms are modeled as concepts, the model can become unnecessarily complex. For example, Status is usually just a property of another concept (like Order Status) rather than a separate concept in its own right.

• Consistency Across the Model: By consistently recognizing properties based on naming conventions, you avoid inconsistencies such as sometimes treating PostalCode as a concept and other times as a property.

• Alignment with Common Modeling Practices: Many semantic and data modeling methodologies recommend separating what something is (concepts) from how something is described (properties). This aligns better with both conceptual modeling and practical implementation in databases or APIs.

• Predictable Structure: Identifying properties based on suffixes or naming patterns makes the model more predictable for others to understand and extend. For example, encountering AccountBalance immediately signals that Balance is a property of Account.

How it works

This check analyzes each term that is not already marked as type 'property':

1. Splits the term name into words (handling spaces, underscores, and camelCase)
2. Examines the last word of the term name
3. Compares it against known property indicators (e.g., id, code, balance, date, name, number, amount)
4. Flags terms where the last word suggests it's a property rather than a concept

What to do

1. Review each flagged term to determine if it's truly a property
2. For confirmed properties:
   • Click the term to open the term sidebar
   • Go to the Details tab
   • Change the Type to "Property"
3. For terms that are actually concepts despite the naming pattern, consider renaming them for clarity
4. Use the bulk operation: Select all matched terms using the 'select terms' icon, then change their type to "property" in the right sidebar

Hiding Properties

After marking terms as properties, you can hide them in the graph by enabling "Hide properties" in Document Settings. This gives you a clearer picture of your concepts (classes) only.

Properties Without Attributive Relations

Identifies property terms that are not properly linked to a concept term using an Attributive relation.

Why this matters

In a well-structured semantic model, a property should always describe a concept through an Attributive relation:

• Ensures a Coherent Model: A property term like CustomerName is meaningless on its own. It only becomes useful when it's attached to a concept like Customer. This check ensures that all your properties have a clear, defined place in your model.

• Prevents "Orphaned" Properties: It helps you find and fix properties that were either mistakenly created as standalone terms or had their relation to a concept accidentally deleted. These orphaned properties are a form of bad data that clutters your model.

• Improves Model Readability: By ensuring every property is connected to a concept, you make your model easier for others to understand. A quick glance at the graph view will show a clear hierarchy: concepts are the main building blocks, and properties branch off from them.

• Validates Data Integrity: This feature acts as a data validation tool for your semantic model. It ensures the model follows the fundamental rule of semantic modeling: a property must describe a concept.

How it works

This check examines every term with the 'property' type:

1. For each property, it looks for an incoming Attributive relation
2. The relation must originate from a term of type concept
3. If a property has no such relation, it's flagged as orphaned
4. All orphaned properties are shown in the list

What to do

1. For each orphaned property, determine which concept it should belong to
2. Create an Attributive relation from the concept to the property:
   • Select the concept term
   • Create a relation to the property
   • Ensure the relation is mapped to type "Attributive" in Relation Types
3. If a property doesn't belong to any concept, either:
   • Change its type back to "Term" or "Concept"
   • Delete it if it's not needed

Prerequisites

This check requires:

• Relation Types: Map your attribute relations to type "Attributive" in Relation Type settings
• Term Types: Terms must be classified as "Concept" or "Property" in the Term Details tab