ERD vs UML Class Diagram: Which Modeling Tool Should Developers Use?

Overview

An entity relationship diagram (ERD) models data. It shows entities such as customers, orders, or products, along with their attributes and relationships. An ERD is primarily concerned with how information is stored, connected, constrained, and retrieved in a database.

A UML class diagram models software structure. It shows classes, properties, operations, visibility, inheritance, interfaces, and associations. A class diagram is primarily concerned with how application code represents behavior and collaborates at runtime.

These models can describe related concepts without being interchangeable. A database table may become a class, but it may also become a repository concern, a persistence model, or several domain objects. Likewise, one application class may read from multiple tables or deliberately hide database details behind an abstraction.

The right choice depends on the decision the diagram must support. If a reviewer needs to validate normalization, foreign keys, or optionality, start with an ERD. If the discussion concerns responsibilities, polymorphism, or application boundaries, use a class diagram. For many systems, the clearest documentation includes both, with an explicit explanation of how persistence models relate to domain and application models.

For database-focused guidance, see Database Schema and ERD Diagrams: A Developer’s Guide. For a broader system view, a C4 model diagram can place the data and application models in their architectural context.

Checklist by scenario

Scenario 1: Designing a new relational database

• Start with an ERD that names the main entities and their business meaning.
• List attributes separately from implementation-specific column details where the design is still conceptual.
• Mark primary keys, foreign keys, unique constraints, and required versus optional relationships.
• Define cardinality clearly: one-to-one, one-to-many, or many-to-many.
• Resolve many-to-many relationships with a junction entity when the relational design requires it.
• Document ownership and lifecycle questions, such as whether an invoice can exist without an account.
• Only add indexes, partitioning, or vendor-specific types when the diagram is intended to represent a physical schema.

Use a UML class diagram later if the database design needs to be mapped to application objects. Do not assume that every table should appear as a public domain class.

Scenario 2: Designing an application or domain model

• Use a class diagram to identify classes, interfaces, responsibilities, and collaborations.
• Show important operations or invariants, not every getter, setter, or framework-generated method.
• Distinguish inheritance from composition. Prefer the relationship that reflects the actual design decision.
• Separate domain objects from controllers, repositories, transport models, and persistence entities where those layers differ.
• Label dependencies so readers can understand direction and intent.
• Keep the diagram focused on one bounded context or responsibility area rather than the entire codebase.

A class diagram is useful here because it communicates behavior and responsibility, not merely stored fields. If request and response structures are the concern, supplement it with an API diagram or schema description rather than overloading the class model.

Scenario 3: Translating a schema into software design

• Place the ERD and class diagram side by side during review.
• Identify direct mappings, such as a simple account record becoming a persistence object.
• Identify transformations, such as several tables being assembled into one read model.
• Record cases where a class has no table because it represents behavior, a value object, or a temporary calculation.
• Record cases where a table has no direct domain class because it supports auditing, indexing, joins, or integration.
• Confirm where validation occurs: database constraints, application logic, or both.

This translation checklist is especially important in domain-driven systems, where the domain model is intentionally not a mirror of the database. The relationship between the two models should be documented rather than left for readers to infer.

Scenario 4: Documenting an API-backed system

• Use an ERD for the authoritative relational data model.
• Use a class diagram for internal services and domain logic when object collaboration matters.
• Use an API architecture diagram to show clients, gateways, services, queues, and external dependencies.
• Use sequence diagrams for request flow, timing, retries, and failure paths.
• Label whether an object or schema is internal, public, persisted, or transformed at a boundary.

These views answer different questions and should not be forced into one crowded drawing. A focused set of diagrams is usually easier to maintain than a single “complete” model.

What to double-check

Semantics and scope

Define what each box means before reviewing visual polish. In an ERD, decide whether an entity represents a business concept, a table, or a physical database object. In a class diagram, state whether the classes are domain objects, implementation classes, or conceptual abstractions. Mixing these levels makes valid relationships look inconsistent.

Relationships

Check that relationship direction and cardinality are unambiguous. A line without labels may not tell readers whether it represents ownership, reference, inheritance, or simple communication. For an ERD, verify that optionality matches the actual constraints. For UML, verify whether composition, aggregation, association, and dependency are being used deliberately rather than decoratively.

Names and boundaries

Use names that match the vocabulary used in requirements, code, and database migrations. If the same concept is called “user” in one model and “customer” in another, explain whether that difference is intentional. Draw boundaries around bounded contexts, services, schemas, or modules so readers know where a relationship stops applying.

Accuracy and ownership

• Compare the ERD with the current migration or schema definition.
• Compare the class diagram with the relevant interfaces and module structure.
• Check that examples do not expose secrets, production identifiers, or sensitive records.
• Add an owner, last-reviewed date, and source location to the documentation.
• Link the diagram to a design document, repository, schema file, or API specification.

A browser-based developer diagram tool can be appropriate for collaborative exploration, while diagrams stored as code may be better for versioned documentation. Consider text-based formats when reviews, pull requests, and repeatable rendering matter; see Mermaid diagrams in Markdown and the comparison of Mermaid, PlantUML, D2, and Graphviz for workflow considerations.

Common mistakes

• Treating an ERD as a class diagram: tables and foreign keys do not explain methods, invariants, or runtime behavior.
• Treating a class diagram as a schema: classes may be transient, composed from multiple sources, or intentionally not persisted.
• Showing every field: excessive detail hides the relationships and decisions the reader needs to review.
• Mixing abstraction levels: placing a cloud provider resource, a database column, and a domain concept in one undifferentiated view creates confusion.
• Using notation without explanation: unfamiliar crow’s-foot or UML symbols should have a legend or clear labels.
• Leaving diagrams unowned: an accurate model becomes misleading when schema or code changes are not reflected.
• Forcing one tool to do every job: an ERD, class diagram, sequence diagram, and deployment view have different purposes even when one tool can render them.

For a broader review process covering clarity, accuracy, security, and ownership, use the diagram review checklist for engineering teams.

When to revisit

Review the model before a planning or design cycle when the team is likely to make structural decisions. Revisit it when a database migration changes keys or relationships, when a domain boundary moves, when an API contract changes, or when services are split or combined. A diagram does not need to change for every implementation detail, but it should change when its intended decision context changes.

Use this short update checklist:

1. Compare the diagram with the current schema, interfaces, and architecture documentation.
2. Remove objects that no longer influence the decision the diagram supports.
3. Mark proposed elements differently from deployed or approved elements.
4. Confirm relationships, cardinality, ownership, and trust boundaries.
5. Ask a developer, database owner, or service owner to review the model from their perspective.
6. Record the review date and link the updated version from the relevant design or documentation page.

The practical rule is simple: choose an ERD when the question is about data persistence, choose a UML class diagram when it is about software structure and behavior, and use both when the boundary between application design and storage needs to be made explicit. Keep each view narrow, label its abstraction level, and update it whenever the underlying design changes.