Data Models & Schemas

Relevant source files

• .gitignore
• CONTRIBUTING.md
• README.md
• api/Conduit.postman_collection.json
• api/README.md
• api/openapi.yml
• apps/api/server/routes/api/articles/index.get.ts
• apps/documentation/src/assets/swagger.json
• apps/documentation/src/content/docs/specifications/frontend/api.md

This document provides a comprehensive reference for all data models and schemas defined in the RealWorld API specification. These schemas define the structure, properties, and validation rules for the core entities in the Conduit application: Users, Profiles, Articles, Comments, and Tags.

For information about how these schemas are used in API endpoints, see Endpoints Reference. For details on how these models are implemented in the database layer, see Database Layer & Prisma. For authentication-specific schemas and token handling, see Authentication & Authorization.

---

Schema Categories Overview

The API specification defines schemas organized into three categories: input schemas (used in requests), output schemas (returned in responses), and shared schemas (used in both).

Sources: api/openapi.yml455-643

---

User & Authentication Schemas

User (Output Schema)

The User schema represents the authenticated user's complete profile, including their JWT token. This schema is returned after successful registration, login, or profile updates.

Property	Type	Required	Nullable	Description
email	string	✓	✗	User's email address
token	string	✓	✗	JWT authentication token
username	string	✓	✗	User's unique username
bio	string	✓	✓	User's biography (can be null)
image	string	✓	✓	URL to user's profile image (can be null)

Sources: api/openapi.yml481-503

NewUser (Input Schema)

The NewUser schema defines the required fields for user registration.

Property	Type	Required	Format	Description
username	string	✓	-	Desired username (must be unique)
email	string	✓	-	Email address (must be unique)
password	string	✓	password	Plain text password (hashed server-side)

Sources: api/openapi.yml467-480

LoginUser (Input Schema)

The LoginUser schema defines the credentials needed for authentication.

Property	Type	Required	Format	Description
email	string	✓	-	User's email address
password	string	✓	password	User's password

Sources: api/openapi.yml456-466

UpdateUser (Input Schema)

The UpdateUser schema allows partial updates to user profile. All fields are optional, but at least one must be provided.

Property	Type	Required	Nullable	Description
email	string	✗	✗	New email address
password	string	✗	✗	New password
username	string	✗	✗	New username
bio	string	✗	✓	New biography
image	string	✗	✓	New profile image URL

Sources: api/openapi.yml504-520

---

Profile Schema

The Profile schema represents the public view of a user. Unlike the User schema, it does not include sensitive information like email addresses or authentication tokens.

Profile (Shared Schema)

Property	Type	Required	Nullable	Description
username	string	✓	✗	User's username
bio	string	✓	✓	User's biography (can be null)
image	string	✓	✓	URL to user's profile image (can be null)
following	boolean	✓	✗	Whether the current user follows this profile

Note: The following field is contextual - it indicates whether the currently authenticated user follows this profile. For unauthenticated requests, this field is always false.

Sources: api/openapi.yml521-540

---

Article Schemas

Article (Output Schema)

The Article schema represents a complete article with all its metadata, content, and relationships.

Article Schema Structure:

Property	Type	Required	Description
slug	string	✓	URL-friendly identifier (e.g., "how-to-train-your-dragon")
title	string	✓	Article title
description	string	✓	Brief description/summary
body	string	✓	Article content (Markdown supported)
tagList	string[]	✓	Array of tag names associated with the article
createdAt	string	✓	ISO 8601 timestamp of creation
updatedAt	string	✓	ISO 8601 timestamp of last update
favorited	boolean	✓	Whether current user favorited this article
favoritesCount	integer	✓	Total number of favorites
author	Profile	✓	Author's profile information

Important Notes:

• The slug is automatically generated from the title and must be unique
• Timestamps follow ISO 8601 format: YYYY-MM-DDTHH:mm:ss.sssZ
• The favorited field is contextual to the authenticated user
• The body field is omitted in list responses for performance (only included in single article responses)

Sources: api/openapi.yml541-578 api/Conduit.postman_collection.json370-382

NewArticle (Input Schema)

The NewArticle schema defines the required fields for creating an article.

Property	Type	Required	Description
title	string	✓	Article title (used to generate slug)
description	string	✓	Brief description
body	string	✓	Article content
tagList	string[]	✗	Optional array of tags

Sources: api/openapi.yml579-595

UpdateArticle (Input Schema)

The UpdateArticle schema allows partial updates to an article. All fields are optional.

Property	Type	Required	Description
title	string	✗	New title (will regenerate slug)
description	string	✗	New description
body	string	✗	New content

Note: The tagList cannot be updated through this schema. Tags are immutable after article creation.

Sources: api/openapi.yml596-604

---

Comment Schemas

Comment (Output Schema)

The Comment schema represents a comment on an article.

Comment Schema Structure:

