Ultimate Guide to JSON API Design: Principles, Best Practices, and Schema Standards

In today's API-first software architecture, JSON has become one of the most widely used data exchange formats. Whether it's RESTful APIs, configuration files, database storage, or log analysis, JSON plays a foundational role.

However, through extensive real-world system practice, we’ve observed that chaotic JSON design, lack of standardization, and inconsistent interfaces are still widespread. These issues seriously impact system maintainability, front-end/back-end collaboration efficiency, and the evolvability of APIs.

This article systematically outlines the core knowledge of structured JSON design, analyzes common issues in depth, and introduces how to leverage EchoAPI’s Schema modeling capabilities to achieve standardized, automated, and intelligent data structure design.

Core Knowledge System of Structured JSON Design

1.1 Basic Structures and Data Types

JSON is composed of two fundamental structures:

Supported data types include:

• String: "hello"
• Number: 42, 3.14
• Boolean: true, false
• Null: null
• Object
• Array

1.2 Common JSON Structural Patterns

Flat Structure

{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com"
}

• ✅ Simple and ideal for basic objects
• ❗ Cannot express complex business semantics or relationships

Nested Structure

{
  "user": {
    "id": 1,
    "profile": {
      "name": "Alice",
      "email": "alice@example.com"
    }
  }
}

• ✅ Reflects real-world object models
• ❗ Avoid excessive nesting ("Russian doll" structure)

Array of Objects

{
  "users": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" }
  ]
}

• ✅ Common for representing lists
• ❗ Ensure consistency in array item structure

1.3 Design Principles and Common Issues

Consistency

Definition: Use consistent field names, hierarchy levels, and data types across interfaces.

❌ Incorrect Example:

// API A
{ "user_id": 101, "user_name": "Tom" }
// API B
{ "uid": 101, "name": "Tom" }

✅ Correct Example:

{ "user_id": 101, "user_name": "Tom" }

Recommendations:

• Define domain field standards (e.g., always use user_id, not uid, id, or userid).
• Document naming conventions.

Readability

Definition: Use meaningful, clear field names. Avoid abbreviations or vague terms.

❌ Incorrect Example:

{ "u_n": "Alice", "t_c": "2025-07-09" }

✅ Correct Example:

{ "user_name": "Alice", "created_time": "2025-07-09T12:00:00Z" }

Recommendations:

• Use full words (e.g., email instead of eml)
• Maintain clarity in English for collaboration and documentation
• Adopt a shared naming dictionary (created_at, status, etc.)

Orthogonality

Definition: Each field should serve a single, distinct purpose.

❌ Incorrect Example:

{ "user_info": "Tom,101,true" }

✅ Correct Example:

{
  "user": {
    "id": 101,
    "name": "Tom",
    "is_active": true
  }
}

Recommendations:

• Do not combine multiple values into one string field
• Use nested structures to represent complex entities

Limit Nesting Depth

Definition: Keep nesting to 2–3 levels to maintain readability and performance.

❌ Incorrect Example:

{
  "user": {
    "profile": {
      "meta": {
        "settings": {
          "preferences": {
            "theme": "dark"
          }
        }
      }
    }
  }
}

✅ Correct Example:

{
  "user": {
    "theme": "dark"
  }
}

Recommendations:

• Restrict nesting to ≤3 levels
• Use references or separate models for complex structures

Extensibility

Definition: Enable easy addition of fields or substructures without breaking existing designs.

❌ Incorrect Flat Structure:

{
  "user_name": "Alice",
  "user_email": "alice@example.com",
  "user_age": 25
}

✅ Correct Nested Structure:

{
  "user": {
    "profile": {
      "name": "Alice",
      "email": "alice@example.com",
      "age": 25
    }
  }
}

Recommendations:

• Use nested modules (profile, settings, etc.)
• Design with future extensibility in mind

Minimal Redundancy

Definition: Avoid duplicating information unnecessarily.

❌ Incorrect Example:

{
  "user_id": 101,
  "user": {
    "id": 101,
    "name": "Alice"
  }
}

✅ Correct Example:

{
  "user": {
    "id": 101,
    "name": "Alice"
  }
}

Recommendations:

• Eliminate redundant fields (especially IDs and statuses)
• Keep the payload concise and unambiguous

Type Clarity

Definition: A field's data type should be consistent across all contexts.

❌ Incorrect Example:

{ "status": 1 }
{ "status": "active" }
{ "status": { "code": 1, "text": "active" } }

✅ Correct Examples:

{ "status": "active" }

