Header Ads Widget

Ticker

6/recent/ticker-posts

Una guía para el esquema JSON

 


Las API y JSON están irrevocablemente entrelazados. JSON es el formato más común para intercambiar datos a través de Internet. Muchos desarrolladores recomiendan usar el formato JSON debido a sus muchos beneficios , que son especialmente beneficiosos para las API.

Sin embargo, si alguna vez ha trabajado con una instancia JSON desde la línea de comandos, sabrá que cuando se deja en sus propios dispositivos, el JSON puede volverse bastante difícil de manejar. Y aunque la mayoría de las API funcionan con JSON, no hay garantía de que el consumidor pueda interactuar con elegancia con los datos en este formato. Un archivo de esquema tiene como objetivo arreglar todo eso.

Los desarrolladores han intervenido para llenar ese vacío. A continuación, veremos JSON Schema , un lenguaje de especificación para JSON. Cubriremos lo que es, si lo necesita, y revisaremos brevemente la puesta en marcha para que pueda probarlo por sí mismo.

Introducción al esquema JSON

Para aquellos que son nuevos en el tema, JSON son las siglas de JavaScript Object Notation. JSON es una forma conveniente de transmitir una gran cantidad de datos pertenecientes a una consulta, que se devuelve como una serie de elementos emparejados. Suele ser un diccionario, pero la raíz de la instancia puede ser una matriz, un booleano, un número o una cadena.

Por ejemplo, imagina que estás solicitando todos los datos pertenecientes a un empleado:

{
   "employee":{
      "name":"sonoo",
      "salary":56000,
      "married":true
   }
}

Bastante simple, ¿verdad? Simplemente consulte por empleados y obtendrá valores de nombre , salario y estado civil como respuesta.

Ahora considere este ejemplo en su lugar.

{
   "medications":[
      {
         "aceInhibitors":[
            {
               "name":"lisinopril",
               "strength":"10 mg Tab",
               "dose":"1 tab",
               "route":"PO",
               "sig":"daily",
               "pillCount":"#90",
               "refills":"Refill 3"
            }
         ],
         "antianginal":[
            {
               "name":"nitroglycerin",
               "strength":"0.4 mg Sublingual Tab",
               "dose":"1 tab",
               "route":"SL",
               "sig":"q15min PRN",
               "pillCount":"#30",
               "refills":"Refill 1"
            }
         ],
         "anticoagulants":[
            {
               "name":"warfarin sodium",
               "strength":"3 mg Tab",
               "dose":"1 tab",
               "route":"PO",
               "sig":"daily",
               "pillCount":"#90",
               "refills":"Refill 3"
            }
         ],
         "betaBlocker":[
            {
               "name":"metoprolol tartrate",
               "strength":"25 mg Tab",
               "dose":"1 tab",
               "route":"PO",
               "sig":"daily",
               "pillCount":"#90",
               "refills":"Refill 3"
            }
         ],
         "diuretic":[
            {
               "name":"furosemide",
               "strength":"40 mg Tab",
               "dose":"1 tab",
               "route":"PO",
               "sig":"daily",
               "pillCount":"#90",
               "refills":"Refill 3"
            }
         ],
         "mineral":[
            {
               "name":"potassium chloride ER",
               "strength":"10 mEq Tab",
               "dose":"1 tab",
               "route":"PO",
               "sig":"daily",
               "pillCount":"#90",
               "refills":"Refill 3"
            }
         ]
      }
   ],
   "labs":[
      {
         "name":"Arterial Blood Gas",
         "time":"Today",
         "location":"Main Hospital Lab"
      },
      {
         "name":"BMP",
         "time":"Today",
         "location":"Primary Care Clinic"
      },
      {
         "name":"BNP",
         "time":"3 Weeks",
         "location":"Primary Care Clinic"
      },
      {
         "name":"BUN",
         "time":"1 Year",
         "location":"Primary Care Clinic"
      },
      {
         "name":"Cardiac Enzymes",
         "time":"Today",
         "location":"Primary Care Clinic"
      },
      {
         "name":"CBC",
         "time":"1 Year",
         "location":"Primary Care Clinic"
      },
      {
         "name":"Creatinine",
         "time":"1 Year",
         "location":"Main Hospital Lab"
      },
      {
         "name":"Electrolyte Panel",
         "time":"1 Year",
         "location":"Primary Care Clinic"
      },
      {
         "name":"Glucose",
         "time":"1 Year",
         "location":"Main Hospital Lab"
      },
      {
         "name":"PT/INR",
         "time":"3 Weeks",
         "location":"Primary Care Clinic"
      },
      {
         "name":"PTT",
         "time":"3 Weeks",
         "location":"Coumadin Clinic"
      },
      {
         "name":"TSH",
         "time":"1 Year",
         "location":"Primary Care Clinic"
      }
   ],
   "imaging":[
      {
         "name":"Chest X-Ray",
         "time":"Today",
         "location":"Main Hospital Radiology"
      },
      {
         "name":"Chest X-Ray",
         "time":"Today",
         "location":"Main Hospital Radiology"
      },
      {
         "name":"Chest X-Ray",
         "time":"Today",
         "location":"Main Hospital Radiology"
      }
   ]
}

