Ranking dos grupos CSAP

Added value: +"Concentração da métrica nos primeiros grupos do ranking (soma de `pct_of_total`, duas casas)"

Previous value: -"Bloco de proveniência (contrato v1.1): fonte, URL, competência, extração, diagnóstico de origem, citação e licença"New value: +"Bloco de proveniência do portfólio: fonte, URL, competência, extração, diagnóstico de origem, citação e licença; e, só quando há o que dizer, avisos, o que o servidor calculou e se o número ainda pode mudar"

Added value: +{
+  "description": "Como o número foi calculado; presente junto com derived",
+  "type": "string"
+}

Added value: +{
+  "description": "Presente (true) quando o número foi calculado por este servidor — os cubos SIH são somas das internações dos arquivos do DATASUS",
+  "type": "boolean"
+}

Added value: +{
+  "description": "Avisos que acompanham o dado (ex.: cubo atrás do espelho healthbr-data, frescor não verificado). Ausente quando não há aviso",
+  "items": {
+    "type": "string"
+  },
+  "minItems": 1,
+  "type": "array"
+}

Previous value: -"Diagnóstico de origem desta chamada (contrato v1.1): idas ao canal sih/cubos/ do healthbr-data (manifesto e arquivos que faltavam no disco), tentativas somadas e anomalias contornadas; unstable=true quando houve anomalia. null = a resposta veio do DISCO (cache aquecido) ou o bloco não é do canal (listas de referência)"New value: +"Diagnóstico de origem desta chamada: idas ao canal sih/cubos/ do healthbr-data (manifesto e arquivos que faltavam no disco), tentativas somadas e anomalias contornadas; unstable=true quando houve anomalia. null = a resposta veio do DISCO (cache aquecido) ou o bloco não é do canal (listas de referência)"

