206 lines
5.0 KiB
Markdown
206 lines
5.0 KiB
Markdown
# 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"
|
|
}
|
|
}
|
|
}
|
|
```
|