Skip to content

Add citizenship-document object template #536

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adulau merged 1 commit into from
Oct 9, 2026
Merged

Add citizenship-document object template #536

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,7 @@ for a specific attribute. An optional **to_ids** boolean field to disable the ID
- [objects/cap-resource](https://github.com/MISP/misp-objects/blob/main/objects/cap-resource/definition.json) - Common Alerting Protocol Version (CAP) resource object.
- [objects/cert-pl-phishing](https://github.com/MISP/misp-objects/blob/main/objects/cert-pl-phishing/definition.json) - cert.pl phishing object template representing an url along with some metadata as such phash, html-structure or partial-hash.
- [objects/chat-message](https://github.com/MISP/misp-objects/blob/main/objects/chat-message/definition.json) - A message exchanged on a chat or messaging platform.
- [objects/citizenship-document](https://github.com/MISP/misp-objects/blob/main/objects/citizenship-document/definition.json) - A document attesting a person's citizenship or nationality, including citizenship, naturalisation, registration and nationality certificates, and other documents serving as citizenship evidence in the relevant jurisdiction. Supports paper and electronic documents, local naming and numbering conventions, and incomplete records. A residence permit or a place of birth alone does not establish citizenship.
- [objects/cloth](https://github.com/MISP/misp-objects/blob/main/objects/cloth/definition.json) - Describes clothes a natural person wears.
- [objects/coin-address](https://github.com/MISP/misp-objects/blob/main/objects/coin-address/definition.json) - An address used in a cryptocurrency.
- [objects/command](https://github.com/MISP/misp-objects/blob/main/objects/command/definition.json) - Command functionalities related to specific commands executed by a program, whether it is malicious or not. Command-line are attached to this object for the related commands.
Expand Down
27 changes: 27 additions & 0 deletions objects/citizenship-document/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Citizenship document

Use one object per document attesting a person's citizenship or nationality. The template covers citizenship, naturalisation, registration and nationality certificates, citizenship cards and confirmation letters. Passports, national identity cards, birth certificates and consular birth records can also be represented when they serve as citizenship evidence in the relevant jurisdiction. Their names alone do not establish that they do so. Residence permits and travel documents issued to non-citizens do not establish citizenship.

All document types and acquisition bases are suggestions rather than closed lists. Preserve local terminology, Unicode names, mononyms, original scripts, leading zeros and punctuation in identifiers. A full name is sufficient; separate given, middle and family names are optional. No country, document number, photograph, expiration date or acquisition basis is mandatory. At least one document number, registry reference, full name, name in an original script, attachment or document transcription is needed.

Keep these concepts separate:

- `citizenship`: the citizenship or nationality actually attested by this document. Multiple values are available when the document explicitly attests more than one.
- `issuing-country`: the jurisdiction on whose behalf it was issued.
- `place-of-issue`: its physical place of issue, including a consulate abroad.
- `document-number`: this document's identifier; `person-number` identifies the holder and `registry-reference` identifies an associated register or case.
- `citizenship-date`: when citizenship took effect; `issue-date` and `expiration-date` describe this document's validity. An expired document does not imply expired citizenship.

Use the existing MISP date types for known dates: `date-of-birth` uses YYYY-MM-DD; the other structured dates use `datetime` and can represent a known calendar date without inventing a time of day. Preserve partial, uncertain or non-Gregorian dates verbatim in `document-text` or `text` when they cannot be reliably converted. Omit inapplicable fields rather than using invented values or sentinel dates.

Typical mappings include:

| Case | Useful attributes |
| --- | --- |
| Naturalisation certificate without an expiration date | `document-type`, `document-number`, `full-name`, `citizenship`, `acquisition-basis`, `citizenship-date`, `issue-date`, `issuing-authority` |
| Citizenship card with separate card and person numbers | `document-type`, `document-number`, `person-number`, `full-name`, `citizenship`, `issue-date`, `expiration-date` when present |
| Consular record issued abroad | `document-type`, `registry-reference`, `citizenship`, `issuing-country`, `issuing-authority`, `place-of-issue`, `parent-name` when recorded |
| Unnumbered or partially legible historical certificate | `full-name` or `name-in-original-script`, `attachment`, `document-text`, `text` |
| Electronic citizenship confirmation | `document-type`, `full-name`, `citizenship`, `attachment`, `verification-url` |

Link to `person` objects for the holder or parents instead of duplicating their complete profiles. Link to `forged-document` or `leaked-document` objects for relevant investigative context. Administrative `document-status` and a verification URL do not themselves establish authenticity. Attributes default to `to_ids: false`; general metadata disables correlation while names and identifiers retain it.
271 changes: 271 additions & 0 deletions objects/citizenship-document/definition.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,271 @@
{
"attributes": {
"acquisition-basis": {
"description": "Basis for acquiring the citizenship attested by the document. Use the terminology of the issuing jurisdiction when known.",
"disable_correlation": true,
"misp-attribute": "text",
"multiple": true,
"sane_default": [
"birth",
"descent",
"naturalisation",
"registration",
"adoption",
"restoration"
],
"to_ids": false,
"ui-priority": 50
},
"address": {
"description": "Address of the holder as recorded on the document, without assuming a particular postal format.",
"misp-attribute": "text",
"multiple": true,
"to_ids": false,
"ui-priority": 20
},
"attachment": {
"description": "Scan, photograph, electronic original or other copy of the citizenship document. Multiple attachments can represent separate pages or sides.",
"misp-attribute": "attachment",
"multiple": true,
"to_ids": false,
"ui-priority": 80
},
"citizenship": {
"description": "Country or jurisdiction whose citizenship or nationality is explicitly attested by the document. Record multiple values only when the document attests them; do not infer citizenship from birthplace, residence or issuing country.",
"disable_correlation": true,
"misp-attribute": "nationality",
"multiple": true,
"to_ids": false,
"ui-priority": 95
},
"citizenship-date": {
"description": "Date on which the attested citizenship took effect, when stated. This may differ from the document's issue date.",
"disable_correlation": true,
"misp-attribute": "datetime",
"to_ids": false,
"ui-priority": 50
},
"date-of-birth": {
"description": "Date of birth of the holder in YYYY-MM-DD format, when known.",
"disable_correlation": true,
"misp-attribute": "date-of-birth",
"to_ids": false,
"ui-priority": 70
},
"document-name": {
"description": "Official title of the document, preserving the original language or local designation.",
"disable_correlation": true,
"misp-attribute": "text",
"to_ids": false,
"ui-priority": 60
},
"document-number": {
"description": "Identifier of this document, such as its certificate, card, passport or serial number. Preserve leading zeros, letters and punctuation; this is distinct from a person identifier or registry reference.",
"misp-attribute": "text",
"to_ids": false,
"ui-priority": 100
},
"document-status": {
"description": "Reported administrative status of the document. Expiration or cancellation of the document does not by itself establish loss of citizenship.",
"disable_correlation": true,
"misp-attribute": "text",
"sane_default": [
"valid",
"expired",
"cancelled",
"revoked",
"replaced",
"unknown"
],
"to_ids": false,
"ui-priority": 30
},
"document-text": {
"description": "Transcription or extracted text of the document, including original spellings, dates, annotations and fields not represented by other attributes.",
"disable_correlation": true,
"misp-attribute": "text",
"multiple": true,
"to_ids": false,
"ui-priority": 20
},
"document-type": {
"description": "Type of document attesting citizenship or nationality. Suggested values are non-exhaustive; use a local document type when appropriate. A passport, identity card or birth certificate belongs here only when it serves as evidence of citizenship in the relevant jurisdiction.",
"disable_correlation": true,
"misp-attribute": "text",
"sane_default": [
"citizenship certificate",
"naturalisation certificate",
"nationality certificate",
"citizenship registration certificate",
"citizenship confirmation letter",
"citizenship card",
"national identity card",
"passport",
"birth certificate",
"consular record of birth abroad"
],
"to_ids": false,
"ui-priority": 90
},
"expiration-date": {
"description": "End of document validity, if an expiration date exists. Omit for documents without an expiration date; this is not the expiration of citizenship.",
"disable_correlation": true,
"misp-attribute": "datetime",
"to_ids": false,
"ui-priority": 40
},
"first-name": {
"description": "Given name of the holder, when the document identifies a separate given-name component. Do not force an undivided name into this field.",
"disable_correlation": true,
"misp-attribute": "first-name",
"to_ids": false,
"ui-priority": 40
},
"full-name": {
"description": "Complete name of the holder as recorded on the document, preserving name order and supporting mononyms without requiring separate name components.",
"misp-attribute": "full-name",
"to_ids": false,
"ui-priority": 95
},
"gender": {
"description": "Sex or gender marker exactly as recorded on the document. No fixed vocabulary is imposed.",
"disable_correlation": true,
"misp-attribute": "gender",
"to_ids": false,
"ui-priority": 20
},
"issue-date": {
"description": "Date on which this document was issued, distinct from the date citizenship took effect.",
"disable_correlation": true,
"misp-attribute": "datetime",
"to_ids": false,
"ui-priority": 60
},
"issuing-authority": {
"description": "Authority that issued the document, such as a ministry, civil registry, court, municipality or consulate.",
"disable_correlation": true,
"misp-attribute": "text",
"to_ids": false,
"ui-priority": 70
},
"issuing-country": {
"description": "Country or jurisdiction on whose behalf the document was issued, including documents issued by its consulates abroad. This is distinct from the physical place of issue and the citizenship attested.",
"disable_correlation": true,
"misp-attribute": "text",
"to_ids": false,
"ui-priority": 80
},
"language": {
"description": "Language or languages used in the document; use an ISO 639 language code when available.",
"disable_correlation": true,
"misp-attribute": "text",
"multiple": true,
"to_ids": false,
"ui-priority": 10
},
"last-name": {
"description": "Family name of the holder, when the document identifies a separate family-name component.",
"misp-attribute": "last-name",
"to_ids": false,
"ui-priority": 40
},
"legal-basis": {
"description": "Legal provision, decision or order cited by the document as the basis for the attested citizenship.",
"disable_correlation": true,
"misp-attribute": "text",
"multiple": true,
"to_ids": false,
"ui-priority": 20
},
"middle-name": {
"description": "Middle name of the holder, when explicitly distinguished on the document.",
"disable_correlation": true,
"misp-attribute": "middle-name",
"to_ids": false,
"ui-priority": 20
},
"mrz": {
"description": "Machine-readable zone as printed on the document, if present. Preserve line breaks and filler characters.",
"misp-attribute": "text",
"to_ids": false,
"ui-priority": 20
},
"name-in-original-script": {
"description": "Name of the holder in an original or additional script as printed on the document, without requiring transliteration.",
"misp-attribute": "full-name",
"multiple": true,
"to_ids": false,
"ui-priority": 50
},
"parent-name": {
"description": "Name of a parent as recorded on the document. Use text for role labels or further context, and related person objects for detailed parent identities.",
"misp-attribute": "full-name",
"multiple": true,
"to_ids": false,
"ui-priority": 20
},
"person-number": {
"description": "Personal or national identification number of the holder as recorded on the document, distinct from this document's number. Preserve its original representation.",
"misp-attribute": "text",
"multiple": true,
"to_ids": false,
"ui-priority": 50
},
"place-of-birth": {
"description": "Place of birth of the holder as recorded on the document; do not infer citizenship from this value.",
"disable_correlation": true,
"misp-attribute": "place-of-birth",
"to_ids": false,
"ui-priority": 40
},
"place-of-issue": {
"description": "Physical place where the document was issued, which may be abroad or differ from the issuing authority's jurisdiction.",
"disable_correlation": true,
"misp-attribute": "text",
"to_ids": false,
"ui-priority": 30
},
"portrait": {
"description": "Portrait of the holder included in the document, if present.",
"misp-attribute": "attachment",
"multiple": true,
"to_ids": false,
"ui-priority": 20
},
"registry-reference": {
"description": "Reference to a citizenship register, case file, book, page or entry associated with the document. Preserve local reference formats.",
"misp-attribute": "text",
"multiple": true,
"to_ids": false,
"ui-priority": 40
},
"text": {
"description": "Additional context, comments or uncertainty about the document and its interpretation.",
"disable_correlation": true,
"misp-attribute": "text",
"multiple": true,
"to_ids": false,
"ui-priority": 10
},
"verification-url": {
"description": "URL provided for checking the document or retrieving its official electronic representation. Recording this URL does not establish authenticity.",
"misp-attribute": "link",
"multiple": true,
"to_ids": false,
"ui-priority": 20
}
},
"description": "A document attesting a person's citizenship or nationality, including citizenship, naturalisation, registration and nationality certificates, and other documents serving as citizenship evidence in the relevant jurisdiction. Supports paper and electronic documents, local naming and numbering conventions, and incomplete records. A residence permit or a place of birth alone does not establish citizenship.",
"meta-category": "misc",
"name": "citizenship-document",
"requiredOneOf": [
"document-number",
"registry-reference",
"full-name",
"name-in-original-script",
"attachment",
"document-text"
],
"uuid": "ed53b890-e087-4743-a774-c95496e8825c",
"version": 1
}
Loading