{
    "openapi": "3.1.0",
    "info": {
        "title": "InvestMoz reference catalogues",
        "version": "1.0.0",
        "description": "Read-only, rate-limited reference options with stable codes, version metadata and pt-MZ labels. Jurisdictions use the packaged territorial reference set. Economic activities are portal-curated sector groupings, not an official statutory classification. Authority entries are withheld until an authoritative source is approved."
    },
    "servers": [{ "url": "/api/v1/catalogs" }],
    "security": [],
    "paths": {
        "/authorities": { "$ref": "#/components/pathItems/Authorities" },
        "/jurisdictions": { "$ref": "#/components/pathItems/Jurisdictions" },
        "/economic-activities": {
            "$ref": "#/components/pathItems/EconomicActivities"
        }
    },
    "components": {
        "pathItems": {
            "Authorities": {
                "get": {
                    "summary": "Search the published authorities catalogue",
                    "parameters": [
                        { "$ref": "#/components/parameters/q" },
                        { "$ref": "#/components/parameters/version" },
                        { "$ref": "#/components/parameters/page" },
                        { "$ref": "#/components/parameters/per_page" },
                        {
                            "name": "jurisdiction_id",
                            "in": "query",
                            "schema": { "type": "string", "format": "uuid" }
                        }
                    ],
                    "responses": {
                        "200": { "$ref": "#/components/responses/CatalogPage" },
                        "429": { "description": "Rate limit exceeded" }
                    }
                }
            },
            "Jurisdictions": {
                "get": {
                    "summary": "List territorial reference options for dependent dropdowns",
                    "parameters": [
                        { "$ref": "#/components/parameters/q" },
                        { "$ref": "#/components/parameters/version" },
                        { "$ref": "#/components/parameters/page" },
                        { "$ref": "#/components/parameters/per_page" },
                        {
                            "name": "type",
                            "in": "query",
                            "required": true,
                            "schema": {
                                "type": "string",
                                "enum": [
                                    "country",
                                    "province",
                                    "district",
                                    "admin_post",
                                    "locality"
                                ]
                            }
                        },
                        {
                            "name": "parent_id",
                            "in": "query",
                            "schema": { "type": "string", "format": "uuid" },
                            "description": "Required for district, admin_post and locality; the parent must be of the immediately preceding level."
                        }
                    ],
                    "responses": {
                        "200": { "$ref": "#/components/responses/CatalogPage" },
                        "422": {
                            "description": "Invalid or missing parent selection"
                        },
                        "429": { "description": "Rate limit exceeded" }
                    }
                }
            },
            "EconomicActivities": {
                "get": {
                    "summary": "Search the portal-curated economic activity groupings",
                    "parameters": [
                        { "$ref": "#/components/parameters/q" },
                        { "$ref": "#/components/parameters/version" },
                        { "$ref": "#/components/parameters/page" },
                        { "$ref": "#/components/parameters/per_page" },
                        {
                            "name": "parent_id",
                            "in": "query",
                            "schema": { "type": "string", "format": "uuid" },
                            "description": "Optional parent activity for hierarchical catalog browsing."
                        },
                        {
                            "name": "sector_id",
                            "in": "query",
                            "schema": { "type": "integer", "minimum": 1 },
                            "description": "Optional sector filter for the dependent activity dropdown."
                        }
                    ],
                    "responses": {
                        "200": { "$ref": "#/components/responses/CatalogPage" },
                        "429": { "description": "Rate limit exceeded" }
                    }
                }
            }
        },
        "parameters": {
            "q": {
                "name": "q",
                "in": "query",
                "schema": { "type": "string", "maxLength": 100 }
            },
            "version": {
                "name": "version",
                "in": "query",
                "schema": { "type": "integer", "minimum": 1 },
                "description": "A published immutable version; omitted selects the current effective version."
            },
            "page": {
                "name": "page",
                "in": "query",
                "schema": { "type": "integer", "minimum": 1 }
            },
            "per_page": {
                "name": "per_page",
                "in": "query",
                "schema": { "type": "integer", "minimum": 1, "maximum": 100 }
            }
        },
        "responses": {
            "CatalogPage": {
                "description": "Stable option values with Portuguese (Mozambique) labels. A not-yet-published catalogue returns an empty page and status not_published.",
                "headers": {
                    "Cache-Control": { "schema": { "type": "string" } },
                    "ETag": { "schema": { "type": "string" } }
                },
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "required": [
                                "data",
                                "links",
                                "meta",
                                "next_page_url",
                                "prev_page_url",
                                "current_page",
                                "per_page",
                                "total",
                                "last_page"
                            ],
                            "properties": {
                                "data": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/components/schemas/CatalogEntry"
                                    }
                                },
                                "links": {
                                    "type": "object",
                                    "properties": {
                                        "next": { "type": ["string", "null"] },
                                        "previous": {
                                            "type": ["string", "null"]
                                        }
                                    }
                                },
                                "next_page_url": { "type": ["string", "null"] },
                                "prev_page_url": { "type": ["string", "null"] },
                                "current_page": { "type": "integer" },
                                "per_page": { "type": "integer" },
                                "total": { "type": "integer" },
                                "last_page": { "type": "integer" },
                                "meta": {
                                    "$ref": "#/components/schemas/CatalogMetadata"
                                }
                            }
                        }
                    }
                }
            }
        },
        "schemas": {
            "CatalogEntry": {
                "type": "object",
                "required": ["id", "value", "code", "name", "label", "locale"],
                "properties": {
                    "id": { "type": "string", "format": "uuid" },
                    "value": {
                        "type": "string",
                        "description": "Stable API value; never the translated label."
                    },
                    "code": { "type": "string" },
                    "name": { "type": "string" },
                    "label": {
                        "type": "string",
                        "description": "Presentation label in pt-MZ."
                    },
                    "locale": { "const": "pt-MZ" },
                    "parent_id": {
                        "type": ["string", "null"],
                        "format": "uuid"
                    },
                    "type": { "type": "string" },
                    "version_no": { "type": "integer", "minimum": 1 },
                    "sector_id": { "type": "integer" },
                    "source_code": { "type": ["string", "null"] },
                    "authority_type": { "type": "string" },
                    "organization_id": { "type": "string", "format": "uuid" },
                    "jurisdiction_id": {
                        "type": ["string", "null"],
                        "format": "uuid"
                    },
                    "jurisdiction_name": { "type": ["string", "null"] }
                }
            },
            "CatalogMetadata": {
                "type": "object",
                "required": [
                    "catalog",
                    "version",
                    "locale",
                    "current_page",
                    "per_page",
                    "total",
                    "last_page"
                ],
                "properties": {
                    "catalog": {
                        "type": "string",
                        "enum": [
                            "authorities",
                            "jurisdictions",
                            "economic-activities"
                        ]
                    },
                    "version": { "type": ["integer", "null"] },
                    "locale": { "const": "pt-MZ" },
                    "status": { "type": "string", "enum": ["not_published"] },
                    "source_version": { "type": ["string", "null"] },
                    "valid_from": {
                        "type": ["string", "null"],
                        "format": "date"
                    },
                    "valid_to": {
                        "type": ["string", "null"],
                        "format": "date"
                    },
                    "current_page": { "type": "integer" },
                    "per_page": { "type": "integer" },
                    "total": { "type": "integer" },
                    "last_page": { "type": "integer" }
                }
            }
        }
    }
}