Data Transfer Objects (DTOs)

Overview

Data Transfer Objects (DTOs) are used throughout the API to define the structure of data sent to and received from the endpoints. This page documents all DTOs available in the system.

All DTOs are implemented as C# records in the preliminarServicios.Models.Dtos namespace, providing immutable data structures with built-in validation.

Patient DTOs

CreatePacienteDto

Used for creating and updating patient records. Location: Models/Dtos/CreatePacienteDto.cs Structure:

nombre

string

required

Patient’s first nameValidation:

Required
Length: 3-100 characters
Pattern: ^[a-zA-ZáéíóúÁÉÍÓÚñÑ\s]+$ (letters and spaces only)
Error: “El nombre solo puede contener letras y espacios”

apellido

string

required

Patient’s last nameValidation:

Required
Length: 3-100 characters
Pattern: ^[a-zA-ZáéíóúÁÉÍÓÚñÑ\s]+$ (letters and spaces only)
Error: “El apellido solo puede contener letras y espacios”

dni

string

required

Patient’s national identity documentValidation:

Required
Pattern: ^\d{8}$ (exactly 8 digits)
Error: “El DNI debe tener exactamente 8 dígitos.”

string

required

Patient’s email addressValidation:

Required
Must be valid email format
Error: “El correo electrónico no es válido.”

telefono

string

Patient’s phone number (optional)Validation:

Optional (nullable)
Must match phone format if provided

fechaNacimiento

DateOnly

required

Patient’s date of birthValidation:

Required
Format: ISO 8601 date (YYYY-MM-DD)

Example:

{
  "nombre": "Juan",
  "apellido": "Pérez",
  "dni": "12345678",
  "email": "[email protected]",
  "telefono": "555-1234",
  "fechaNacimiento": "1990-05-15"
}

C# Definition:

public record class CreatePacienteDto(
    [Required] 
    [Length(3, 100)]
    [RegularExpression(@"^[a-zA-ZáéíóúÁÉÍÓÚñÑ\s]+$")] 
    string Nombre,
    
    [Required]
    [Length(3, 100)]
    [RegularExpression(@"^[a-zA-ZáéíóúÁÉÍÓÚñÑ\s]+$")] 
    string Apellido,
    
    [Required]
    [RegularExpression(@"^\d{8}$")]
    string Dni,

    [Required]
    [EmailAddress]
    string Email,
    
    [Phone]
    string? Telefono,
    
    [Required] DateOnly FechaNacimiento
);

PacienteResumenDto

Compact patient summary used in appointment listings. Location: Models/Dtos/PacienteResumenDto.cs Structure:

integer

required

Patient’s unique identifier

nombreCompleto

string

required

Patient’s full name (concatenated first and last name)

dni

string

required

Patient’s national identity document

Example:

{
  "id": 1,
  "nombreCompleto": "Juan Pérez",
  "dni": "12345678"
}

C# Definition:

public record class PacienteResumenDto(
    int Id,
    string NombreCompleto,
    string Dni
);

Doctor DTOs

CreateMedicoDto

Used for creating and updating doctor records. Location: Models/Dtos/CreateMedicoDto.cs Structure:

nombre

string

required

Doctor’s first nameValidation:

Required
Length: 3-100 characters
Pattern: ^[a-zA-ZáéíóúÁÉÍÓÚñÑ\s]+$ (letters and spaces only)
Error: “El nombre solo puede contener letras y espacios”

apellido

string

required

Doctor’s last nameValidation:

Required
Length: 3-100 characters
Pattern: ^[a-zA-ZáéíóúÁÉÍÓÚñÑ\s]+$ (letters and spaces only)
Error: “El apellido solo puede contener letras y espacios”

numeroLicencia

string

required

Doctor’s professional license numberValidation:

Required
Must be unique

telefono

string

Doctor’s phone number (optional)Validation:

Optional (nullable)
Must match phone format if provided

Example:

