Ontology schema reference

A field-level companion to the Ontology architecture page. The source of truth is schemas/ontology/ontology_v3.5.yaml (currently v3.5.2), published into the ontology_schema_versions table and validated for drift in CI.

Top-level structure

version: "3.5.2"
name: "Enhanced OSINT Schema (Complete)"
output_format:        # JSON contract every crew must return
entity_types:         # 8 entity types
relationship_types:   # 7 relationship types
risk_categories:      # 11 categories
crew_instructions:    # per-module guidance
compliance_rules:
risk_scoring:
survivorship:         # strategies, module_trust, provider_trust, protected_fields

Entity types

Type	Selected attributes
LegalEntity	legal_name (required), registration_number, registration_numbers (combine), jurisdiction, country_code (ISO 3166-1), lei (ISO 17442), vat_number, status, financials, sheets, events, segment_codes, contact_info, capital_history
Person	name, date_of_birth, nationalities, is_pep 🔒, pep_position/pep_source/pep_details/pep_category 🔒, is_sanctioned/sanctions_matches/sanctions_source/sanctions_lists 🔒
Address	street_address, postal_code, city, country, latitude, longitude, premises_type
Document	source documents / filings
Domain	web domains
SanctionsMatch	a sanctions-list match
PEPExposure	PEP exposure detail
AdverseMedia	adverse-media mention, with sentiment

🔒 = protected field.

Relationship types

Type	Source → Target
Directorship	Person → LegalEntity
Ownership	Entity → LegalEntity
RegisteredAt	LegalEntity → Address
DocumentsEntity	Document → Entity
OwnsDomain	LegalEntity → Domain
MatchedTo	Person → SanctionsMatch
MentionedIn	Entity → AdverseMedia

Risk categories

sanctions · pep · adverse_media · ownership · governance · corporate_status · jurisdiction · digital_footprint · regulatory · data_quality · secrecy_jurisdiction

Survivorship

Strategies

most_trusted (source priority cir > mebo > roa > frls > spepws > amlrr > dfwo) · most_recent · most_complete · combine.

Module trust

Module	Weight
cir	10
mebo	8
roa	7
frls	6
spepws	5
amlrr	4
dfwo	3

Provider trust (selected)

Provider · field	Weight
northdata · registration_number	0.99
northdata · jurisdiction	0.99
northdata · legal_name	0.98
northdata · lei / country_code	0.95
northdata · _default	0.80
kvk · postal_code	0.95
kvk · _default	0.85
osint · premises_type / full_address	0.80
osint · _default	0.70

Protected fields

Entity	Fields
Person	is_pep, pep_position, pep_source, pep_details, pep_category, is_sanctioned, sanctions_matches, sanctions_source, sanctions_lists
LegalEntity	PEP / sanctions flags

These are never overwritten by a provider; they originate from the SPEPWS / AMLRR crews. See Claims & survivorship.

Crew output contract

Every crew returns:

{
  "entities": [{ "type": "...", "name": "...", "properties": {}, "confidence": 0.0 }],
  "relationships": [{ "type": "...", "source": "...", "target": "...", "properties": {} }],
  "risk_indicators": [{ "indicator_name": "...", "severity": "critical|high|medium|low",
                        "category": "...", "description": "...", "evidence": "..." }],
  "summary": { "data_quality_score": 0.0, "total_entities": 0,
               "total_relationships": 0, "key_findings": [] }
}

Versioning

Minor bumps keep the ontology_v3.5.yaml filename; history lives in git. Each version is published byte-equal into ontology_schema_versions by a companion migration (e.g. V130__ontology_schema_v3_5_2.sql), and a CI drift check enforces parity between YAML and database. Schema lifecycle is governed by ADR-010.