{
  "openapi": "3.1.0",
  "info": {
    "title": "Cybersecurity Database – Open Data API",
    "version": "1.0.0",
    "description": "API pubblica in sola lettura, composta da file statici rigenerati a ogni build. Metadati e riassunti con licenza CC BY 4.0. / Read-only public API made of static files regenerated at every build. Metadata and summaries licensed CC BY 4.0.",
    "license": {
      "name": "CC BY 4.0",
      "url": "https://creativecommons.org/licenses/by/4.0/"
    }
  },
  "servers": [
    {
      "url": "https://www.cybersecuritydatabase.org/api/v1"
    }
  ],
  "paths": {
    "/documents.json": {
      "get": {
        "summary": "Tutti i documenti pubblicati / All published documents",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "license": {
                      "type": "string"
                    },
                    "updated_at": {
                      "type": "string"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "documents": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Document"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/documents.csv": {
      "get": {
        "summary": "Tutti i documenti in CSV / All documents as CSV",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "text/csv": {}
            }
          }
        }
      }
    },
    "/documents/{slug}.json": {
      "get": {
        "summary": "Un documento / One document",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "document": {
                      "$ref": "#/components/schemas/Document"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/jurisdictions.json": {
      "get": {
        "summary": "Paesi e organizzazioni / Countries and organisations",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jurisdictions": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Jurisdiction"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/jurisdictions/{code}.json": {
      "get": {
        "summary": "Una giurisdizione con i suoi documenti / One jurisdiction with its documents",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "description": "ISO 3166-1 alpha-2 in minuscolo o codice organizzazione (eu, coe, un, nato, itu)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "jurisdiction": {
                      "$ref": "#/components/schemas/Jurisdiction"
                    },
                    "documents": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Document"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/taxonomies.json": {
      "get": {
        "summary": "Tassonomie con etichette / Taxonomies with labels",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Document": {
        "title": "Document",
        "description": "Un documento di policy sulla cybersecurity (strategia, legge, regolamento, decreto, direttiva, linea guida, documento internazionale). Un file YAML per documento in data/documents/<slug>.yaml.",
        "type": "object",
        "required": [
          "id",
          "slug",
          "title_original",
          "document_type",
          "jurisdiction",
          "issuing_body",
          "date_adopted",
          "status",
          "languages",
          "summary",
          "topics",
          "source_url",
          "license",
          "ingested_from",
          "verified_at",
          "verified_by",
          "editorial_status",
          "created_at",
          "updated_at"
        ],
        "$defs": {
          "partialDate": {
            "description": "Data completa (AAAA-MM-GG) o parziale (AAAA-MM, AAAA) quando il giorno non è noto con certezza.",
            "type": "string",
            "pattern": "^\\d{4}(-\\d{2}(-\\d{2})?)?$"
          },
          "slug": {
            "type": "string",
            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
          },
          "localized": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "en"
            ],
            "properties": {
              "it": {
                "type": "string",
                "minLength": 1
              },
              "en": {
                "type": "string",
                "minLength": 1
              },
              "fr": {
                "type": "string",
                "minLength": 1
              },
              "es": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        },
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "slug": {
            "$ref": "#/components/schemas/Document/$defs/slug"
          },
          "title_original": {
            "type": "string",
            "minLength": 1
          },
          "title_en": {
            "type": "string"
          },
          "title_it": {
            "type": "string"
          },
          "title_fr": {
            "type": "string"
          },
          "title_es": {
            "type": "string"
          },
          "document_type": {
            "enum": [
              "strategy",
              "action_plan",
              "law",
              "regulation",
              "decree",
              "directive",
              "guideline",
              "circular",
              "international"
            ]
          },
          "strategy_form": {
            "description": "Solo per le strategie: autonoma o capitolo di un documento più ampio (ICT, digitale, sicurezza nazionale).",
            "enum": [
              "standalone",
              "chapter"
            ]
          },
          "jurisdiction": {
            "type": "string",
            "pattern": "^[A-Z]{2}$|^[A-Z][A-Za-z]{1,9}$"
          },
          "issuing_body": {
            "type": "string",
            "minLength": 1
          },
          "official_number": {
            "type": "string"
          },
          "date_adopted": {
            "$ref": "#/components/schemas/Document/$defs/partialDate"
          },
          "date_in_force": {
            "$ref": "#/components/schemas/Document/$defs/partialDate"
          },
          "period_start": {
            "type": "integer",
            "minimum": 1980,
            "maximum": 2100
          },
          "period_end": {
            "type": "integer",
            "minimum": 1980,
            "maximum": 2100
          },
          "status": {
            "enum": [
              "in_vigore",
              "superato",
              "abrogato",
              "in_consultazione",
              "scaduto",
              "adottato"
            ]
          },
          "languages": {
            "type": "array",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[a-z]{2}$"
            }
          },
          "official_translations": {
            "description": "Lingue (ISO 639-1) per cui esiste una traduzione ufficiale. Le altre lingue di 'languages' non originali sono non ufficiali.",
            "type": "array",
            "uniqueItems": true,
            "items": {
              "type": "string",
              "pattern": "^[a-z]{2}$"
            }
          },
          "summary": {
            "$ref": "#/components/schemas/Document/$defs/localized"
          },
          "topics": {
            "type": "array",
            "minItems": 1,
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/Document/$defs/slug"
            }
          },
          "strategic_objectives": {
            "type": "array",
            "uniqueItems": true,
            "items": {
              "$ref": "#/components/schemas/Document/$defs/slug"
            }
          },
          "source_url": {
            "type": "string",
            "format": "uri",
            "pattern": "^https?://"
          },
          "file_url": {
            "type": "string",
            "format": "uri",
            "pattern": "^https?://"
          },
          "archived_copy": {
            "description": "Percorso del file ospitato sotto /files/. Ammesso solo con licenza compatibile (vedi validate.mjs).",
            "type": "string",
            "pattern": "^/files/[A-Za-z0-9._/-]+$"
          },
          "archive_snapshot_url": {
            "type": "string",
            "format": "uri",
            "pattern": "^https?://"
          },
          "file_hash_sha256": {
            "type": "string",
            "pattern": "^[a-f0-9]{64}$"
          },
          "license": {
            "enum": [
              "pubblico_dominio",
              "cc_by_4_0",
              "eu_reuse",
              "ogl_v3",
              "crown_copyright",
              "termini_specifici",
              "sconosciuto"
            ]
          },
          "license_notes": {
            "type": "string"
          },
          "full_text": {
            "type": "string"
          },
          "supersedes": {
            "$ref": "#/components/schemas/Document/$defs/slug"
          },
          "related_documents": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "slug",
                "relation"
              ],
              "properties": {
                "slug": {
                  "$ref": "#/components/schemas/Document/$defs/slug"
                },
                "relation": {
                  "enum": [
                    "attua",
                    "recepisce",
                    "modifica",
                    "abroga",
                    "cita"
                  ]
                }
              }
            }
          },
          "notes": {
            "type": "string"
          },
          "ingested_from": {
            "type": "string",
            "minLength": 1
          },
          "verified_at": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "verified_by": {
            "type": "string",
            "minLength": 1
          },
          "editorial_status": {
            "enum": [
              "bozza",
              "in_revisione",
              "pubblicato",
              "archiviato"
            ]
          },
          "created_at": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "updated_at": {
            "type": "string",
            "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Pagina del documento sul sito"
          },
          "superseded_by": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Slug dei documenti che lo sostituiscono"
          }
        }
      },
      "Jurisdiction": {
        "title": "Jurisdiction",
        "description": "Paese, territorio o organizzazione emittente. Un file YAML per giurisdizione in data/jurisdictions/<code minuscolo>.yaml.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "code",
          "name_it",
          "name_en",
          "name_fr",
          "name_es",
          "type",
          "regions"
        ],
        "properties": {
          "code": {
            "type": "string",
            "pattern": "^[A-Z]{2}$|^[A-Z][A-Za-z]{1,9}$"
          },
          "iso_numeric": {
            "description": "ISO 3166-1 numerico, usato dalla mappa.",
            "type": "string",
            "pattern": "^\\d{3}$"
          },
          "name_it": {
            "type": "string"
          },
          "name_en": {
            "type": "string"
          },
          "name_fr": {
            "type": "string"
          },
          "name_es": {
            "type": "string"
          },
          "name_local": {
            "type": "string"
          },
          "type": {
            "enum": [
              "paese",
              "territorio",
              "organizzazione_regionale",
              "organizzazione_internazionale"
            ]
          },
          "regions": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "continent"
            ],
            "properties": {
              "continent": {
                "enum": [
                  "europe",
                  "americas",
                  "asia",
                  "africa",
                  "oceania",
                  "global"
                ]
              },
              "m49": {
                "type": "string"
              },
              "memberships": {
                "type": "array",
                "uniqueItems": true,
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "national_cyber_agency": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "name"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri",
                "pattern": "^https?://"
              }
            }
          },
          "notes": {
            "type": "string"
          }
        }
      }
    }
  }
}