Este JSON podría ser la base de datos de un hospital representada como una serie de objetos JavaScript. Cuenta con JSON anidado para diferentes departamentos, desde información sobre medicamentos hasta la ubicación de diferentes departamentos.

Como puede ver en este ejemplo, JSON puede volverse sumamente complicado rápidamente. Es posible anidar opciones de JavaScript y matrices, que rápidamente pueden volverse bastante abrumadoras. También es un ejemplo de cuánto es posible cuando se usa JSON.

Las instancias complejas y largas no son el único problema con el que se puede encontrar al usar JSON. Las aplicaciones a menudo necesitan validar un objeto JSON para asegurarse de que se cumplan algunos criterios. Sin un esquema, una aplicación solo puede indicar que un objeto JSON está formateado correctamente. No puede decir qué hay en el objeto.

Aquí es donde entra en juego JSON Schema.

JSON Schema es un lenguaje para describir el contenido, la estructura y la semántica de la instancia JSON. Le permite aplicar metadatos sobre las propiedades de un objeto, que a su vez se enumeran como JSON. El esquema JSON dicta qué campos existen, si ese campo es opcional y qué formato de datos puede esperar el consumidor.

A continuación, se muestra un ejemplo de un esquema JSON:

{
   "$schema":"https://json-schema.org/draft/2020-12/schema",
   "title":"Person",
   "description":"A person",
   "type":"object",
   "properties":{
      "name":{
         "description":"A person's name",
         "type":"string"
      },
      "age":{
         "description":"A person's age",
         "type":"number",
         "minimum":18,
         "maximum":64
      }
   },
   "required":[
      "name",
      "age"
   ]
}

Aquí hay un objeto JSON en sí mismo:

{
   "name":"John Doe",
   "age":35
}

Con el esquema JSON, el consumidor de API sabe que el nombre del cliente es "John Doe" y su edad es "35".

Una aplicación que comprende lo que hay dentro de un objeto JSON hace que sea mucho más fácil devolver datos dentro de restricciones particulares. Por ejemplo, puede consultar para devolver solo a los empleados de 30 años o solo a los empleados que estén casados.

Beneficios del esquema JSON

JSON está destinado a devolver datos en un formato que sea legible por humanos y máquinas por igual. Sin embargo, sin un poco de ajuste, a veces no es ninguna de las dos cosas. Una ventaja de usar JSON Schema es que hace que JSON sea más inteligible tanto para las computadoras como para los usuarios.

Uno de los beneficios más populares de JSON Schema es su utilidad para la prueba y validación de API. Por ejemplo, supongamos que su API solo puede manejar nombres que tengan menos de 20 caracteres. O imagine que solo desea enviar correos electrónicos de un rango de fechas en particular a su base de datos.

Como señalamos antes, implementar esto no es fácil cuando el consumidor de API no sabe qué hay dentro de la instancia JSON. Sin un esquema en su lugar, una aplicación podría decir que hay algo allí, pero el contenido en sí será un misterio.

El uso de JSON Schema también evita que tenga que realizar demasiados cambios en el lado del cliente. Un enfoque común pero equivocado para crear aplicaciones API del lado del cliente es hacer una lista de los códigos HTML comunes y luego implementarlos en el lado del cliente. Sin embargo, este no es el mejor enfoque, ya que algunas funciones pueden fallar si algo cambia en el lado del servidor.

“El beneficio principal de usar JSON Schema es su interoperabilidad entre muchos lenguajes de programación; la consistencia y confiabilidad de la validación. Una buena implementación utilizará la suite de pruebas oficial, asegurando la interoperabilidad y la correcta validación. Las organizaciones que publican API a menudo proporcionan esquemas JSON para sus cargas de datos y expectativas, lo que permite a los desarrolladores saber qué se requiere y a las computadoras validar de manera confiable ". - Ben Hutton, jefe de especificación de esquema JSON en Postman

Un beneficio final de usar JSON Schema que mencionaremos hoy (hay muchos) es que ya hay una serie de activos preescritos disponibles. JSON Schema se ha vuelto bastante popular, por lo que existen bibliotecas para validadores JSON para la mayoría de los lenguajes de programación populares.

