{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api.brazilmcp.dev/schemas/company_lookup.schema.json",
  "title": "company_lookup response (v1)",
  "description": "Brazilian company registry lookup by CNPJ. Data from Receita Federal open data (monthly extraction). Field names in English; values as registered (Portuguese). Consumers MUST tolerate unknown fields (additive minor changes).",
  "type": "object",
  "required": [
    "schema_version",
    "tool",
    "generated_at",
    "query",
    "result_status",
    "data"
  ],
  "properties": {
    "schema_version": {
      "type": "string",
      "pattern": "^1\\.\\d+\\.\\d+$"
    },
    "tool": {
      "const": "company_lookup"
    },
    "generated_at": {
      "type": "string",
      "format": "date-time"
    },
    "query": {
      "type": "object",
      "required": [
        "input",
        "cnpj"
      ],
      "properties": {
        "input": {
          "type": "string",
          "description": "Raw input as received"
        },
        "cnpj": {
          "oneOf": [
            {
              "$ref": "#/$defs/cnpj"
            },
            {
              "type": "null"
            }
          ],
          "description": "Normalized CNPJ the query resolved to; null when a name query matched no company (result_status = not_found)"
        }
      }
    },
    "result_status": {
      "enum": [
        "found",
        "not_found"
      ]
    },
    "data": {
      "oneOf": [
        {
          "type": "null",
          "description": "When result_status = not_found"
        },
        {
          "$ref": "#/$defs/companyRecord"
        }
      ]
    }
  },
  "$defs": {
    "cnpj": {
      "type": "string",
      "pattern": "^\\d{14}$",
      "description": "CNPJ, 14 digits, no punctuation"
    },
    "codeLabel": {
      "type": "object",
      "required": [
        "code",
        "label"
      ],
      "properties": {
        "code": {
          "type": "string",
          "description": "Stable source code — use for logic"
        },
        "label": {
          "type": [
            "string",
            "null"
          ],
          "description": "Human/model-readable label, as in source"
        }
      }
    },
    "source": {
      "type": "object",
      "required": [
        "name",
        "data_date",
        "retrieved_at"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "data_date": {
          "type": [
            "string",
            "null"
          ],
          "format": "date",
          "description": "Reference date of the data at origin (RFB monthly extraction may lag up to ~1 month)"
        },
        "retrieved_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "money": {
      "type": "object",
      "required": [
        "amount",
        "currency"
      ],
      "properties": {
        "amount": {
          "type": "number"
        },
        "currency": {
          "type": "string",
          "default": "BRL"
        }
      }
    },
    "companyRecord": {
      "type": "object",
      "required": [
        "cnpj",
        "legal_name",
        "is_head_office",
        "registration_status",
        "opened_on",
        "legal_nature",
        "main_activity",
        "address",
        "partners",
        "source"
      ],
      "properties": {
        "cnpj": {
          "$ref": "#/$defs/cnpj"
        },
        "legal_name": {
          "type": "string",
          "description": "Razão social, as registered"
        },
        "trade_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Nome fantasia"
        },
        "is_head_office": {
          "type": "boolean",
          "description": "true = matriz, false = filial"
        },
        "registration_status": {
          "allOf": [
            {
              "$ref": "#/$defs/codeLabel"
            }
          ],
          "description": "Situação cadastral. Known RF codes (open enum): 01 NULA, 02 ATIVA, 03 SUSPENSA, 04 INAPTA, 08 BAIXADA",
          "properties": {
            "since": {
              "type": [
                "string",
                "null"
              ],
              "format": "date"
            }
          }
        },
        "opened_on": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        },
        "legal_nature": {
          "$ref": "#/$defs/codeLabel"
        },
        "company_size": {
          "oneOf": [
            {
              "$ref": "#/$defs/codeLabel"
            },
            {
              "type": "null"
            }
          ],
          "description": "Porte (RF): 01 NAO INFORMADO, 03 EPP, 05 DEMAIS (open enum)"
        },
        "share_capital": {
          "oneOf": [
            {
              "$ref": "#/$defs/money"
            },
            {
              "type": "null"
            }
          ]
        },
        "main_activity": {
          "allOf": [
            {
              "$ref": "#/$defs/codeLabel"
            }
          ],
          "description": "Primary CNAE"
        },
        "secondary_activities": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/codeLabel"
          }
        },
        "address": {
          "type": "object",
          "required": [
            "city",
            "state"
          ],
          "properties": {
            "street": {
              "type": [
                "string",
                "null"
              ]
            },
            "number": {
              "type": [
                "string",
                "null"
              ]
            },
            "complement": {
              "type": [
                "string",
                "null"
              ]
            },
            "district": {
              "type": [
                "string",
                "null"
              ]
            },
            "city": {
              "type": "object",
              "required": [
                "name"
              ],
              "properties": {
                "ibge_code": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "name": {
                  "type": "string"
                }
              }
            },
            "state": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2,
              "description": "UF"
            },
            "zip_code": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        },
        "tax_regime": {
          "type": "object",
          "properties": {
            "simples": {
              "$ref": "#/$defs/optedSince"
            },
            "mei": {
              "$ref": "#/$defs/optedSince"
            }
          }
        },
        "partners": {
          "type": "array",
          "description": "QSA as in the public company registry. LGPD boundary: name only as registered; NO personal documents (not even masked), no enrichment.",
          "items": {
            "type": "object",
            "required": [
              "name",
              "person_type",
              "qualification"
            ],
            "properties": {
              "name": {
                "type": "string"
              },
              "person_type": {
                "enum": [
                  "natural",
                  "legal",
                  "foreign",
                  null
                ],
                "description": "RF identificador de sócio: 2=natural, 1=legal, 3=foreign; null if the source identifier is unknown"
              },
              "qualification": {
                "$ref": "#/$defs/codeLabel"
              },
              "joined_on": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date"
              }
            }
          }
        },
        "source": {
          "$ref": "#/$defs/source"
        },
        "has_corporate_group": {
          "type": [
            "boolean",
            "null"
          ],
          "description": "True when this company has at least one corporate (PJ) shareholder or subsidiary in the registry-derived ownership graph — i.e. when company_group would return an actual graph. False when it has none (the common case: only ~0.7% of all CNPJs do, though 27–39% of those with share capital above R$ 1M). Null when the ownership graph is not loaded on this instance — never assume false from null. Use it to decide whether the company_group call is worth its price."
        }
      }
    },
    "optedSince": {
      "type": "object",
      "required": [
        "opted"
      ],
      "properties": {
        "opted": {
          "type": [
            "boolean",
            "null"
          ]
        },
        "since": {
          "type": [
            "string",
            "null"
          ],
          "format": "date"
        }
      }
    }
  }
}