Added value: +{
+  "additionalProperties": false,
+  "description": "Se o número ainda pode mudar: provisional quando algum ano da resposta ainda tem competências abertas no SIH (o total ainda pode crescer); current nos demais — o DATASUS reedita arquivos de competências passadas",
+  "properties": {
+    "note": {
+      "description": "O específico da fonte: o que revisa, quando, por quê",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "status": {
+      "description": "current = versão vigente, a fonte pode revisá-la; provisional = preliminar, incompleta ou sujeita a mudança (não compare como se fosse fechada); final = não muda mais, declarado pela fonte",
+      "enum": [
+        "current",
+        "provisional",
+        "final"
+      ],
+      "type": "string"
+    }
+  },
+  "required": [
+    "status",
+    "note"
+  ],
+  "type": "object"
+}

Added value: +{
+  "description": "Presente só quando a resposta junta partes de origens ou momentos distintos: para cada grupo de campos, a URL, a extração e se veio do cache. Ausente nas respostas de uma origem só",
+  "items": {
+    "additionalProperties": false,
+    "description": "Proveniência de um grupo de campos da resposta: de onde veio e quando foi extraído",
+    "properties": {
+      "data_vintage": {
+        "description": "Vintage/competência da sub-fonte",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "dataset_id": {
+        "description": "Identificador do conjunto da sub-fonte",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "fields": {
+        "description": "Campos do payload atribuídos a esta sub-fonte",
+        "items": {
+          "type": "string"
+        },
+        "minItems": 1,
+        "type": "array"
+      },
+      "retrieved_at": {
+        "description": "ISO-8601 da extração desta sub-fonte na origem",
+        "type": [
+          "string",
+          "null"
+        ]
+      },
+      "served_from_cache": {
+        "description": "true se esta sub-fonte veio do cache do servidor (retrieved_at é o da extração original); false se foi buscada nesta chamada; null se o servidor não distingue",
+        "type": [
+          "boolean",
+          "null"
+        ]
+      },
+      "source_url": {
+        "description": "URL canônica da sub-fonte que originou estes campos",
+        "type": "string"
+      }
+    },
+    "required": [
+      "fields",
+      "source_url",
+      "dataset_id",
+      "data_vintage",
+      "retrieved_at"
+    ],
+    "type": "object"
+  },
+  "minItems": 1,
+  "type": "array"
+}

Previous value: -"Instante REAL da extração na origem (ISO-8601) — para os cubos SIH, a safra do sidecar (extração no FTP do DATASUS), nunca o instante do download"New value: +"Instante REAL da extração na origem (ISO-8601) — para os cubos SIH, o download MAIS ANTIGO, do FTP do DATASUS, entre os .dbc que alimentaram a resposta (cópia idêntica ao original naquela data, MD5 registrado no sidecar), nunca o instante da chamada"

Previous value: -"Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença"New value: +"Bloco de proveniência (contrato v1.1): fonte, URL, competência, extração, diagnóstico de origem, citação e licença"

Added value: +{
+  "description": "Diagnóstico de origem desta chamada (contrato v1.1): idas ao canal sih/cubos/ do healthbr-data (manifesto e arquivos que faltavam no disco), tentativas somadas e anomalias contornadas; unstable=true quando houve anomalia. null = a resposta veio do DISCO (cache aquecido) ou o bloco não é do canal (listas de referência)",
+  "oneOf": [
+    {
+      "additionalProperties": false,
+      "description": "Diagnóstico de origem da chamada: como o dado foi obtido. Medição real do servidor; unstable=true pede ao agente que trate o dado como obtido com dificuldade",
+      "properties": {
+        "anomalies": {
+          "description": "Anomalias superadas até o sucesso, somadas por classe, em ordem fixa; [] se nenhuma",
+          "items": {
+            "additionalProperties": false,
+            "properties": {
+              "count": {
+                "description": "Ocorrências desta classe na chamada",
+                "minimum": 1,
+                "type": "integer"
+              },
+              "kind": {
+                "description": "Classe da anomalia (vocabulário fechado do contrato)",
+                "enum": [
+                  "timeout",
+                  "network",
+                  "http_4xx",
+                  "http_5xx",
+                  "rate_limited",
+                  "malformed_body"
+                ],
+                "type": "string"
+              }
+            },
+            "required": [
+              "kind",
+              "count"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        "attempts": {
+          "description": "Tentativas somadas, incluindo as repetidas (>= requests)",
+          "minimum": 1,
+          "type": "integer"
+        },
+        "requests": {
+          "description": "Idas distintas à origem que compõem esta resposta (fatias, páginas)",
+          "minimum": 1,
+          "type": "integer"
+        },
+        "unstable": {
+          "description": "true se houve repetição (attempts > requests) ou alguma anomalia",
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "requests",
+        "attempts",
+        "anomalies",
+        "unstable"
+      ],
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ]
+}

Previous value: -"Instante REAL da extração na origem (ISO-8601)"New value: +"Instante REAL da extração na origem (ISO-8601) — para os cubos SIH, a safra do sidecar (extração no FTP do DATASUS), nunca o instante do download"

Previous value: -[
-  "source",
-  "source_url",
-  "data_vintage",
-  "retrieved_at",
-  "citation",
-  "license"
-]New value: +[
+  "source",
+  "source_url",
+  "data_vintage",
+  "retrieved_at",
+  "retrieval",
+  "citation",
+  "license"
+]

Added value: +{
+  "description": "Anos que o canal de cubos publica — a verdade do canal, distinta do que esta instância tem em disco; só com o cache de cubos ligado",
+  "items": {
+    "type": "number"
+  },
+  "type": "array"
+}

Previous value: -nullNew value: +{
+  "additionalProperties": false,
+  "anyOf": [
+    {
+      "required": [
+        "metric",
+        "ranking",
+        "notes",
+        "concentration",
+        "total_groups"
+      ]
+    },
+    {
+      "required": [
+        "error"
+      ]
+    }
+  ],
+  "description": "Os grupos CSAP ordenados pela métrica, com participação de cada um e concentração nos primeiros; `error` quando nenhum ano pedido tem dado",
+  "properties": {
+    "attribution": {
+      "description": "URLs canônicas das fontes desta resposta (lista de atribuição)",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "available_sih_years": {
+      "description": "Anos com dados SIH atendíveis por este servidor",
+      "items": {
+        "type": "number"
+      },
+      "type": "array"
+    },
+    "concentration": {
+      "additionalProperties": false,
+      "properties": {
+        "top_3_percentage": {
+          "description": "Soma da participação dos 3 primeiros, %",
+          "type": "number"
+        },
+        "top_5_percentage": {
+          "description": "Soma dos 5 primeiros, %",
+          "type": "number"
+        }
+      },
+      "required": [
+        "top_3_percentage",
+        "top_5_percentage"
+      ],
+      "type": "object"
+    },
+    "data": {
+      "description": "Sempre vazio: só aparece no caminho de erro-mole do funil",
+      "items": {},
+      "type": "array"
+    },
+    "error": {
+      "description": "Motivo pelo qual não há dados nesta resposta (ano sem dado, cobertura populacional, falha na consulta)",
+      "type": "string"
+    },
+    "metric": {
+      "description": "Métrica que ordena",
+      "enum": [
+        "n",
+        "days",
+        "value",
+        "deaths"
+      ]
+    },
+    "note": {
+      "description": "Como obter o dado (por exemplo, consultar get_available_years)",
+      "type": "string"
+    },
+    "notes": {
+      "description": "Avisos que qualificam os números: era CID-9, raça/cor ausente, universo do % ICSAP, denominador populacional, truncamento",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "provenance": {
+      "description": "Um bloco por procedência que contribuiu com esta resposta (SIH, lista CSAP, csapAIH, população…); licenças nunca se fundem",
+      "items": {
+        "additionalProperties": false,
+        "description": "Bloco de proveniência (contrato v1.0): fonte, URL, competência, extração e licença",
+        "properties": {
+          "citation": {
+            "description": "Citação pronta para uso",
+            "type": "string"
+          },
+          "data_vintage": {
+            "description": "Competência ou safra do dado segundo a fonte; null quando a fonte não expõe",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "license": {
+            "description": "Regime legal do dado (id SPDX quando há)",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "retrieved_at": {
+            "description": "Instante REAL da extração na origem (ISO-8601)",
+            "type": "string"
+          },
+          "source": {
+            "description": "Fonte oficial do dado",
+            "type": "string"
+          },
+          "source_url": {
+            "description": "URL canônica que reproduz a consulta ou localiza a fonte",
+            "type": "string"
+          }
+        },
+        "required": [
+          "source",
+          "source_url",
+          "data_vintage",
+          "retrieved_at",
+          "citation",
+          "license"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "ranking": {
+      "description": "Ranking em ordem decrescente da métrica",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "csap_group": {
+            "description": "Grupo CSAP g01–g19",
+            "type": "string"
+          },
+          "csap_name": {
+            "description": "Nome do grupo",
+            "type": "string"
+          },
+          "deaths": {
+            "description": "Óbitos",
+            "type": "number"
+          },
+          "metric_value": {
+            "description": "Valor da métrica escolhida",
+            "type": "number"
+          },
+          "n_hospitalizations": {
+            "description": "Internações do grupo",
+            "type": "number"
+          },
+          "pct_of_total": {
+            "description": "Participação do grupo no total da métrica, %",
+            "type": "number"
+          },
+          "rank": {
+            "description": "Posição, 1 = maior",
+            "type": "number"
+          },
+          "total_days": {
+            "description": "Dias de permanência",
+            "type": "number"
+          },
+          "total_value": {
+            "description": "Valor pago (R$)",
+            "type": "number"
+          }
+        },
+        "required": [
+          "rank",
+          "csap_group",
+          "csap_name",
+          "metric_value",
+          "pct_of_total",
+          "n_hospitalizations",
+          "total_days",
+          "total_value",
+          "deaths"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "total_groups": {
+      "description": "Quantos grupos no ranking",
+      "type": "number"
+    },
+    "years_not_available": {
+      "additionalProperties": false,
+      "description": "Presente só quando parte dos anos pedidos não tem dado: os números cobrem apenas os anos atendidos",
+      "properties": {
+        "note": {
+          "description": "Quais anos ficaram fora e quais os números cobrem",
+          "type": "string"
+        },
+        "years": {
+          "description": "Anos pedidos que não têm dados SIH e ficaram fora do resultado",
+          "items": {
+            "type": "number"
+          },
+          "type": "array"
+        }
+      },
+      "required": [
+        "years",
+        "note"
+      ],
+      "type": "object"
+    }
+  },
+  "required": [
+    "provenance",
+    "attribution"
+  ],
+  "type": "object"
+}

Added value: +false