{
  "openapi": "3.1.1",
  "info": {
    "title": "Apple Localization Terms Glossary API",
    "version": "1.0.0",
    "description": "Unofficial, read-only examples of Apple localization. GET URL compatibility is preserved. Pin a platform/major and retain returned version/build/provenance. Key is a resource identifier, not necessarily English. Results are evidence, not translation rules. Do not submit confidential text without permission. llms.txt and MCP instructions: /docs/agent-access.md. Legacy /api/{platform}/catalog and /search[/advanced] aliases choose the latest dataset; prefer explicit major routes below."
  },
  "servers": [
    {
      "url": "/",
      "description": "This deployment (also works with local Compose)."
    }
  ],
  "security": [],
  "paths": {
    "/api/datasets": {
      "get": {
        "operationId": "listDatasets",
        "summary": "Discover available OS releases and components",
        "responses": {
          "200": {
            "description": "Available datasets; not hardcoded by clients.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Datasets"
                }
              }
            }
          }
        }
      }
    },
    "/api/{platform}/{major}/catalog": {
      "get": {
        "operationId": "getCatalog",
        "summary": "Discover stored locales, language groups and full bundle paths",
        "description": "Does not scan occurrences per request. An optional component scopes languages, bundles and total; the components list still describes the entire dataset.",
        "parameters": [
          {
            "name": "platform",
            "in": "path",
            "required": true,
            "schema": {
              "enum": [
                "ios",
                "macos"
              ],
              "type": "string"
            }
          },
          {
            "name": "major",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "component",
            "in": "query",
            "description": "Optional component of this dataset, discovered from its catalog.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Catalog for exactly one platform/major.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            }
          },
          "400": {
            "description": "Invalid conditions, component, query or pagination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset or route.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Only GET is supported (empty response body)."
          },
          "500": {
            "description": "Search failed. Do not interpret as no matches.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Search unavailable, including database statement timeout. Narrow the query before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/{platform}/{major}/search": {
      "get": {
        "operationId": "searchTranslations",
        "summary": "Full-text search of localization values with context expansion",
        "description": "Searches text and serialized structured JSON, then returns selected-language rows sharing the same resource table and exact key. Not every returned row matches q. Not relevance-ranked. Does not search resource keys. Matching and output language filters are the same; include both source and target languages if needed. Components remain distinct. Omit q only when a bundle filter is supplied.",
        "parameters": [
          {
            "name": "platform",
            "in": "path",
            "required": true,
            "schema": {
              "enum": [
                "ios",
                "macos"
              ],
              "type": "string"
            }
          },
          {
            "name": "major",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "component",
            "in": "query",
            "description": "Optional component of this dataset, discovered from its catalog.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Input is not trimmed. Normal search needs nonempty q, b or bundle_path; advanced search needs nonempty q.",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 4096,
              "description": "Server limit is 4096 UTF-16 code units."
            }
          },
          {
            "name": "l",
            "in": "query",
            "description": "Repeat for language display groups or stored codes. Union with locale; omit both for all languages. Do not send the UI-only empty l marker.",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "locale",
            "in": "query",
            "description": "Repeat for exact stored codes (no group expansion). Unknown selections match nothing. Preserve spelling from catalog.",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "bundle_path",
            "in": "query",
            "description": "Exact effective bundle path from catalog; valid in both search modes.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "One-based page. Pages can split resource contexts.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "size",
            "in": "query",
            "description": "Rows per page, not contexts. Values above 200 are clamped to 200. Prefer 20; does not bound COUNT work.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 200
            }
          },
          {
            "name": "b",
            "in": "query",
            "description": "Bundle basename. May match multiple full paths.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of rows; total counts expanded rows, not translations or keys.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Search"
                }
              }
            }
          },
          "400": {
            "description": "Invalid conditions, component, query or pagination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset or route.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Only GET is supported (empty response body)."
          },
          "500": {
            "description": "Search failed. Do not interpret as no matches.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Search unavailable, including database statement timeout. Narrow the query before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/{platform}/{major}/search/advanced": {
      "get": {
        "operationId": "compareTranslations",
        "summary": "Compare a key, text localization, raw locale, file or bundle name",
        "description": "Only matching rows, without normal search's context expansion. Localization compares text-kind values only. File and Bundle compare basenames; Language compares stored codes. startsWith is a literal prefix, not a user wildcard. Legacy b is ignored: use bundle_path. A key match does not imply an English source value.",
        "parameters": [
          {
            "name": "platform",
            "in": "path",
            "required": true,
            "schema": {
              "enum": [
                "ios",
                "macos"
              ],
              "type": "string"
            }
          },
          {
            "name": "major",
            "in": "path",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "component",
            "in": "query",
            "description": "Optional component of this dataset, discovered from its catalog.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Input is not trimmed. Normal search needs nonempty q, b or bundle_path; advanced search needs nonempty q.",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 4096
            }
          },
          {
            "name": "l",
            "in": "query",
            "description": "Repeat for language display groups or stored codes. Union with locale; omit both for all languages. Do not send the UI-only empty l marker.",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "locale",
            "in": "query",
            "description": "Repeat for exact stored codes (no group expansion). Unknown selections match nothing. Preserve spelling from catalog.",
            "required": false,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "style": "form",
            "explode": true
          },
          {
            "name": "bundle_path",
            "in": "query",
            "description": "Exact effective bundle path from catalog; valid in both search modes.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "page",
            "in": "query",
            "description": "One-based page. Pages can split resource contexts.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "size",
            "in": "query",
            "description": "Rows per page, not contexts. Values above 200 are clamped to 200. Prefer 20; does not bound COUNT work.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 200
            }
          },
          {
            "name": "c",
            "in": "query",
            "description": "Comparison field.",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "key",
                "localization",
                "language",
                "file",
                "bundle"
              ]
            }
          },
          {
            "name": "o",
            "in": "query",
            "description": "Comparison operation.",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "equal",
                "notEqual",
                "startsWith"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of matching rows.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Search"
                }
              }
            }
          },
          "400": {
            "description": "Invalid conditions, component, query or pagination.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown dataset or route.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "405": {
            "description": "Only GET is supported (empty response body)."
          },
          "500": {
            "description": "Search failed. Do not interpret as no matches.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Search unavailable, including database statement timeout. Narrow the query before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "Component": {
        "type": "object",
        "properties": {
          "key": {
            "type": "string"
          },
          "schema": {
            "type": "string"
          },
          "packageManifest": {
            "type": "string"
          }
        },
        "required": [
          "key"
        ]
      },
      "Dataset": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "platform": {
            "type": "string",
            "enum": [
              "iOS",
              "macOS"
            ]
          },
          "version": {
            "type": "string"
          },
          "build": {
            "type": "string"
          },
          "components": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Component"
            }
          }
        },
        "required": [
          "id",
          "platform",
          "version",
          "build",
          "components"
        ]
      },
      "Datasets": {
        "type": "object",
        "properties": {
          "validationOnly": {
            "type": "boolean"
          },
          "datasets": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Dataset"
            }
          }
        },
        "required": [
          "datasets"
        ]
      },
      "Catalog": {
        "type": "object",
        "properties": {
          "validationOnly": {
            "type": "boolean"
          },
          "target": {
            "$ref": "#/components/schemas/Dataset"
          },
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "languages": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "languageGroups": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "bundles": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "components": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "rows": {
                  "type": "integer",
                  "minimum": 0
                },
                "sourceId": {
                  "type": "string"
                }
              },
              "required": [
                "key",
                "rows",
                "sourceId"
              ]
            }
          }
        },
        "required": [
          "target",
          "total",
          "languages",
          "languageGroups",
          "bundles",
          "components"
        ]
      },
      "Provenance": {
        "type": "object",
        "properties": {
          "source_id": {
            "type": "string"
          },
          "table_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "resource_id": {
            "type": "string"
          },
          "resource_status": {
            "type": "string"
          },
          "image_path": {
            "type": "string"
          },
          "resource_path": {
            "type": [
              "string",
              "null"
            ]
          },
          "bundle_path": {
            "type": [
              "string",
              "null"
            ]
          },
          "bundle_assignment": {
            "type": [
              "string",
              "null"
            ]
          },
          "sha256": {
            "type": "string"
          },
          "language": {
            "type": "object",
            "properties": {
              "raw": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "basis": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "status": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "bundle_evidence": {},
          "original": {},
          "ownership_correction": {},
          "language_evidence": {}
        },
        "required": [
          "source_id",
          "table_id",
          "resource_id",
          "image_path",
          "language"
        ]
      },
      "Row": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 0,
            "description": "Component-local identifier, not a global ID."
          },
          "dataset": {
            "type": "string"
          },
          "component": {
            "type": "string"
          },
          "group_id": {
            "type": "string",
            "description": "Table/key grouping inside a component. Also retain dataset, build and component."
          },
          "source": {
            "type": "string",
            "description": "Resource key; not necessarily the source-language value."
          },
          "target": {
            "type": "string",
            "description": "Display string; structured values are serialized JSON."
          },
          "target_kind": {
            "type": "string",
            "enum": [
              "text",
              "structured"
            ]
          },
          "target_value": {
            "description": "Unaltered JSON value. Text remains a string; plural/structured values must not be flattened."
          },
          "language": {
            "type": "string"
          },
          "file_name": {
            "type": "string"
          },
          "bundle_name": {
            "type": "string"
          },
          "provenance": {
            "$ref": "#/components/schemas/Provenance"
          }
        },
        "required": [
          "id",
          "dataset",
          "component",
          "source",
          "target",
          "target_kind",
          "target_value",
          "language",
          "provenance"
        ]
      },
      "Search": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Row"
            }
          },
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "last_page": {
            "type": "integer",
            "minimum": 0
          },
          "meta": {
            "type": "object",
            "properties": {
              "validationOnly": {
                "type": "boolean"
              },
              "dataset": {
                "type": "string"
              },
              "version": {
                "type": "string"
              },
              "build": {
                "type": "string"
              },
              "components": {
                "type": "object",
                "additionalProperties": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "sourceField": {
                "type": "string"
              },
              "grouping": {
                "type": "string"
              }
            },
            "required": [
              "dataset",
              "version",
              "build"
            ]
          }
        },
        "required": [
          "data",
          "total",
          "last_page",
          "meta"
        ]
      }
    }
  }
}