{
  "nombre": "Ana",
  "apellido": "Martínez",
  "numeroLicencia": "MED-12345",
  "telefono": "555-1111"
}

C# Definition:

public record class CreateMedicoDto(
    [Required] 
    [Length(3, 100)]
    [RegularExpression(@"^[a-zA-ZáéíóúÁÉÍÓÚñÑ\s]+$")]
    string Nombre,
    
    [Required] 
    [Length(3, 100)]
    [RegularExpression(@"^[a-zA-ZáéíóúÁÉÍÓÚñÑ\s]+$")]
    string Apellido,

    [Required] string NumeroLicencia,

    [Phone] string? Telefono
);

MedicoResumenDto

Compact doctor summary used in appointment listings, includes specialty information. Location: Models/Dtos/MedicoResumenDto.cs Structure:

integer

required

Doctor’s unique identifier

nombreCompleto

string

required

Doctor’s full name (concatenated first and last name)

especialidad

string

required

Name of the doctor’s medical specialty

Example:

{
  "id": 1,
  "nombreCompleto": "Ana Martínez",
  "especialidad": "Cardiología"
}

C# Definition:

public record class MedicoResumenDto(
    int Id,
    string NombreCompleto,
    string Especialidad
);

Specialty DTOs

CreateEspecialidadDto

Used for creating and updating medical specialties. Location: Models/Dtos/CreateEspecialidadDto.cs Structure:

nombre

string

required

Name of the medical specialtyValidation:

Required
Length: 3-100 characters
Pattern: ^[a-zA-ZáéíóúÁÉÍÓÚñÑ\s]+$ (letters and spaces only)
Error: “El nombre solo puede contener letras y espacios”
Must be unique

Example:

{
  "nombre": "Cardiología"
}

C# Definition:

public record class CreateEspecialidadDto(    
    [Required]
    [Length(3, 100)]
    [RegularExpression(@"^[a-zA-ZáéíóúÁÉÍÓÚñÑ\s]+$")]
    string Nombre
);

Appointment DTOs

CreateCitaDto

Used for creating and updating appointment records. Location: Models/Dtos/CreateCitaDto.cs Structure:

pacienteId

integer

required

ID of the patient for this appointmentValidation:

Required
Must reference an existing patient

medicoId

integer

required

ID of the doctor for this appointmentValidation:

Required
Must reference an existing doctor

costo

decimal

required

Cost of the appointmentValidation:

Required
Range: 0 to double.MaxValue
Error: “El costo debe ser un número positivo.”

motivo

string

required

Reason or purpose for the appointmentValidation:

Required

fechaInicio

DateTime

required

Start date and time of the appointmentValidation:

Required
Format: ISO 8601 DateTime

fechaFin

DateTime

required

End date and time of the appointmentValidation:

Required
Format: ISO 8601 DateTime

observaciones

string

Additional notes or observations (optional)Validation:

Optional (nullable)

Example:

{
  "pacienteId": 1,
  "medicoId": 1,
  "costo": 150.00,
  "motivo": "Consulta de control cardiológico",
  "fechaInicio": "2026-03-15T09:00:00",
  "fechaFin": "2026-03-15T09:30:00",
  "observaciones": "Primera consulta del año"
}

C# Definition:

public record class CreateCitaDto(
    [Required] 
    int PacienteId,
    
    [Required] 
    int MedicoId,
    
    [Required]
    [Range(0, double.MaxValue, ErrorMessage = "El costo debe ser un número positivo.")]
    decimal Costo,

    [Required]
    string Motivo,

    [Required]
    DateTime FechaInicio,
    
    [Required]
    DateTime FechaFin,
    
    string? Observaciones
);

CitaDto

Enriched appointment DTO with embedded patient and doctor summaries. Location: Models/Dtos/CitaDto.cs Structure:

integer

required

Appointment’s unique identifier

paciente

PacienteResumenDto

required

Summary of the patient information

Show PacienteResumenDto

integer

required

