{
  "openapi": "3.2.1",
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "info": {
    "title": "BOP Data API",
    "version": "1.0.0",
    "summary": "Canonical structured datasets from data.bop.ink",
    "description": "BOP Data maintains normalized datasets based on sources identified per dataset. One Canonical ID identifies the same logical dataset across its HTML, JSON, CSV, Markdown, Embed and supported agent access representations.",
    "license": {
      "name": "Dataset-specific licensing",
      "identifier": "LicenseRef-BOP-Dataset-Specific"
    }
  },
  "servers": [
    {
      "url": "https://data.bop.ink",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Catalog",
      "summary": "Dataset discovery"
    },
    {
      "name": "Dataset",
      "summary": "Canonical dataset access"
    }
  ],
  "paths": {
    "/api/v1/datasets.json": {
      "get": {
        "operationId": "listDatasets",
        "summary": "List datasets",
        "tags": [
          "Catalog"
        ],
        "responses": {
          "200": {
            "description": "Machine-readable BOP Data catalog",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CatalogResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/datasets/{canonicalId}.json": {
      "get": {
        "operationId": "getDataset",
        "summary": "Get one canonical dataset",
        "tags": [
          "Dataset"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/CanonicalId"
          }
        ],
        "responses": {
          "200": {
            "description": "Canonical public dataset envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicDataset"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/api/v1/datasets/{canonicalId}.csv": {
      "get": {
        "operationId": "getDatasetCsv",
        "summary": "Download current dataset records as CSV",
        "tags": [
          "Dataset"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/CanonicalId"
          }
        ],
        "responses": {
          "200": {
            "description": "UTF-8 CSV containing the current records table",
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string",
                  "contentMediaType": "text/csv"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/export/{canonicalId}.pdf": {
      "get": {
        "operationId": "getDatasetPdf",
        "summary": "Export one dataset as PDF",
        "tags": [
          "Dataset"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/CanonicalId"
          }
        ],
        "responses": {
          "200": {
            "description": "Printable PDF generated from the canonical dataset",
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "contentMediaType": "application/pdf"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    },
    "/export/{canonicalId}.png": {
      "get": {
        "operationId": "getDatasetPng",
        "summary": "Export one dataset as PNG",
        "tags": [
          "Dataset"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/CanonicalId"
          }
        ],
        "responses": {
          "200": {
            "description": "Shareable PNG generated from the canonical dataset",
            "content": {
              "image/png": {
                "schema": {
                  "type": "string",
                  "contentMediaType": "image/png"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "CanonicalId": {
        "name": "canonicalId",
        "in": "path",
        "required": true,
        "description": "Immutable BOP Data Canonical ID.",
        "schema": {
          "type": "string",
          "minLength": 3,
          "pattern": "^[A-Za-z0-9._-]+$"
        }
      }
    },
    "responses": {
      "NotFound": {
        "description": "Dataset not found",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error"
              ],
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "LocalizedText": {
        "type": "object",
        "required": [
          "vi",
          "en"
        ],
        "properties": {
          "vi": {
            "type": "string"
          },
          "en": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "Highlight": {
        "type": "object",
        "required": [
          "label",
          "value",
          "unit"
        ],
        "properties": {
          "label": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "value": {
            "oneOf": [
              {
                "type": "number"
              },
              {
                "type": "string"
              }
            ]
          },
          "unit": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "context": {
            "$ref": "#/components/schemas/LocalizedText"
          }
        },
        "additionalProperties": false
      },
      "Column": {
        "type": "object",
        "required": [
          "key",
          "label",
          "type"
        ],
        "properties": {
          "key": {
            "type": "string"
          },
          "label": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "type": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "semanticRole": {
            "type": "string"
          },
          "displayPriority": {
            "type": "integer"
          }
        },
        "additionalProperties": true
      },
      "Source": {
        "type": "object",
        "required": [
          "id",
          "title",
          "publisher",
          "url",
          "retrievedDate",
          "redistributionAllowed"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "publisher": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "sourceLanguage": {
            "type": "string"
          },
          "sourceDate": {
            "type": [
              "string",
              "null"
            ]
          },
          "retrievedDate": {
            "type": "string"
          },
          "sourceVersion": {
            "type": [
              "string",
              "null"
            ]
          },
          "license": {
            "type": [
              "string",
              "null"
            ]
          },
          "redistributionAllowed": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      },
      "AccessLinks": {
        "type": "object",
        "required": [
          "html",
          "markdown",
          "json",
          "csv",
          "embed"
        ],
        "properties": {
          "html": {
            "type": "string",
            "format": "uri"
          },
          "markdown": {
            "type": "string",
            "format": "uri"
          },
          "json": {
            "type": "string",
            "format": "uri"
          },
          "csv": {
            "type": "string",
            "format": "uri"
          },
          "embed": {
            "type": "string",
            "format": "uri"
          },
          "pdf": {
            "type": "string",
            "format": "uri"
          },
          "png": {
            "type": "string",
            "format": "uri"
          }
        },
        "additionalProperties": true
      },
      "PublicDataset": {
        "type": "object",
        "required": [
          "spec",
          "canonicalId",
          "identity",
          "data",
          "freshness",
          "provenance",
          "links"
        ],
        "properties": {
          "spec": {
            "type": "string",
            "const": "bop.dataset/1"
          },
          "canonicalId": {
            "type": "string"
          },
          "identity": {
            "type": "object",
            "required": [
              "category",
              "subcategory",
              "slug",
              "title",
              "summary",
              "scope",
              "geography",
              "schemaId",
              "schemaVersion"
            ],
            "properties": {
              "category": {
                "type": "string"
              },
              "subcategory": {
                "type": "string"
              },
              "slug": {
                "type": "string"
              },
              "title": {
                "$ref": "#/components/schemas/LocalizedText"
              },
              "summary": {
                "$ref": "#/components/schemas/LocalizedText"
              },
              "scope": {
                "$ref": "#/components/schemas/LocalizedText"
              },
              "geography": {
                "type": "string"
              },
              "geographyLabel": {
                "$ref": "#/components/schemas/LocalizedText"
              },
              "jurisdiction": {
                "$ref": "#/components/schemas/LocalizedText"
              },
              "schemaId": {
                "type": "string"
              },
              "schemaVersion": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "data": {
            "type": "object",
            "required": [
              "renderer",
              "highlights",
              "columns",
              "records",
              "extensions"
            ],
            "properties": {
              "renderer": {
                "type": "string"
              },
              "highlights": {
                "type": "array",
                "maxItems": 3,
                "items": {
                  "$ref": "#/components/schemas/Highlight"
                }
              },
              "columns": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Column"
                }
              },
              "records": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              },
              "extensions": {
                "type": "object",
                "additionalProperties": true
              }
            },
            "additionalProperties": false
          },
          "freshness": {
            "type": "object",
            "required": [
              "currentVersion",
              "status",
              "lastUpdated"
            ],
            "properties": {
              "currentVersion": {
                "type": "string"
              },
              "status": {
                "type": "string"
              },
              "effectiveDate": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "publishedDate": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "lastVerified": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "lastUpdated": {
                "type": "string"
              },
              "refreshCadence": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "refreshPolicy": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/LocalizedText"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "additionalProperties": false
          },
          "provenance": {
            "type": "object",
            "required": [
              "license",
              "sources"
            ],
            "properties": {
              "license": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "sources": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Source"
                }
              }
            },
            "additionalProperties": false
          },
          "links": {
            "$ref": "#/components/schemas/AccessLinks"
          }
        },
        "additionalProperties": false
      },
      "CatalogItem": {
        "type": "object",
        "required": [
          "canonicalId",
          "title",
          "schemaId",
          "schemaVersion",
          "currentVersion",
          "lastUpdated",
          "links"
        ],
        "properties": {
          "canonicalId": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "subcategory": {
            "type": "string"
          },
          "title": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "summary": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "schemaId": {
            "type": "string"
          },
          "schemaVersion": {
            "type": "string"
          },
          "currentVersion": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "lastUpdated": {
            "type": "string"
          },
          "refreshCadence": {
            "type": [
              "string",
              "null"
            ]
          },
          "sourcePublisher": {
            "type": [
              "string",
              "null"
            ]
          },
          "links": {
            "$ref": "#/components/schemas/AccessLinks"
          }
        },
        "additionalProperties": false
      },
      "CatalogResponse": {
        "type": "object",
        "required": [
          "spec",
          "total",
          "datasets"
        ],
        "properties": {
          "spec": {
            "type": "string",
            "const": "bop.catalog/1"
          },
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "datasets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CatalogItem"
            }
          }
        },
        "additionalProperties": false
      }
    }
  }
}