# The person object

Attributes:
- `id` (string): Person identifier (`psn_<digits>`).
- `name` (string, nullable): The familiar name the person is known by (Rodri); the legal name is `full_name`. `null` with `name_status: unavailable` when the person has no name yet (a referee or coach whose source gives no name), which is not a 404.
- `name_status` (enum): Says why a nullable `name` is or is not served: `known` = a dated name applies at `valid_at` as known at the cutoff; `unavailable` = the entity exists but has no dated name at that date (for example a team known from a source that reports no names); `withheld` = a name exists but the rights of its sources do not allow serving it to you. An entity is never a 404 for lacking a name. One of: `known`, `unavailable`, `withheld`.
- `full_name` (string, nullable): The full legal name (Rodrigo Hernández Cascante for `name` Rodri); `null` when no servable source supplies it.
- `first_name` (string, nullable): First name; `null` when no servable source supplies it.
- `last_name` (string, nullable): Last name; `null` when no servable source supplies it.
- `aliases` (array of strings): Every other spelling a servable source gave for the person (Savio, Sávio Moreira de Oliveira for `name` Savinho), including those given for a person merged into this one while the merge stands, without `name` and `full_name`; a spelling stops being an alias when its source no longer maps the person or corrects it. For search and matching. Empty when there is none.
- `association_code` (string, nullable): Football nationality as a FIFA member-association code; `null` when unknown.
- `born_on` (date, nullable)
- `height_cm` (integer, nullable): Height in centimetres; `null` when unknown.
- `weight_kg` (integer, nullable): Weight in kilograms; `null` when unknown.
- `birth_country_code` (string, nullable): Country of birth as a FIFA code (not the football nationality, which is `association_code`); `null` when unknown.
- `position` (enum, nullable): A player's main position; `null` when unknown or never a player. One of: `goalkeeper`, `defender`, `midfielder`, `attacker`.
- `detailed_position` (enum, nullable): A player's detailed position, always one of `position`'s (a source's detailed position of another main position is not served); `null` when unknown or never a player. One of: `goalkeeper`, `centre_back`, `left_back`, `right_back`, `defensive_midfield`, `central_midfield`, `attacking_midfield`, `left_midfield`, `right_midfield`, `left_wing`, `right_wing`, `second_striker`, `centre_forward`.
- `preferred_foot` (enum, nullable): Preferred foot; `null` when unknown. One of: `left`, `right`, `both`.
- `birth_place` (string, nullable): Place of birth as the source names it; `null` when unknown.
- `contract_until` (date, nullable): End of the current club contract; `null` when unknown.
- `roles` (array of objects)
  - `role` (enum):  One of: `coach`, `player`, `referee`.
  - `team_id` (string, nullable): Team identifier (`tm_<digits>`).
  - `competition_id` (string, nullable): Competition identifier (`cmp_<digits>`).
  - `from` (date)
  - `to` (date, nullable)
- `resolution` (object): How the requested identifier resolved. Present whenever the requested identifier is not the canonical one, and optional otherwise.
  - `requested_id` (string): OddsFinder identifier, `<prefix>_<digits>`, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. `Resolution` uses this generic form because its identifiers are of the resource's kind.
  - `canonical_id` (string): OddsFinder identifier, `<prefix>_<digits>`, a per-kind sequence number without padding, leading zeros, grouping or sign (1 to 9223372036854775807). The prefix names the kind; the per-kind schemas fix it where a field or parameter has one kind. `Resolution` uses this generic form because its identifiers are of the resource's kind.
  - `status` (enum): `canonical`: the requested identifier is the identity itself; `alias`: it was retired by a merge decision and resolves to `canonical_id`. One of: `canonical`, `alias`.
  - `decision_id` (string, nullable): Identifier of a merge or reversal decision (`dec_<digits>`), a record you can cite.
  - `decided_at` (timestamp, nullable): A `Timestamp`, or `null` when unknown; the owning object says why.
- `knowledge` (object): The effective knowledge cutoff of the response. Under a grant freshness delay it is never later than the request time minus the delay, whatever `known_at` asked for.
  - `known_at` (timestamp): RFC 3339 instant in UTC with `Z` suffix; optional fractional seconds up to microseconds.
  - `as_requested` (boolean): True when the caller supplied `known_at`; false when it defaulted to the request time.
- `sources` (object): Source references, or an explicit statement that they are withheld by source rights or unknown.
  - `status` (enum):  One of: `included`, `withheld`, `unknown`.
  - `items` (array of objects)
    - `source` (string): Source namespace (for example `footystats`).
    - `observed_at` (timestamp, nullable): A `Timestamp`, or `null` when unknown; the owning object says why.
    - `recorded_at` (timestamp): RFC 3339 instant in UTC with `Z` suffix; optional fractional seconds up to microseconds.
    - `precision` (enum): Precision of the source timestamp; `unknown` when the source gave none. One of: `unknown`, `day`, `hour`, `minute`, `second`, `millisecond`.
- `provenance` (object): `include=provenance`: for every field whose value OddsFinder chooses among several sources, the source report its ranking of sources selects among those recorded by the cutoff. The served value is in the body; this block says where it came from. `policy` identifies the ranking used (sport and version).
  - `policy` (object)
    - `sport` (string)
    - `version` (integer)
  - `fields` (map)
    - `status` (enum):  One of: `known`, `unavailable`, `no_observation`, `withheld`.
    - `provider` (string, nullable): A source provider or namespace name (`footystats`, `football`).
    - `namespace` (string, nullable): A source provider or namespace name (`footystats`, `football`).
    - `source_time` (timestamp, nullable): A `Timestamp`, or `null` when unknown; the owning object says why.
    - `source_time_precision` (enum, nullable):  One of: `unknown`, `day`, `hour`, `minute`, `second`, `millisecond`.
    - `observed_at` (timestamp, nullable): A `Timestamp`, or `null` when unknown; the owning object says why.
    - `recorded_at` (timestamp, nullable): A `Timestamp`, or `null` when unknown; the owning object says why.

Example:

```json
{
  "id": "psn_5",
  "name": "L. Ferri",
  "name_status": "known",
  "full_name": null,
  "first_name": null,
  "last_name": null,
  "aliases": [],
  "association_code": null,
  "born_on": null,
  "height_cm": null,
  "weight_kg": null,
  "birth_country_code": null,
  "position": null,
  "detailed_position": null,
  "preferred_foot": null,
  "birth_place": null,
  "contract_until": null,
  "roles": [],
  "resolution": {
    "requested_id": "psn_5",
    "canonical_id": "psn_5",
    "status": "canonical",
    "decision_id": "dec_2",
    "decided_at": "2026-09-20T10:00:00Z"
  },
  "knowledge": {
    "known_at": "2026-10-04T09:00:00Z",
    "as_requested": false
  }
}
```