{
  "openapi": "3.1.0",
  "info": {
    "title": "Tidbit API",
    "version": "1.0.0",
    "description": "Read-only JSON for the Tidbit tech dictionary: static files, no auth, CORS open. The version is in the path (/v1/). Fields are only added within a version; a breaking change ships as /v2/ and /v1/ keeps working for at least 12 months after it, announced with Deprecation and Sunset headers and in https://tidbit.legios.com.ar/developers/. Errors are RFC 9457 problem+json. Fair use: 300 requests per 60 seconds per client, announced in RateLimit headers.",
    "license": {
      "name": "MIT",
      "url": "https://github.com/legiosai/tidbit/blob/main/LICENSE"
    },
    "contact": {
      "name": "Legios",
      "url": "https://github.com/legiosai/tidbit/issues"
    }
  },
  "externalDocs": {
    "description": "Developer guide",
    "url": "https://tidbit.legios.com.ar/developers/"
  },
  "servers": [
    {
      "url": "https://tidbit.legios.com.ar"
    }
  ],
  "paths": {
    "/v1/terms.json": {
      "get": {
        "operationId": "listTerms",
        "summary": "List every term",
        "description": "Every term with its one-line definition, aliases, level, topics and URLs, in English and Spanish.",
        "responses": {
          "200": {
            "description": "The term list",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TermList"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests; wait Retry-After seconds",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/v1/terms/{slug}.json": {
      "get": {
        "operationId": "getTerm",
        "summary": "Get one term",
        "description": "The full entry for one term: explanation, analogy, key points and links in both languages.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "The term's slug, as in its URL",
            "schema": {
              "type": "string",
              "pattern": "^[a-z0-9-]+$",
              "example": "data-lake"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The entry",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Entry"
                }
              }
            }
          },
          "404": {
            "description": "No term with that slug",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests; wait Retry-After seconds",
            "headers": {
              "RateLimit": {
                "$ref": "#/components/headers/RateLimit"
              },
              "RateLimit-Policy": {
                "$ref": "#/components/headers/RateLimitPolicy"
              }
            },
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "headers": {
      "RateLimit": {
        "description": "Remaining quota in the current window (draft-ietf-httpapi-ratelimit-headers)",
        "schema": {
          "type": "string",
          "example": "\"fair\";r=299;t=60"
        }
      },
      "RateLimitPolicy": {
        "description": "The quota policy",
        "schema": {
          "type": "string",
          "example": "\"fair\";q=300;w=60"
        }
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details",
        "required": [
          "type",
          "title",
          "status",
          "code"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "enum": [
              "not_found",
              "rate_limited",
              "method_not_allowed"
            ],
            "description": "Machine-readable error code"
          },
          "resolution": {
            "type": "string",
            "description": "What to do next"
          },
          "documentation_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "LocalizedSummary": {
        "type": "object",
        "required": [
          "title",
          "tagline",
          "aliases",
          "lead",
          "url",
          "markdown"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "tagline": {
            "type": "string"
          },
          "aliases": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "imageAlt": {
            "type": "string"
          },
          "lead": {
            "type": "string",
            "description": "First paragraph of the explanation"
          },
          "analogy": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "markdown": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Term": {
        "type": "object",
        "required": [
          "id",
          "slug",
          "date",
          "level",
          "subjects",
          "en",
          "es"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "level": {
            "type": "integer",
            "enum": [
              1,
              2,
              3
            ],
            "description": "1 basic, 2 intermediate, 3 advanced"
          },
          "subjects": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "ai",
                "aws",
                "cloud",
                "hardware",
                "software",
                "data",
                "security",
                "networks",
                "companies"
              ]
            }
          },
          "image": {
            "type": "string",
            "format": "uri"
          },
          "en": {
            "$ref": "#/components/schemas/LocalizedSummary"
          },
          "es": {
            "$ref": "#/components/schemas/LocalizedSummary"
          }
        }
      },
      "TermList": {
        "type": "object",
        "required": [
          "count",
          "terms"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "generated": {
            "type": "string",
            "format": "date"
          },
          "subjects": {
            "type": "object",
            "additionalProperties": {
              "type": "object",
              "properties": {
                "en": {
                  "type": "string"
                },
                "es": {
                  "type": "string"
                }
              }
            }
          },
          "terms": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Term"
            }
          }
        }
      },
      "Entry": {
        "type": "object",
        "required": [
          "id",
          "slug",
          "date",
          "level",
          "subjects",
          "aliases",
          "en",
          "es",
          "urls"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "date": {
            "type": "string",
            "format": "date"
          },
          "level": {
            "type": "integer",
            "enum": [
              1,
              2,
              3
            ]
          },
          "subjects": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "ai",
                "aws",
                "cloud",
                "hardware",
                "software",
                "data",
                "security",
                "networks",
                "companies"
              ]
            }
          },
          "image": {
            "type": "string"
          },
          "aliases": {
            "type": "object",
            "properties": {
              "en": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "es": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "en": {
            "type": "object",
            "required": [
              "title",
              "tagline",
              "explanation",
              "analogy",
              "keyPoints",
              "links"
            ],
            "properties": {
              "title": {
                "type": "string"
              },
              "tagline": {
                "type": "string",
                "description": "One-line definition"
              },
              "explanation": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "minItems": 2,
                "maxItems": 4,
                "description": "Paragraphs with **bold** and `code` inline markup"
              },
              "analogy": {
                "type": "string"
              },
              "keyPoints": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "minItems": 3,
                "maxItems": 4
              },
              "links": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "label",
                    "url"
                  ],
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "es": {
            "type": "object",
            "required": [
              "title",
              "tagline",
              "explanation",
              "analogy",
              "keyPoints",
              "links"
            ],
            "properties": {
              "title": {
                "type": "string"
              },
              "tagline": {
                "type": "string",
                "description": "One-line definition"
              },
              "explanation": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "minItems": 2,
                "maxItems": 4,
                "description": "Paragraphs with **bold** and `code` inline markup"
              },
              "analogy": {
                "type": "string"
              },
              "keyPoints": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "minItems": 3,
                "maxItems": 4
              },
              "links": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "label",
                    "url"
                  ],
                  "properties": {
                    "label": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "urls": {
            "type": "object",
            "properties": {
              "en": {
                "type": "string",
                "format": "uri"
              },
              "es": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}