Response models¶
Pydantic models returned by the client methods. All set
extra="ignore" — unknown server-side fields are silently dropped so
the client doesn't break when yente adds a field.
models ¶
Pydantic response models for the yente / OpenSanctions API.
These mirror the wire format, reshaped where a flatter surface reads better —
notably MatchResponse, flattened from the responses[<key>] envelope.
extra="ignore" on every response model means unknown server-side fields
are silently dropped, so the client doesn't break when yente adds a field. A
field the client doesn't model yet becomes available only after a client
release that adds it.
AdjacentPropertyResponse ¶
Bases: BaseModel
Body of /entities/{id}/adjacent/{property} — paginated entity refs.
AdjacentResponse ¶
Bases: BaseModel
Body of /entities/{id}/adjacent — entity plus its adjacency map.
Algorithm ¶
Bases: BaseModel
Description of one enabled matching algorithm.
Returned in the algorithms list of AlgorithmsResponse. The
docs dict maps feature name → human-readable description.
AlgorithmsResponse ¶
Bases: BaseModel
Body of /algorithms.
DataCoverage ¶
Bases: BaseModel
The temporal and geographic extent a dataset claims to cover.
Lives under Dataset.coverage. start / end are partial dates
("2020", "2020-06", or a full ISO date) so they stay strings here
rather than parsed datetimes. frequency is the update cadence and is
"unknown" when the publisher hasn't declared one.
DataPublisher ¶
Bases: BaseModel
Who publishes a dataset's source data.
Lives under Dataset.publisher. For OpenSanctions source datasets this
is the upstream authority (a sanctions body, registry, court); official
distinguishes a government/primary source from an aggregator.
Dataset ¶
Bases: BaseModel
One dataset entry in DatasetsResponse.datasets.
Mirrors a subset of yente's YenteDatasetModel — the fields most
callers actually use. Unknown fields are dropped via extra="ignore".
load is True on the dataset(s) yente has actually indexed (1 to N
per server). Every other catalog entry rides along as metadata —
collection definitions, source-level descriptors for the indexed
collection's children, etc. index_current / index_version only
carry meaningful freshness when load is true; on metadata-only
entries they reflect upstream state, not what's queryable here.
children is non-empty when the dataset is a collection — a grouping
that aggregates other datasets. The descriptive fields (summary,
entity_count, coverage, publisher, …) are populated for source
datasets and collections alike, but a given server only fills in what its
upstream metadata carries — expect most to be None on bare entries.
DatasetsResponse ¶
Bases: BaseModel
Body of /catalog: the list of indexed datasets and their freshness.
Named DatasetsResponse (not CatalogResponse) because the
payload is fundamentally a datasets listing; catalog remains the
wire endpoint name for the HTTP call.
Entity ¶
Bases: BaseModel
A FtM entity as the server returns it.
Different from the input entity classes (Person, Company, …):
response entities are dict-shaped (any schema) and carry server-only
metadata (datasets, referents, target, timestamps). Property values can
be nested entities when the server traverses adjacent edges.
FeatureResult ¶
Bases: BaseModel
Per-feature breakdown of how a match score was computed.
Lives under ScoredEntity.explanations keyed by feature name (e.g.
"name_match", "birth_date_match"). Useful for showing users why
a candidate scored as it did.
MatchResponse ¶
Bases: BaseModel
Flat response for /match.
The wire format wraps the result in responses[<key>]; the call layer
unwraps that envelope so callers always see a flat object. query
echoes the input as the server saw it (post-cleaning).
Program ¶
Bases: BaseModel
One sanctions program from the OpenSanctions program catalog.
key is the value entities carry in their programId property
(e.g. "EU-UKR", "US-RUSHAR") — fetch the catalog to resolve
those codes into the program's title, issuer, and policy summary.
ProgramIssuer ¶
Bases: BaseModel
The authority behind a sanctions program (government, UN body, …).
ProgramsResponse ¶
Bases: BaseModel
Body of the program catalog artifact — a plain list under data.
ScoredEntity ¶
Bases: Entity
An Entity plus match-specific scoring fields.
Returned only by /match; score is in [0.0, 1.0] and match is
true when score >= threshold per the request (defaults to 0.70).
contributing_explanations
property
¶
The features that actually moved the score — the non-zero subset.
Use when presenting why a candidate scored as it did: a match response
enumerates every feature the algorithm considered, including ones that
carried no signal (0.0 — a property the query didn't supply, or one
that doesn't apply to the schema). Those are noise in an explanation.
Negative features (penalties) are kept; only exact zeros are dropped.
explanations is left intact for callers that want the full set.
SearchFacet ¶
Bases: BaseModel
A facet aggregation under SearchResponse.facets.
SearchFacetItem ¶
Bases: BaseModel
One value within a search facet (e.g. one country in a countries facet).
SearchResponse ¶
Bases: BaseModel
Response shape for /search.
Statement ¶
Bases: BaseModel
One row of the statement-level data lineage stream.
Statements are the atomic claims that compose into entities — each
statement records a single (entity_id, prop, value) triple plus
provenance metadata (which dataset asserted it, when it was first
and last seen, language, original pre-cleaning value, and origin
— how the claim was produced, e.g. "inferred" or "patch",
unset for plain crawled data). See the
statement-based data model <https://www.opensanctions.org/docs/statements/>_
for background.
StatementsResponse ¶
Bases: BaseModel
Body of /statements — paginated list of statement rows.
StatusResponse ¶
Bases: BaseModel
Body of /healthz and /readyz: {"status": "ok"}.
TotalSpec ¶
Bases: BaseModel
Total-count envelope returned alongside paginated results.
relation indicates whether value is exact ("eq") or a lower
bound ("gte"); the server uses "gte" when result counts hit
Elasticsearch's track_total_hits limit.