74 Adding Comments and Descriptions to Schemas: A Practical Guide to Documenting Your Data

Schema documentation is often treated as a trivial part of application development. However, as a system grows in complexity, comments and descriptions on both database schemas and API schemas become a game changer for maintaining quality, collaboration, and the long-term sustainability of a project. In this 74th article of the series, I’ll go into detail on how to add comments and descriptions to various schemas—from SQL and NoSQL databases all the way to APIs (OpenAPI/Swagger)—complete with code examples, simulations, and best practices I frequently encounter in the professional world.

Why Are Comments and Descriptions in Schemas Important?

On many projects, I often come across legacy schemas with little to no documentation. This leads to:

• Difficulty onboarding new developers
• Misinterpretation of the data structure
• Overlapping column names or data types
• Hard-to-perform migrations or refactors

Comments and descriptions in a schema can serve as living documentation that anyone can easily inspect—whether through the code, a tool’s interface (such as pgAdmin/dBeaver/Postman), or an automatic documentation generator.

Case Study: Adding Comments to a PostgreSQL Database Schema

Let’s put this into practice with PostgreSQL, a database that strongly supports adding comments directly at the table, column, and even constraint or view level.

Example of Creating a Schema Without Comments

1CREATE TABLE users (
2    id SERIAL PRIMARY KEY,
3    name VARCHAR(100) NOT NULL,
4    email VARCHAR(200) UNIQUE NOT NULL,
5    created_at TIMESTAMP DEFAULT NOW()
6);

The columns above are fairly clear, but as a project grows more complex (say, with status, roles, and similar fields) without comments, other developers will need extra time to ask around or consult separate documentation.

Adding Comments with COMMENT ON

PostgreSQL provides the COMMENT ON command to add descriptions to database objects.

1-- Add a comment to the table
2COMMENT ON TABLE users IS 'Tabel utama menyimpan data user aplikasi.';
3
4-- Add comments to the columns
5COMMENT ON COLUMN users.id IS 'Primary key (auto increment).';
6COMMENT ON COLUMN users.name IS 'Nama lengkap user.';
7COMMENT ON COLUMN users.email IS 'Alamat email user, harus unik.';
8COMMENT ON COLUMN users.created_at IS 'Waktu registrasi user.';

Simulation: If you use pgAdmin/dBeaver, these comments automatically appear under the Properties / Description tab. If you run \d+ users in psql, the comments will show up in the table information.

Visualizing the Process with Mermaid

Let’s look at the flow of how a developer and a database designer collaborate to enrich a schema with documentation.

flowchart TD
    A[Database Designer] -->|Define Table| B[Create Table]
    B --> C[Assign Columns]
    C -->|Add Comment| D[Document Each Column]
    D --> E[Developer Reads Schema w/ Description]

flowchart TD
    A[Database Designer] -->|Define Table| B[Create Table]
    B --> C[Assign Columns]
    C -->|Add Comment| D[Document Each Column]
    D --> E[Developer Reads Schema w/ Description]

Documenting Schemas in MongoDB

In NoSQL databases like MongoDB, the schema isn’t rigid and there’s no built-in comment feature, but we can standardize descriptions through the schema in Mongoose (an ODM for Node.js).

 1const mongoose = require('mongoose');
 2
 3const userSchema = new mongoose.Schema({
 4  name: {
 5    type: String,
 6    required: true,
 7    description: 'Full name of the user'
 8  },
 9  email: {
10    type: String,
11    required: true,
12    unique: true,
13    description: 'A valid email address'
14  },
15  createdAt: {
16    type: Date,
17    default: Date.now,
18    description: 'Date and time the user was created'
19  }
20});

Mongoose will ignore the description property, but with this convention, other developers can easily understand the meaning of each field.

Documenting an API Schema with OpenAPI (Swagger)

An API schema is actually more straightforward, since modern tools like Swagger and Postman already adopt descriptions natively.

Example OpenAPI specification:

 1components:
 2  schemas:
 3    User:
 4      type: object
 5      properties:
 6        id:
 7          type: integer
 8          description: Unique user ID
 9        name:
10          type: string
11          description: Full name of the user
12        email:
13          type: string
14          format: email
15          description: A valid user email address
16        createdAt:
17          type: string
18          format: date-time
19          description: User registration date
20      required:
21        - id
22        - name
23        - email

By applying a description to each property, the API documentation becomes far more informative automatically through Swagger UI.

Best Practices: Documenting Schemas

Here are a few professional tips from my own experience:

Simulation Study: The Impact of Schema Documentation

Team Simulation:

1. Without comments: During sprint 6, the status field (an integer) is requested for filtering, but it’s unclear what the values 0, 1, and 2 mean. QA files a bug report.

2. With comments:

   sql

   Copy

   1COMMENT ON COLUMN users.status IS 'Status user: 0=inactive, 1=active, 2=banned.';

   The product manager immediately understands the mapping without having to ask the developer.

Data Study: The Effect of Documentation

An internal survey at my workplace last year across 14 development teams showed:

Teams with fully documented schemas experienced far fewer data incidents and developed software much faster.

Closing

Adding comments and descriptions to your schemas is a small investment with a big payoff for the sustainability and quality of a project—it doesn’t just help your colleagues today, but also helps you, six months from now, when you need to recall the architectural decisions you made. I highly recommend adopting this habit with discipline across every layer of development, from the database to the API. Don’t wait until it’s too late; start adding descriptions to your schemas today. Happy documenting! 🚀