Designing Data Models

In the previous chapter, you identified what data your API needs. Now it's time to design the data models and implement them as schemas in Apidog.

Data models define the structure of your API's data—what fields exist, their types, validation rules, and how they're used. Schemas are the technical implementation of these models in Apidog using JSON Schema.

In this chapter, we'll learn how to design data models and immediately implement them as schemas in Apidog. We'll use the Pet Store User module as our example, creating schemas step by step.

1. What Are Data Models and Schemas?

A data model is a conceptual design of how your data is structured. A schema is the technical specification that implements that model.

Think of it this way:

Data Model = the blueprint (what you design)

Schema = the actual specification in Apidog/OpenAPI (what you implement)

In Apidog, schemas are based on JSON Schema and define:

Field names and types

Required vs optional fields

Validation rules (format, length, patterns)

Nested objects and arrays

Default values

2. The Design Process

When designing data models, follow this approach:

Start with requirements — What data do you need? (from previous chapter)

Design the model — What fields, types, and rules?

Implement as schema — Create it in Apidog

Test and refine — Validate the design

Let's apply this to the User module.

3. Designing the User Model

Based on our requirements analysis, a User needs:

Required fields:

id — unique identifier (generated by system)

email — for login and communication

firstName — user's first name

lastName — user's last name

createdAt — account creation timestamp

Optional fields:

phone — phone number

preferences — user preferences (nested object)

Authentication:

password — for login (never returned in responses)

User Model Structure

Here's what the User model looks like:

{
  "id": "usr_3Oy2JIS7TMJgEXfM",
  "email": "jane.smith@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+14155551234",
  "preferences": {
    "newsletter": true,
    "notifications": false
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

4. Creating Schemas in Apidog

Now let's implement this model as a schema in Apidog. Apidog's recommended approach is to paste JSON directly, and it will automatically recognize and generate the schema structure.

Step 1: Create the User Schema

In your Apidog project, go to the Schemas section

Click the ➕ icon and select New Schema

Name it "User" and add a description: "User account information"

Step 2: Generate Schema from JSON

Instead of manually adding properties one by one, Apidog allows you to paste JSON and automatically generate the schema:

Click "Generate from JSON etc." button in the Schema Editor

Paste the following JSON:

{
  "id": "usr_3Oy2JIS7TMJgEXfM",
  "email": "jane.smith@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "phone": "+14155551234",
  "preferences": {
    "newsletter": true,
    "notifications": false
  },
  "createdAt": "2024-01-15T10:30:00Z"
}

Apidog will automatically:

Recognize all properties and their types

Set appropriate data types (string, boolean, object, date-time)

Create the nested preferences object structure

Note: By default, all properties in the JSON will be marked as required. You'll need to adjust this manually for optional fields.

Step 3: Refine the Generated Schema

After generating from JSON, refine the schema:

Mark optional fields as not required:

Uncheck "Required" for phone and preferences

Add validation rules:

id: Add pattern ^usr_[A-Za-z0-9]{16}$ and mark as read-only

email: Set format to email, add max length 255

firstName and lastName: Add max length 50

phone: Add pattern ^\+?[1-9]\d{1,14}$ (E.164 format)

createdAt: Set format to date-time and mark as read-only

Add descriptions to each field for better documentation

Tip: Apidog's JSON smart recognition generates the data structure based on the JSON values, but doesn't save the actual values. You can add descriptions and adjust validation rules afterward.

5. Creating Nested Schemas: UserPreferences

The preferences field is a nested object. Let's create a separate schema for it so we can reuse it.

Step 1: Create UserPreferences Schema

Create a new schema named "UserPreferences"

Add description: "User communication preferences"

Step 2: Generate from JSON

Click "Generate from JSON etc."

Paste this JSON:

{
  "newsletter": true,
  "notifications": false
}

Apidog will automatically recognize both boolean fields

Step 3: Refine the Schema

Mark both fields as optional (uncheck "Required")

Set default values:

newsletter: Default false

notifications: Default true

Add descriptions to each field

Step 4: Reference in User Schema

Now go back to the User schema and:

Select the preferences property

Change its type to Reference

Select UserPreferences from the list

This creates a reference, allowing you to reuse the UserPreferences schema. If you update UserPreferences later, all references will automatically reflect the changes.

6. Schema Best Practices

When designing schemas, keep these principles in mind:

Keep It Simple

Avoid over-engineering: Don't add fields "just in case"

Use simple types when possible: Prefer string over complex objects when appropriate

Group related fields: Use nested objects for logical groupings (like preferences)

Avoid Over-Nesting

Try to keep nesting to 2-3 levels maximum. Deep nesting makes schemas hard to understand and use.

Use Schema References

When you have reusable structures (like UserPreferences), create separate schemas and reference them. This:

Reduces duplication

Makes updates easier

Improves consistency

Security Considerations

Never include passwords in response schemas

Use write-only for sensitive input fields (password)

Use read-only for system-generated fields (id, createdAt)

Validate all input according to your rules

Plan for Extensibility

Use optional fields for new features

Avoid removing fields (mark as deprecated instead)

Use API versioning for major changes

7. Key Takeaways

Designing and implementing data models is a crucial step:

Data models define what data your API uses

Schemas are the technical implementation in Apidog

Use "Generate from JSON" to quickly create schemas from JSON data

Use schema references for reusable structures (like UserPreferences)

Create core schemas first — request/response variations can be handled at the endpoint level

Security matters: Use write-only for sensitive fields, read-only for system-generated fields

Keep it simple: Avoid over-nesting and over-engineering

Now that you have your core schemas designed and implemented, you're ready to start building endpoints. In the next chapter, we'll learn how to design endpoints in Apidog, using the schemas we created and the endpoint structure we planned earlier.

Let's continue with Designing Endpoints.

Designing Data Models

1. What Are Data Models and Schemas?#

2. The Design Process#

3. Designing the User Model#

User Model Structure#

4. Creating Schemas in Apidog#

Step 1: Create the User Schema#

Step 2: Generate Schema from JSON#

Step 3: Refine the Generated Schema#

5. Creating Nested Schemas: UserPreferences#

Step 1: Create UserPreferences Schema#

Step 2: Generate from JSON#

Step 3: Refine the Schema#

Step 4: Reference in User Schema#

6. Schema Best Practices#

Keep It Simple#

Avoid Over-Nesting#

Use Schema References#

Security Considerations#

Plan for Extensibility#

7. Key Takeaways#