RAML: Schemi nidificati

Question

1) Quando si scrive RAML, è possibile utilizzare l'annidamento nella definizione dello schema?

Ad esempio:

schemas: 
    - DNSResponse: | 
     { 
     "type": "object", 
     "properties": { 
      "AnswerSection": { 
       "type": "array", 
       "items": (((I want a re-useable schema here. ex: ARecord))) 
      }, 
      "AA": {"type": "boolean"}, 
      "AD": {"type": "boolean"}, 
      ... 
     } 
     } 
    - ARecord: | 
     { 
     "type": "object", 
     "properties": { 
      "address": "string", 
      "ttl": "number", 
      "name": "string" 
     } 
     } 

2) Posso utilizzare una delle scelte/enum su una serie di schemi nidificabili?

"items": [ARecord, MXRecord, PTRRecord, ...] 

Answer 1

1) Sì, è possibile. Vedi this example. Che sarebbe:

"items": { "$ref": "ARecord" } 

2) Credo che questo è possibile in Draft 4 di JSON Schema, usando la direttiva oneOf. Non penso che questo sia supportato da RAML però. In alternativa, è possibile creare uno schema di base e disporre di ARecord, MXRecord e PTRRecord estendere questo schema di base e quindi consentire gli elementi dello schema di base. Questo non sarà molto semanticamente ricco ma potrebbe farti iniziare.

Answer 2

Dal momento che la tua domanda non è al 100% richiede JSON, vorrei aggiungere questo nelle risposte ...

Con il rilascio delle specifiche Raml 1.0, è possibile utilizzare types, che ti permette di fare proprio questo (in quello che considero leggermente più pulito).

Ecco il link di riferimento: http://docs.raml.org/specs/1.0/#raml-10-spec-types

Raml 1.0 introduce la nozione di tipi di dati, che forniscono un modo conciso e potente per descrivere i dati nel vostro API. I dati possono essere in un parametro URI (URI di base o di risorsa), un parametro di query, un'intestazione di richiesta o di risposta o, naturalmente, un corpo di richiesta o di risposta. Alcuni tipi sono incorporati, mentre i tipi personalizzati possono essere definiti estendendo (ereditando da) i tipi predefiniti. In qualsiasi posto in cui l'API si aspetta dati, un tipo incorporato può essere usato per descrivere i dati, o un tipo può essere esteso in linea per descrivere quei dati. I tipi di CustomSecurityScheme possono anche essere nominati e quindi utilizzati come qualsiasi tipo built-in.

E per coloro che vogliono meno testo e altri esempi (tratto da documentazione Raml):

#%RAML 1.0 
title: API with Types 
types: 
    User: 
    type: object 
    properties: 
     firstname: string 
     lastname: string 
     age:  number 
/users/{id}: 
    get: 
    responses: 
     200: 
     body: 
      application/json: 
      type: User 

Answer 3

penso che il seguente esempio si applica qui. Dimostra la definizione di due tipi Url e File (utilizzando RAML 1.0) e quindi utilizzando l'OR logico per consentire uno dei due tipi (schema aka) in Item come sottoschema. Potresti potenzialmente includere più tipi se necessario.

Ho anche definito alcuni esempi in linea che dimostrano come funziona se si utilizza il raml-parser.

#%RAML 1.0 
types: 
    Url: 
     properties: 
      url: 
       type: string 
       example: http://www.cats.com/kittens.jpg 
       description: | 
        The url to ingest. 

    File: 
     properties: 
      filename: 
       type: string 
       example: kittens.jpg 
       description: | 
        Name of the file that will be uploaded. 


    Item: 
     description: | 
      An example of a allowing multiple types using RAML 1.0 
     properties: 
      ext: 
       type: File | Url 
     examples: 
      file_example: 
       content: 
        ext: 
         filename: video.mp4 
      url_example: 
       content: 
        ext: 
         url: http://heres.a.url.com/asset.jpg 
      should_fail: 
       content: 
        ext: 
         unexpected: blah