or

{ "status": { "code": 1, "label": "active" } }

Recommendations:

• Use fixed types (string, object, etc.)
• Prefer enums or structured objects for status fields

Summary

1.4 Naming Standards

Best Practices for JSON Design

Type Clarity

❌ Incorrect:

{ "price": "123.45" }

✅ Correct:

{ "price": 123.45 }

Recommendations:

• Use number for numeric fields
• Use string (e.g., ISO 8601) for time fields consistently

Use Enums or Booleans for Status

❌ Incorrect:

{ "status": 1 }

✅ Correct (Boolean):

{ "is_active": true }

✅ Correct (Enum):

{ "status": "active" }

Standard Error Response Format

❌ Incorrect:

{ "error_msg": "Invalid email", "code": 400 }

✅ Correct:

{
  "code": 400,
  "message": "Invalid request parameter",
  "error": {
    "field": "email",
    "reason": "Invalid format"
  }
}

Use JSON Schema for Structure Definition

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer",
      "minimum": 0
    }
  },
  "required": ["email"]
}

Benefits:

• Clear field constraints
• Automatic request/response validation
• Supports documentation and testing tools

Avoid Overuse of null

❌ Incorrect:

{ "nickname": null }

✅ Better:

{
  // simply omit "nickname" if not provided
}

✅ Keep null only when needed:

{ "nickname": null } // Explicitly indicates user cleared the field

Summary

EchoAPI Schema: Unified JSON Modeling

1. Visual Schema Designer

• Add or edit fields visually, set types, descriptions, and required status
• Drag-and-drop to reorder fields
• Supports nested objects, arrays, and references
• Instantly preview both schema and example JSON
• Manage reusable models by category for easier maintenance

2. Import Various Structure Files

Easily convert existing data formats into fully usable schemas:

• ✅ JSON examples
• ✅ JSON Schema
• ✅ XML
• ✅ MySQL DDL

This dramatically accelerates schema creation—especially helpful when onboarding legacy APIs or databases.

3. AI-Assisted Schema Completion

Save time and reduce manual errors with smart suggestions based on content and context.

4. Export & Standards Compatibility

EchoAPI is built with interoperability in mind:

• ✅ Export to OpenAPI 3.0
• ✅ Supports Swagger Editor for live preview
• ✅ Advanced JSON Schema support (anyOf, oneOf, $ref, etc.)
• ✅ One-click export of mock data, API documentation, and SDKs

5. Boost Frontend–Backend Alignment

Unified schemas ensure consistent expectations between frontend and backend developers, making integration smoother and reducing miscommunication.

6. Validate and Enforce Data Structure

Schemas in EchoAPI enforce field types, required rules, and value constraints—reducing bugs and increasing confidence in API stability.

7. High Reusability and Modularity

Extract shared structures as standalone schemas and reference them across multiple endpoints—promoting DRY principles and easier updates.

8. Flexible Field-Level Customization

Control validations like:

• Array length limits
• String minLength/maxLength
• Number ranges
• Enum sets, patterns, formats

9. Live Preview & Code Mode

Switch between visual editing and raw JSON Schema code for full flexibility—perfect for both beginners and power users.

10. Cross-Platform Toolchain Integration

EchoAPI supports:

• IntelliJ IDEA plugin
• VS Code plugin
• Chrome request capture extension

All without requiring a login. Lightweight, fast, and developer-friendly.

EchoAPI streamlines schema design with intelligent tools, visual editing, smart imports, and full standards support—making your API workflow faster, more consistent, and easier to maintain.

EchoAPI Documentation | EchoAPI

EchoAPI

What Is a Schema in API Development? Uses, Benefits, and Best Practices with EchoAPI

This article delves into what schemas are, their significance in API design, and how tools like EchoAPI can streamline the implementation and management of schemas to enhance API development

EchoAPISharvan Bhatra

Streamline Your API Design Workflow: Using Schemas with EchoAPI

Schemas are vital in API development, offering a structured way to define and validate data. They improve data integrity and streamline communication between services, ensuring consistency.

EchoAPIEchoAPI

Final Thoughts: Structure is Contract, Schema is Language

APIs are the language of interconnected systems, and JSON is their syntax. With EchoAPI, your team can:

• Minimize risk from structure changes
• Avoid miscommunication
• Accelerate front-end/back-end collaboration
• Keep documentation and code in sync
• Build a unified data structure standard

If you're designing complex APIs or aiming for more robust, intelligent JSON structures — EchoAPI Schema is worth a try.