Property	Type	Required	Description
id	integer	✓	Unique comment identifier
body	string	✓	Comment text content
createdAt	string	✓	ISO 8601 timestamp of creation
updatedAt	string	✓	ISO 8601 timestamp of last update
author	Profile	✓	Author's profile information

Sources: api/openapi.yml605-625

NewComment (Input Schema)

The NewComment schema defines the required fields for creating a comment.

Property	Type	Required	Description
body	string	✓	Comment text content

Sources: api/openapi.yml626-632

---

Tag Schema

Tags are represented as simple strings. The API does not define a separate Tag object schema; instead, tags are handled as:

• Arrays of strings in the Article schema (tagList property)
• An array of strings in the tags list response

Example Tags Response:

Sources: api/openapi.yml645-657

---

Schema Relationships & Data Flow

This diagram illustrates how schemas relate to each other and flow through the API lifecycle.

Sources: api/openapi.yml22-453

---

Property Nullability and Type Specifications

The OpenAPI 3.1 specification uses a specific syntax to indicate nullable fields. Understanding this is crucial for proper implementation.

Nullable String Fields

Several fields in the schemas can be either a string or null:

Nullable Fields by Schema:

Schema	Nullable Fields
User	bio, image
UpdateUser	bio, image
Profile	bio, image

Sources: api/openapi.yml497-503 api/openapi.yml513-520 api/openapi.yml532-538

---

Validation Rules & Constraints

Username Constraints

• Uniqueness: Must be unique across all users
• Required: Cannot be null or empty when creating a user
• Used in URLs: Appears in profile endpoints: /profiles/{username}

Email Constraints

• Uniqueness: Must be unique across all users
• Required: Cannot be null or empty when creating a user
• Format: Must be a valid email format (validated server-side)

Password Constraints

• Storage: Never returned in responses; hashed server-side
• Format: Specified as format: password in the schema
• Minimum Length: Implementation-dependent (not specified in schema)

Article Slug Constraints

• Uniqueness: Must be unique across all articles
• Generation: Auto-generated from title using URL-safe characters
• Immutability: Changes when title is updated
• Format: Lowercase, hyphenated (e.g., "how-to-train-your-dragon")

Timestamp Format

All timestamp fields use ISO 8601 format with timezone:

2024-01-15T14:30:00.000Z

Validated by Postman Tests:

Sources: api/Conduit.postman_collection.json373-376

---

Request/Response Wrapper Schemas

The API wraps all data models in envelope objects for consistency. This means schemas are never sent directly; they are always nested under a key.

Request Body Wrappers

Example Request Body:

Response Wrappers

Example Response:

Sources: api/openapi.yml817-889

---

Schema Composition in Responses

MultipleArticlesResponse Structure

The MultipleArticlesResponse has a unique structure that differs slightly from the main Article schema - it omits the body field for performance reasons.

Key Points:

• The articlesCount field represents the total number of articles matching the query, not the page size
• Individual articles in the array omit the body field (included only in single article responses)
• Pagination is controlled by offset and limit query parameters

Sources: api/openapi.yml693-741 api/Conduit.postman_collection.json800-804

---

Contextual Fields

Several fields in the schemas are contextual, meaning their values depend on the current authenticated user.

Favorited Field (Article)

• Type: boolean
• Context: Indicates whether the current user has favorited this article
• Unauthenticated: Always false
• Authenticated: true if the current user favorited it, false otherwise

Following Field (Profile)

• Type: boolean
• Context: Indicates whether the current user follows this profile
• Unauthenticated: Always false
• Authenticated: true if the current user follows this profile, false otherwise

Sources: api/openapi.yml573-575 api/openapi.yml539-540

---

Error Schema

The GenericErrorModel schema defines the structure for all error responses.

GenericErrorModel

Structure:

• errors (required): An object containing error details
• Keys are field names or error categories (e.g., "email", "password", "token", "resource")
• Values are arrays of error message strings

Common Error Keys:

Key	Context	Example Messages
email	User registration/login	["has already been taken"]
username	User registration	["has already been taken"]
token	Authentication	["is missing"], ["is invalid"]
resource	Resource access	["not found"], ["forbidden"]
title	Article creation	["can't be blank"]

Sources: api/openapi.yml633-643 api/openapi.yml773-816

---

Schema Summary Table

Schema	Category	Required Fields	Optional Fields	Nested Schemas
LoginUser	Input	email, password	-	-
NewUser	Input	username, email, password	-	-
User	Output	email, token, username, bio, image	-	-
UpdateUser	Input	-	email, password, username, bio, image	-
Profile	Shared	username, bio, image, following	-	-
NewArticle	Input	title, description, body	tagList	-
UpdateArticle	Input	-	title, description, body	-
Article	Output	slug, title, description, body, tagList, createdAt, updatedAt, favorited, favoritesCount, author	-	Profile
NewComment	Input	body	-	-
Comment	Output	id, body, createdAt, updatedAt, author	-	Profile
GenericErrorModel	Output	errors	-	-

Sources: api/openapi.yml455-643