# Data Models & Schemas (POC)

**Feature**: `001-multilingual-entity-classifier`
**Status**: Completed

---

## 1. Input Schemas

### 1.1 ECP Snapshot Schema (`snapshot.json`)

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ECPSnapshot",
  "type": "object",
  "required": [
    "target_entity_id",
    "target_name",
    "aliases",
    "domain",
    "anchors"
  ],
  "properties": {
    "target_entity_id": {
      "type": "string",
      "description": "Unique identifier of the entity"
    },
    "target_name": {
      "type": "string",
      "description": "Canonical name of the entity"
    },
    "aliases": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Multilingual aliases, acronyms, and trade names"
    },
    "domain": {
      "type": "string",
      "description": "Primary industry, category, or domain of the entity"
    },
    "anchors": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Key domain concepts, topics, and contextual keywords"
    },
    "negative_anchors": {
      "type": "array",
      "items": { "type": "string" },
      "default": [],
      "description": "Homonym disambiguators or exclusion terms"
    },
    "graph_version": {
      "type": "string",
      "default": "1.0.0",
      "description": "Version timestamp or hash of the source graph"
    },
    "related_entities": {
      "type": "array",
      "default": [],
      "items": {
        "type": "object",
        "required": ["entity_id", "name", "relation_type", "weight"],
        "properties": {
          "entity_id": { "type": "string" },
          "name": { "type": "string" },
          "aliases": { "type": "array", "items": { "type": "string" }, "default": [] },
          "relation_type": { "type": "string" },
          "weight": { "type": "number", "minimum": 0.0, "maximum": 1.0 },
          "scope": { "type": "string", "default": "general" },
          "confidence": { "type": "number", "minimum": 0.0, "maximum": 1.0, "default": 1.0 }
        }
      }
    }
  }
}
```

### 1.2 Content Item Schema (`content.md`)

- **Format**: Plain Markdown document (`.md` or `.txt`).
- **Validation Rules**:
  - Must not be empty (minimum 5 non-whitespace characters).
  - Must contain readable text in UTF-8 encoding.

---

## 2. Output Schemas

### 2.1 Classification Success Result Schema (`result.json`)

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ClassificationResult",
  "type": "object",
  "required": [
    "decision",
    "is_inherent",
    "confidence",
    "detected_language",
    "matched_anchors",
    "negative_matches",
    "graph_matches",
    "evidence",
    "rationale",
    "warnings"
  ],
  "properties": {
    "decision": {
      "type": "string",
      "enum": [
        "DIRECT_INHERENT",
        "CONTEXTUAL_INHERENT",
        "TANGENTIAL",
        "NOT_RELATED"
      ]
    },
    "is_inherent": {
      "type": "boolean",
      "description": "Derived: true if DIRECT_INHERENT or CONTEXTUAL_INHERENT; false if TANGENTIAL or NOT_RELATED"
    },
    "confidence": {
      "type": "number",
      "minimum": 0.0,
      "maximum": 1.0,
      "description": "Normalized confidence score of the classification"
    },
    "detected_language": {
      "type": "string",
      "description": "Detected ISO-639-1 code (pt, en, es, de, it, fr, etc.)"
    },
    "matched_anchors": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Entity aliases and direct anchors identified in text"
    },
    "negative_matches": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Negative anchors found in text"
    },
    "graph_matches": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "entity_id": { "type": "string" },
          "name": { "type": "string" },
          "relation_type": { "type": "string" },
          "weight": { "type": "number" }
        }
      },
      "description": "Related entities from snapshot matched in text"
    },
    "evidence": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Extracted textual snippets from Markdown justifying the decision"
    },
    "rationale": {
      "type": "string",
      "description": "Concise explanation of the classification verdict"
    },
    "warnings": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Non-fatal warnings encountered during processing"
    }
  }
}
```

### 2.2 Error Result Schema

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ClassificationError",
  "type": "object",
  "required": [
    "error_code",
    "message",
    "details"
  ],
  "properties": {
    "error_code": {
      "type": "string",
      "enum": [
        "invalid_ecp_json",
        "invalid_markdown",
        "unsupported_language",
        "empty_content",
        "missing_required_field"
      ]
    },
    "message": {
      "type": "string"
    },
    "details": {
      "type": "object"
    }
  }
}
```