Muoversi lombardia: glossario

[ioggstream]

@stefkohub.

Le info di glossario non le metterei direttamente qui ma in components.schemas.

Guarda in questo draft come le informazioni di glossario siano indicate sia sulla classe che per campo.

https://github.com/teamdigitale/api-openapi-samples/blob/master/external-apis/spid-aa.yaml#L109

Un parser può semplicemente ricostruire tutto il gioco leggendo lo yaml e ricavare l'informazione completa e aggiornata.

eg.

    Point:
      externalDocs:
         url: URL VERSO IL GLOSSARIO
         x-glossary: true
      description: Un punto sulla mappa. Questo e' definito in un glossario e linkato tramite externalDocs
         oppure potremmo definire un x-glossary a questo livello.
      type: object
      properties:
        label:
          type: string
        type:
          type: string
        x:
          '$ref': '#/components/schemas/Longitudine'
        y:
          '$ref': '#/components/schemas/Latitudine'
      example:
        label: Rogoredo M3
        type: areadifermata
        x: 9.237421
        y: 45.433681

[stefkohub]

Sono d'accordo sul posizionare le info di glossario in components.schemas.

A tal proposito ti propongo una struttura come questa:

components:
  schemas:
    taxCode:
      $ref: '#/components/x-glossary/teamdigitale/TaxCode'
    Problem:
      $ref: '#/components/x-glossary/teamdigitale/Problem'

  x-glossary:
    teamdigitale:
      TaxCode:
        $ref: "https://raw.githubusercontent.com/teamdigitale/openapi/master/docs/schemas/tax_code.yaml#/TaxCode"
      Problem:
        $ref: "https://raw.githubusercontent.com/teamdigitale/openapi/0.0.1/docs/schemas/problem.yaml#/Problem"
      description: "Glossario definito dal Team Digitale"
      publisher: Team Digitale
      ecosystem: Eventuale Ecosistema
      version: Versione

In questo modo abbiamo:

1. la possibilità di definire modelli a partire da un glossario esterno definito
2. la possibilità di definire più di un glossario a cui fare riferimento negli schema
3. la possibilità di descrivere in termini business, con i campi opzionali description, publisher, ecosystem e version lo specifico glossario

[ioggstream]

Ciao @stefkohub

• capito l'obiettivo
• potremmo farlo nel file sorgente (eg. schemas/glossario-muoversi.yaml#/x-glossary/Tax-Code)
• non cambierei l'alberatura di OAS invece. Il glossario, come la definizione gdpr lo ricaverei dai datatype, non dall'API.

[stefkohub]

Concordo, la struttura x-glossary può andare in un YAML separato, e contenere sia le informazioni dei datatype che le informazioni "di business" accessorie.