Las bibliotecas para la validación de esquemas JSON incluyen:

IDIOMABIBLIOTECA
.NETOEsquema Json.NET
CWJElement
Clojuregafe
Vamosgojsonschema
JavaScriptajv
Pitónjschon
RubíJSONSchemer
PHPOpis Json Schema
KotlinMedeia-validador

Introducción al esquema JSON

Ahora echemos un vistazo rápido a cómo puede usar JSON Schema por sí mismo para que pueda probarlo dentro de su propio proyecto.

Creemos un objeto JSON para el catálogo de una tienda de mascotas. Un artículo individual en el catálogo incluye:

  • Un identificador: productID
  • Nombre del producto: productName
  • Precio de coste
  • Información adicional: etiquetas

Un objeto JSON para ese catálogo podría verse así:

{
   "productId":1,
   "productName":"Kibble",
   "price":12.50,
   "tags":[
      "food",
      "dogs"
   ]
}

Un esquema JSON básico contiene cuatro puntos de datos principales.

  • $schema declara qué borrador de esquema JSON estás usando
  • $id declara un URI que será el URI base con el que se compararán otras referencias de URI.
  • El título y la descripción son meramente descriptivos
  • El tipo le dice al consumidor qué tipo de objeto puede esperar.

Un ejemplo de un esquema JSON básico podría ser:

{
   "$schema":"https://json-schema.org/draft/2020-12/schema",
   "$id":"https://example.com/product.schema.json",
   "title":"Product",
   "description":"A product in the catalog",
   "type":"object"
}

Definición de las propiedades

Ahora veamos cómo se vería un ejemplo real de JSON Schema.

{
   "$schema":"https://json-schema.org/draft/2020-12/schema",
   "$id":"https://example.com/product.schema.json",
   "title":"Product",
   "description":"A product from pet store's catalog",
   "type":"object",
   "properties":{
      "productId":{
         "description":"The unique identifier for a product",
         "type":"integer"
      }
   },
   "required":[
      "productId"
   ]
}

¿Hasta aquí todo bien, no? Todo esto es bastante sencillo. Pero, ¿Qué sucede cuando un esquema JSON se involucra más?

Anidamiento de estructuras de datos

Ahora echemos un vistazo a un esquema JSON un poco más detallado.

{
   "$schema":"https://json-schema.org/draft/2020-12/schema",
   "$id":"https://example.com/product.schema.json",
   "title":"Product",
   "description":"A product from pet store's catalog",
   "type":"object",
   "properties":{
      "productId":{
         "description":"The unique identifier for a product",
         "type":"integer"
      },
      "productName":{
         "description":"Name of the product",
         "type":"string"
      },
      "price":{
         "description":"The price of the product",
         "type":"number",
         "exclusiveMinimum":0
      },
      "tags":{
         "description":"Tags for the product",
         "type":"array",
         "items":{
            "type":"string"
         },
         "minItems":1,
         "uniqueItems":true
      },
      "dimensions":{
         "type":"object",
         "properties":{
            "length":{
               "type":"number"
            },
            "width":{
               "type":"number"
            },
            "height":{
               "type":"number"
            }
         },
         "required":[
            "length",
            "width",
            "height"
         ]
      }
   },
   "required":[
      "productId",
      "productName",
      "price"
   ]
}

Aquí puede ver que se ha agregado una entrada de dimensiones y que los objetos JSON anidados se han atribuido a la variable de propiedades . Cuando sigue este formato, puede agregar tantas propiedades como necesite, y el consumidor de API siempre las entenderá correctamente.

Esquema JSON: pensamientos finales

Es seguro decir que la validación y las pruebas de API continuarán siendo más críticas a medida que las API continúen siendo más frecuentes. También es seguro asumir que JSON probablemente no se volverá menos complicado a medida que avanza el tiempo.

Esto significa que tener un esquema para sus datos también seguirá siendo más importante de aquí en adelante. Esto hace que JSON Schema sea una opción ideal para quienes trabajan con API, ya que JSON es el formato de archivo preferido para trabajar con API.

Mirando hacia el futuro de JSON Schema, Ben Hutton dijo lo siguiente:

“Con la adición de dialectos y vocabularios, refinados en nuestra última publicación (borrador 2020-12), JSON Schema ahora tiene una base sobre la cual se pueden construir extensiones estandarizadas para otros casos de uso. Ya estamos trabajando para formar dos Grupos de Interés Especial (SIG) líderes en la industria para la generación de código y bases de datos. Algunas extensiones ya existen, pero no son estándar ".

Publicar un comentario

0 Comentarios