Patient’s ID

nombreCompleto

string

required

Patient’s full name

dni

string

required

Patient’s DNI

medico

MedicoResumenDto

required

Summary of the doctor information

Show MedicoResumenDto

integer

required

Doctor’s ID

nombreCompleto

string

required

Doctor’s full name

especialidad

string

required

Doctor’s specialty

fechaHora

DateTime

required

Date and time of the appointment

motivo

string

required

Reason for the appointment

estado

string

required

Status of the appointment (Pendiente, Confirmada, Cancelada, Completada)

Example:

{
  "id": 1,
  "paciente": {
    "id": 1,
    "nombreCompleto": "Juan Pérez",
    "dni": "12345678"
  },
  "medico": {
    "id": 1,
    "nombreCompleto": "Ana Martínez",
    "especialidad": "Cardiología"
  },
  "fechaHora": "2026-03-15T09:00:00",
  "motivo": "Consulta de control cardiológico",
  "estado": "Confirmada"
}

C# Definition:

public record class CitaDto(
    int Id,
    PacienteResumenDto Paciente,
    MedicoResumenDto Medico,
    DateTime FechaHora,
    string Motivo,
    string Estado
);

Entity Models vs DTOs

Key Differences

DTOs are used for data transfer between client and server, while Entities represent the database schema and domain models.

Aspect	DTOs	Entities
Purpose	Data transfer, validation	Database mapping, business logic
Location	`Models/Dtos/`	`Models/Entities/`
Type	Record classes (immutable)	Classes (mutable)
Validation	Data annotations	Required/optional modifiers
ID Field	Not included in Create DTOs	Always included
Relationships	Foreign key IDs	May include navigation properties

When to Use Each

Use DTOs for:

API request bodies (POST, PUT)
Returning simplified data structures
Aggregating data from multiple entities
Hiding sensitive fields

Use Entities for:

Database operations
Business logic
Data persistence
Internal application state

Validation Attributes

All DTOs use C# Data Annotations for validation:

Common Attributes

[Required] - Field cannot be null or empty
[Length(min, max)] - String length constraints
[RegularExpression(pattern)] - Pattern matching
[EmailAddress] - Valid email format
[Phone] - Valid phone format
[Range(min, max)] - Numeric range validation

Custom Error Messages

Many validation attributes include Spanish error messages:

[RegularExpression(@"^[a-zA-ZáéíóúÁÉÍÓÚñÑ\s]+$", 
    ErrorMessage = "El nombre solo puede contener letras y espacios")]

Overview

Endpoints

Data Transfer Objects

Overview

Patient DTOs

CreatePacienteDto

PacienteResumenDto

Doctor DTOs

CreateMedicoDto

MedicoResumenDto

Specialty DTOs

CreateEspecialidadDto

Appointment DTOs

CreateCitaDto

CitaDto

Entity Models vs DTOs

Key Differences

When to Use Each

Validation Attributes

Common Attributes

Custom Error Messages

Build docs developers (and LLMs) love

Overview

Endpoints

Data Transfer Objects

​Overview

​Patient DTOs

​CreatePacienteDto

​PacienteResumenDto

​Doctor DTOs

​CreateMedicoDto

​MedicoResumenDto

​Specialty DTOs

​CreateEspecialidadDto

​Appointment DTOs

​CreateCitaDto

​CitaDto

​Entity Models vs DTOs

​Key Differences

​When to Use Each

​Validation Attributes

​Common Attributes

​Custom Error Messages

​Related Resources

Build docs developers (and LLMs) love

Overview

Patient DTOs

CreatePacienteDto

PacienteResumenDto

Doctor DTOs

CreateMedicoDto

MedicoResumenDto

Specialty DTOs

CreateEspecialidadDto

Appointment DTOs

CreateCitaDto

CitaDto

Entity Models vs DTOs

Key Differences

When to Use Each

Validation Attributes

Common Attributes

Custom Error Messages

Related Resources