Diseño de Esquemas JSON para Interfaces, Colecciones y Validaciones: Una Guía de Ingeniería

Introducción En el desarrollo de sistemas modernos, particularmente aquellos que requieren manejo de datos entre diferentes capas (frontend, backend y almacenamiento), es crucial diseñar estructuras claras, consistentes y escalables. Un esquema JSON bien diseñado puede centralizar la configuración de campos, validaciones, y traducciones, permitiendo una mayor eficiencia en el desarrollo y mantenimiento. Este artículo explora un diseño ampliado para representar interface-input, interface-output y collection, proporcionando ejemplos y razones de ingeniería.

El Modelo Ampliado El siguiente esquema JSON amplía la representación de campos para incluir:

• interface-input: Datos que se reciben desde el cliente o sistema externo.

• interface-output: Datos que se envían de vuelta al cliente o sistema externo.

• collection: Campos almacenados en la base de datos.

Esquema JSON Propuesto

{
  "fields": [
    {
      "name": "id",
      "type": "integer",
      "in": ["interface-output", "collection"],
      "validations": {
        "collection": ["primaryKey", "autoincrement"]
      },
      "description": "Identificador único del registro."
    },
    {
      "name": "username",
      "type": "string",
      "in": ["interface-input", "interface-output", "collection"],
      "validations": {
        "interface-input": {
          "required": {
            "message": {
              "en": "Username is required.",
              "es": "El nombre de usuario es obligatorio."
            }
          },
          "minLength": {
            "value": 3,
            "message": {
              "en": "Username must be at least 3 characters long.",
              "es": "El nombre de usuario debe tener al menos 3 caracteres."
            }
          },
          "maxLength": {
            "value": 50,
            "message": {
              "en": "Username must not exceed 50 characters.",
              "es": "El nombre de usuario no debe exceder los 50 caracteres."
            }
          }
        },
        "collection": ["unique", "notNull"]
      },
      "translate": {
        "label": {
          "en": "Username",
          "es": "Nombre de usuario"
        },
        "placeholder": {
          "en": "Enter your username",
          "es": "Ingresa tu nombre de usuario"
        }
      }
    },
    {
      "name": "password",
      "type": "string",
      "in": ["interface-input"],
      "validations": {
        "interface-input": {
          "required": {
            "message": {
              "en": "Password is required.",
              "es": "La contraseña es obligatoria."
            }
          },
          "minLength": {
            "value": 8,
            "message": {
              "en": "Password must be at least 8 characters long.",
              "es": "La contraseña debe tener al menos 8 caracteres."
            }
          },
          "regex": {
            "value": "^(?=.*[A-Za-z])(?=.*\\d)[A-Za-z\\d@$!%*?&]{8,}$",
            "message": {
              "en": "Password must contain at least one letter and one number.",
              "es": "La contraseña debe contener al menos una letra y un número."
            }
          }
        }
      },
      "translate": {
        "label": {
          "en": "Password",
          "es": "Contraseña"
        },
        "placeholder": {
          "en": "Enter your password",
          "es": "Ingresa tu contraseña"
        }
      }
    },
    {
      "name": "email",
      "type": "string",
      "in": ["interface-input", "interface-output", "collection"],
      "validations": {
        "interface-input": {
          "required": {
            "message": {
              "en": "Email is required.",
              "es": "El correo electrónico es obligatorio."
            }
          },
          "regex": {
            "value": "^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$",
            "message": {
              "en": "Enter a valid email address.",
              "es": "Ingresa una dirección de correo electrónico válida."
            }
          }
        },
        "collection": ["unique", "notNull"]
      },
      "translate": {
        "label": {
          "en": "Email",
          "es": "Correo Electrónico"
        },
        "placeholder": {
          "en": "Enter your email",
          "es": "Ingresa tu correo electrónico"
        }
      }
    },
    {
      "name": "created_at",
      "type": "datetime",
      "in": ["interface-output", "collection"],
      "validations": {
        "collection": ["notNull", "default:CURRENT_TIMESTAMP"]
      },
      "translate": {
        "label": {
          "en": "Creation Date",
          "es": "Fecha de Creación"
        }
      }
    }
  ]
}

Razones de Diseño

1. Separación de Responsabilidades:

   • interface-input: Representa los datos que el usuario o sistema externo envía al sistema. Incluye validaciones específicas para garantizar la calidad de los datos recibidos.

   • interface-output: Contiene los datos expuestos hacia el cliente, evitando exponer información sensible o innecesaria.

   • collection: Define los datos persistidos en la base de datos, así como las reglas que aseguran la integridad referencial y unicidad.

2. Validaciones Contextuales:

   • Se diferencian las reglas de validación para inputs de usuario y reglas de integridad de datos en la base de datos.

   • Mensajes traducibles permiten una experiencia de usuario adaptada a idiomas locales.

3. Traducciones Incorporadas:

   • Campos como label y placeholder se adaptan a diferentes idiomas, mejorando la internacionalización del sistema.

4. Escalabilidad:

   • Agregar nuevos idiomas o campos es sencillo gracias a la estructura modular del JSON.

Conclusión Este diseño JSON proporciona una base clara y estructurada para manejar datos en sistemas modernos, garantizando separación de responsabilidades, escalabilidad y una experiencia de usuario mejorada. Implementar un esquema como este permite centralizar reglas y traducciones, reduciendo errores y facilitando la evolución del sistema.