¿Cómo describir los datos JSON en una especificación?

Question

¿Cuál es la mejor manera de describir datos JSON en una especificación?

En el pasado he usado ejemplos con descripciones "verbales", pero se siente impreciso.

Parece haber una nueva norma JSON schema, pero no parece un proyecto muy activo. ¿Alguna otra manera?

---

(actualización) Después de pensar en esto durante varios días me gusta bmargulies sugerencia alrededor de usar una convención de conversión. Dado que los documentos JSON en este caso, nuestra salida de los servicios web .NET voy a simplemente documentar el esquema con la sintaxis de la clase C#. Esto puede no ser totalmente riguroso, pero todos los involucrados lo entenderán y, junto con los ejemplos, transmitirán el mensaje lo más rápido posible.

Answer 1

¿Qué tal si usamos algún tipo de BNF extendido?

PERSON <- { "firstname": FIRSTNAMES, "lastname": LASTNAME, "age": AGE, "version": VERSION, "parents" <- PARENTS } 

FIRSTNAMES <- [ FIRSTNAME+ ] 

FIRSTNAME <- STRING 

LASTNAME <- STRING 

PARENTS <- [ PERSON{0,2} ] 

AGE <- INTEGER 

VERSION <- 1 | 2 

Tendría que definir el significado de las descripciones de tipo atómico como INTEGER y STRING en algún lugar. Si desea agregar teclas no hardcoded para los diccionarios, definiría eso como sigue:

BREADLOOKUP <- { (TYPE : HOWMANY)+ } 

TYPE <- "white" | "dark" | "french" | "croissant" 

HOWMANY <- POSITIVE-INTEGER 

Esto permitiría cosas como

{ "white": 5, 
    "french": 2 
} 

Dado que ambas expresiones regulares y BNF son bastante bien conocidos, este podría ser una manera fácil de ir. ?, +, *, {n}, {min,max} serían formas fáciles de especificar una serie de elementos (tomados de expresiones regulares) y el resto es más o menos puro BNF.

Si lo hizo con la rigurosidad suficiente, incluso podría ser analizable para un validador.

Answer 2

Puede combinar un Esquema XML de W3C, o un esquema menos desagradable como RelaxNG, con las convenciones de conversión.

Answer 3

Sé que esto es una cuestión mayor, pero que podría ser útil a alguien más: En la búsqueda de métodos para describir los datos JSON-me topé Orderly. Aquí está el derecho abstracto de la portada:

Ordenada es un formato de texto para describir JSON. Orderly se puede compilar en JSONSchema. Está diseñado para ser fácil de leer y escribir.

Estoy de acuerdo con eso, pero hasta ahora solo lo he probado con estructuras relativamente simples.

Answer 4

Recomendaría mi biblioteca de JavaScript js-schema. La principal motivación detrás de esto fue lo mismo que describes en la pregunta. Es una notación simple y fácil de entender para describir esquemas JSON (o especificación, si lo desea).

Un esquema de ejemplo descrito en JSON esquema:

{ 
    "type":"object", 
    "properties":{ 
    "id":{ 
     "type":"number", 
     "required":true 
    }, 
    "name":{ 
     "type":"string", 
     "required":true 
    }, 
    "price":{ 
     "type": "number", 
     "minimum":0, 
     "required":true 
    }, 
    "tags":{ 
     "type":"array", 
     "items":{ 
     "type":"string" 
     } 
    } 
    } 
} 

y la misma descripción esquema con js-esquema:

{ 
    "id" : Number, 
    "name" : String, 
    "price" : Number.min(0), 
    "?tags" : Array.of(String) 
} 

La biblioteca es capaz de validar objeto contra esquemas, generar objetos aleatorios conforme a un esquema dado, y serializar/deserializar a/desde el esquema JSON.