Markus Schepke
Joined 16 March 2015
Wikibase JSON format edit
This document describes the canonical JSON format used to represent Wikibase entities in the API, in JSON dumps, as well as by Special:EntityData (when using JSON output). This format can be expected to be reasonably stable, and is designed with flexibility and robustness in mind.
For an explanation of the terms used in this document, please refer to the Wikibase Glossary.
NOTE: this is different from the JSON format used by Wikibase internally, when storing entities to the database. The internal format is what is used in MediaWiki's XML dumps and returned by Special:Export and the by some API modules that return raw revision text. The internal format is designed to be terse, and may frequently change. External tools should use the canonical JSON format whenever possible, and should not rely on the internal format.
JSON Flavor edit
When encoding the data structure in JSON, several choices had to be made as to how values are represented:
- Strings are encoded in one of two ways:
- using either Unicode escape sequences (like \u0645) resulting in a UTF16 representation when decoded.
- ...or using native UTF8 encoding.
- Numbers may be given in two ways:
- as numeric JavaScript literals (float or int)
- ...or as strings. Strings are preferable where the precision of numeric literals guaranteed by JSON may not be sufficient.
- Entity IDs are given as upper-case strings, e.g. "P29" or "Q623289". Note: until recently, lower-case prefixes were used in entity IDs!
Clients should be ready to process any of the forms given above.
Top Level Structure edit
{
"id": "Q60",
"type": "item",
"labels": {},
"descriptions": {},
"aliases": {}
"claims": {},
"sitelinks": {},
"lastrevid": 195301613,
"modified": "2015-02-10T12:42:02Z"
}
The JSON representation consists of the following fields in the top level structure:
- id: The canonical ID of the entity.
- type: The entity type identifier. "item" for data items, and "property" for properties.
- labels: Contains the labels in different languages, see Labels, Descriptions and Aliases below.
- descriptions: Contains the descriptions in different languages, see Labels, Descriptions and Aliases below.
- aliases: Contains aliases in different languages, see Labels, Descriptions and Aliases below.
- claims: Contains any number of claims or statements, groups by property. See Claims and Statements below.
- sitelinks: Contains site links to pages on different sites describing the item, see Site Links below.
- lastrevid: The JSON document's version (this is a MediaWiki revision ID).
- modified: The JSON document's publication date (this is a MediaWiki revision timestamp).
API modules currently handle the revision and date modified slightly differently using the fields below.
{
"lastrevid": 195301613,
"modified": "2015-02-10T12:42:02Z"
}
API modules also often return extra information related to the entity and the wiki:
{
"title": "Q60",
"pageid": 186,
"ns": 0
}
- title: The title of the page the entity is stored on (this could also include namespace such as 'Item:Q60')
- pageid: The page id the entity is stored on
- ns: the namespace id the entity is stored in
Labels, Descriptions and Aliases edit
{
"labels": {
"en": {
"language": "en",
"value": "New York City"
},
"ar": {
"language": "ar",
"value": "\u0645\u062f\u064a\u0646\u0629 \u0646\u064a\u0648 \u064a\u0648\u0631\u0643"
}
},
"descriptions": {
"en": {
"language": "en",
"value": "largest city in New York and the United States of America"
},
"it": {
"language": "it",
"value": "citt\u00e0 degli Stati Uniti d'America"
}
},
"aliases": {
"en": [
{
"language": "en",
"value": "NYC"
},
{
"language": "en",
"value": "New York"
},
],
"fr": [
{
"language": "fr",
"value": "New York City"
},
{
"language": "fr",
"value": "NYC"
},
{
"language": "fr",
"value": "The City"
},
{
"language": "fr",
"value": "City of New York"
},
{
"language": "fr",
"value": "La grosse pomme"
}
]
}
}
Labels, descriptions and aliases are represented by the same basic data structure. For each language, there is a record using the following fields:
- language: The language code.
- value: The actual label or description.
In the case of aliases, each language is associated with a list of such records, while for labels and descriptions the record is associated directly with the language.
Site Links edit
{
"sitelinks": {
"afwiki": {
"site": "afwiki",
"title": "New York Stad",
"badges": []
},
"frwiki": {
"site": "frwiki",
"title": New York City",
"badges": []
},
"nlwiki": {
"site": "nlwiki",
"title": "New York City",
"badges": [
"Q17437796"
]
},
"enwiki": {
"site": "enwiki",
"title": "New York City",
"badges": []
},
"dewiki": {
"site": "dewiki",
"title": "New York City",
"badges": [
"Q17437798"
]
}
}
}
Site links are given as records for each site identifier. Each such record contains the following fields:
- site: The site ID.
- title: The page title.
- badges: Any "badges" associated with the page (such as "featured article"). Badges are given as a list of item IDs.
- url: Optionally, the full URL of the page may be included.
Claims and Statements edit
{
"claims": {
"P17": [
{
"id": "q60$5083E43C-228B-4E3E-B82A-4CB20A22A3FB",
"mainsnak": {},
"type": "statement",
"rank": "normal",
"qualifiers": {
"P580": [],
"P5436": []
}
"references": [
{
"hash": "d103e3541cc531fa54adcaffebde6bef28d87d32",
"snaks": []
}
]
}
]
}
}
A Claim consists of a main value (or main Snak) and a number of qualifier Snaks. A Statement is a Claim that also contains a (possibly empty) list of references. A claim is always associated with a Property (semantically, the Claim is about the Property), and there can be multiple Claims about the same Property in a single Entity. This is represented by a map structure that uses Property IDs as keys, and maps them to lists of Claim records.
A Claim record uses the following fields:
- id: An arbitrary identifier for the claim, which is unique across the repository. No assumptions can and shall be made about the identifier's structure, and no guarantees are given that the format will stay the same.
- type: the type of the claim - currently either statement or claim.
- mainsnak: If the claim has the type value, it has a mainsnak field that contains the Snak representing the value to be associated with the property. See Snaks below. The Property specified in the main Snak must be the same as the property the Claim is associated with. That is, if a value claim is provided for property P17, its main Snak will specify P17 as the property the value is assigned to.
- rank: Ihe rank expresses whether this value will be used in queries, and shown be visible per default on a client system. The value is either preferred, normal or deprecated.
- qualifiers: Qualifiers provide a context for the primary value, such as the point in time of measurement. Qualifiers are given as lists of snaks, each associated with one property. See Qualifiers below.
- references: If the Claim's type is statement, there may be a list of references, given as a list of reference records. See References below.
Snaks edit
{
"claims": {
"P17": [
{
"mainsnak": {
"snaktype": "value",
"property": "P17",
"datatype": "wikibase-item",
"datavalue": {
"value": {
"entity-type": "item",
"numeric-id": 30
},
"type": "wikibase-entityid"
}
},
},
{
"mainsnak": {
"snaktype": "somevalue",
"property": "P17",
},
}
],
"P356": [
{
"mainsnak": {
"snaktype": "value",
"property": "P356",
"datatype": "string",
"datavalue": {
"value": "SomePicture.jpg",
"type": "string"
}
},
}
]
}
}
A Snak provides some kind of information about a specific Property of a given Entity. Currently, there are three kinds of Snaks: value, somevalue or novalue. A value snak represents a specific value for the property, which novalue and somevalue only express that there is no, or respectively some unknown, value.
A Snak is represented by providing the following fields:
- snaktype: The type of the snak. Currently, this is one of value, somevalue or novalue.
- property: The ID of the property this Snak is about.
- datatype: The datatype field indicates how the value of the Snak can be interpreted. The datatypes could be any other of the datatypes listed on Special:ListDatatypes.
- datavalue: If the snaktype is value, there is a datavalue field that contains the actual value the Snak associates with the Property. See Data Values below.
Data Values edit
"datavalue": {
"value": {
"entity-type": "item",
"numeric-id": 30
},
"type": "wikibase-entityid"
}
"datavalue": {
"value": "SomePicture.jpg",
"type": "string"
}
Data value records represent a value of a specific type. They consist of two fields:
- type: the value type. This defines the structure of the value field, and is not to be confused with the Snak's data type (which is derived from the Snak's Property's data type). The value type does not allow for interpretation of the value, only for processing of the raw structure. As an example, a link to a web page may use the data type "url", but have the value type "string".
- value: the actual value. This field may contain a single string, a number, or a complex structure. The structure is defined by the type field.
Some value types and their structure are defined in the following sections.
string edit
"datavalue": {
"value": "SomePicture.jpg",
"type": "string"
}
Strings are given is given as simple string literals.
wikibase-entityid edit
"datavalue": {
"value": {
"entity-type": "item",
"numeric-id": 30
},
"type": "wikibase-entityid"
}
Entity IDs are used to reference entities on the same repository. They are represented by a map structure containing two fields:
- entity-type: defines the type of the entity, such as item or property.
- numeric-id: the is the actual ID number.
WARNING: wikibase-entityid may in the future change to be represented as a single string literal, or may even be dropped in favor of using the string value type to reference entities.
NOTE: There is currently no reliable mechanism for clients to generate a prefixed ID or a URL from the information in the data value.
globecoordinate edit
"datavalue": {
"value": {
"latitude": 52.516666666667,
"longitude": 13.383333333333,
"altitude": null,
"precision": 0.016666666666667,
"globe": "http:\/\/www.wikidata.org\/entity\/Q2"
},
"type": "globecoordinate"
}
- latitude: The latitude part of the coordinate in degrees, as a float literal (or an equivalent string).
- longitude: The longitude part of the coordinate in degrees, as a float literal (or an equivalent string).
- precision: the coordinate's precision, in (fractions of) degrees, given as a float literal (or an equivalent string).
- globe: the URI of a reference globe. This would typically refer to a data item on wikidata.org. This is usually just an indication of the celestial body (e.g. Q2 = earth), but could be more specific, like WGS 84 or ED50.
- altitude: Deprecated and no longer used. Will be dropped in the future.
time edit
"datavalue": {
"value": {
"time": "+00000002001-12-31T00:00:00Z",
"timezone": 0,
"before": 0,
"after": 0,
"precision": 11,
"calendarmodel": "http:\/\/www.wikidata.org\/entity\/Q1985727"
},
"type": "time"
}
Time values are given as a map with the following fields:
- time: Date and time in ISO notation, including. E.g. "+00000001994-01-01T00:00:00Z". Note: the format and interpretation of this string may vary based on the calendar model. Currently, only julian and gregorian dates are supported, which use the ISO format.
- timezone: The time zone offset against UTC, in minutes. May be given as an integer or string literal.
- calendarmodel: A URI of a calendar model, such as gregorian or julian. Typically given as the URI of a data item on the repository
- precision: To what unit is the given date/time significant? Given as an integer indicating one of the following units:
- 0: 1 Gigayear
- 1: 100 Megayears
- 2: 10 Megayears
- 3: Megayear
- 4: 100 Kiloyears
- 5: 10 Kiloyears
- 6: Kiloyear
- 7: 100 years
- 8: 10 years
- 9: years
- 10: months
- 11: days
- 12: hours
- 13: minutes
- 14: seconds
- more may be added in the future, in order to indicate milli-, micro-, and nanoseconds.
- before: Begin of an uncertainty range, given in the unit defined by the precision field. (Currently unused, may be dropped in the future)
- after: End of an uncertainty range, given in the unit defined by the precision field. (Currently unused, may be dropped in the future)
Qualifiers edit
{
"qualifiers": {
"P580": [
{
"hash": "sssde3541cc531fa54adcaffebde6bef28g6hgjd",
"snaktype": "value",
"property": "P580",
"datatype": "time",
"datavalue": {
"value": {
"time": "+00000001994-01-01T00:00:00Z",
"timezone": 0,
"before": 0,
"after": 0,
"precision": 11,
"calendarmodel": "http:\/\/www.wikidata.org\/entity\/Q1985727"
},
"type": "time"
}
}
],
"P582": [
{
"hash": "f803e3541cc531fa54n7a9ffebde6bef28d87ddv",
"snaktype": "value",
"property": "P582",
"datatype": "time",
"datavalue": {
"value": {
"time": "+00000002001-12-31T00:00:00Z",
"timezone": 0,
"before": 0,
"after": 0,
"precision": 11,
"calendarmodel": "http:\/\/www.wikidata.org\/entity\/Q1985727"
},
"type": "time"
}
}
]
},
}
Qualifiers provide context for a Claim's value, such as a point in time, a method of measurement, etc. Qualifiers are given as snaks. The set of qualifiers for a statement is provided grouped by property ID, resulting in a map which associates property IDs with one list of snaks each.
References edit
{
"references": [
{
"hash": "7eb64cf9621d34c54fd4bd040ed4b61a88c4a1a0",
"snaks": {
"P143": [
{
"snaktype": "value",
"property": "P143",
"datatype": "wikibase-item",
"datavalue": {
"value": {
"entity-type": "item",
"numeric-id": 328
},
"type": "wikibase-entityid"
}
}
],
"P854": [
{
"snaktype": "value",
"property": "P854",
"datatype": "url",
"datavalue": {
"value": "http: //www.nytimes.com/2002/01/02/opinion/the-bloomberg-era-begins.html",
"type": "string"
}
}
]
},
"snaks-order": [
"P143",
"P854"
]
}
]
}
]
}
References provide provenance/authority information for individual claims. Each reference is a set of Snaks structured in a similar way to how qualifiers are represented: Snaks about the same property are grouped together in a list and made accessible by putting all these lists into a map, using the property IDs as keys. By snaks-order the order of those snaks is shown by their property IDs.
Example edit
Below is an example of an extract of a complete entity represented in JSON.
{
"pageid": 186,
"ns": 0,
"title": "Q60",
"lastrevid": 199780882,
"modified": "2015-02-27T14:37:20Z",
"id": "Q60",
"type": "item",
"aliases": {
"en": [
{
"language": "en",
"value": "NYC"
},
{
"language": "en",
"value": "New York"
}
],
"fr": [
{
"language": "fr",
"value": "New York City"
},
{
"language": "fr",
"value": "NYC"
},
],
"zh-mo": [
{
"language": "zh-mo",
"value": "\u7d10\u7d04\u5e02"
}
]
},
"labels": {
"en": {
"language": "en",
"value": "New York City"
},
"ar": {
"language": "ar",
"value": "\u0645\u062f\u064a\u0646\u0629 \u0646\u064a\u0648 \u064a\u0648\u0631\u0643"
},
"fr": {
"language": "fr",
"value": "New York City"
},
"my": {
"language": "my",
"value": "\u1014\u101a\u1030\u1038\u101a\u1031\u102c\u1000\u103a\u1019\u103c\u102d\u102f\u1037"
},
"ps": {
"language": "ps",
"value": "\u0646\u064a\u0648\u064a\u0627\u0631\u06a9"
}
},
"descriptions": {
"en": {
"language": "en",
"value": "largest city in New York and the United States of America"
},
"it": {
"language": "it",
"value": "citt\u00e0 degli Stati Uniti d'America"
},
"pl": {
"language": "pl",
"value": "miasto w Stanach Zjednoczonych"
},
"ro": {
"language": "ro",
"value": "ora\u015ful cel mai mare din SUA"
}
},
"claims": {
"P1151": [
{
"id": "Q60$6f832804-4c3f-6185-38bd-ca00b8517765",
"mainsnak": {
"snaktype": "value",
"property": "P1151",
"datatype": "wikibase-item",
"datavalue": {
"value": {
"entity-type": "item",
"numeric-id": 6342720
},
"type": "wikibase-entityid"
}
},
"type": "statement",
"rank": "normal"
}
],
"P625": [
{
"id": "q60$f00c56de-4bac-e259-b146-254897432868",
"mainsnak": {
"snaktype": "value",
"property": "P625",
"datatype": "globe-coordinate",
"datavalue": {
"value": {
"latitude": 40.67,
"longitude": -73.94,
"altitude": null,
"precision": 0.00027777777777778,
"globe": "http://www.wikidata.org/entity/Q2"
},
"type": "globecoordinate"
}
},
"type": "statement",
"rank": "normal",
"references": [
{
"hash": "7eb64cf9621d34c54fd4bd040ed4b61a88c4a1a0",
"snaks": {
"P143": [
{
"snaktype": "value",
"property": "P143",
"datatype": "wikibase-item",
"datavalue": {
"value": {
"entity-type": "item",
"numeric-id": 328
},
"type": "wikibase-entityid"
}
}
]
},
"snaks-order": [
"P143"
]
}
]
}
],
"P150": [
{
"id": "Q60$bdddaa06-4e4b-f369-8954-2bb010aaa057",
"mainsnak": {
"snaktype": "value",
"property": "P150",
"datatype": "wikibase-item",
"datavalue": {
"value": {
"entity-type": "item",
"numeric-id": 11299
},
"type": "wikibase-entityid"
}
},
"type": "statement",
"rank": "normal"
},
{
"id": "Q60$0e484d5b-41a5-1594-7ae1-c3768c6206f6",
"mainsnak": {
"snaktype": "value",
"property": "P150",
"datatype": "wikibase-item",
"datavalue": {
"value": {
"entity-type": "item",
"numeric-id": 18419
},
"type": "wikibase-entityid"
}
},
"type": "statement",
"rank": "normal"
},
{
"id": "Q60$e5000a60-42fc-2aba-f16d-bade1d2e8a58",
"mainsnak": {
"snaktype": "value",
"property": "P150",
"datatype": "wikibase-item",
"datavalue": {
"value": {
"entity-type": "item",
"numeric-id": 18424
},
"type": "wikibase-entityid"
}
},
"type": "statement",
"rank": "normal"
},
{
"id": "Q60$4d90d6f4-4ab8-26bd-f2a5-4ac2a6eb48cd",
"mainsnak": {
"snaktype": "value",
"property": "P150",
"datatype": "wikibase-item",
"datavalue": {
"value": {
"entity-type": "item",
"numeric-id": 18426
},
"type": "wikibase-entityid"
}
},
"type": "statement",
"rank": "normal"
},
{
"id": "Q60$ede49e3c-44f6-75a3-eb74-6a89886e30c9",
"mainsnak": {
"snaktype": "value",
"property": "P150",
"datatype": "wikibase-item",
"datavalue": {
"value": {
"entity-type": "item",
"numeric-id": 18432
},
"type": "wikibase-entityid"
}
},
"type": "statement",
"rank": "normal"
}
],
"P6": [
{
"id": "Q60$5cc8fc79-4807-9800-dbea-fe9c20ab273b",
"mainsnak": {
"snaktype": "value",
"property": "P6",
"datatype": "wikibase-item",
"datavalue": {
"value": {
"entity-type": "item",
"numeric-id": 4911497
},
"type": "wikibase-entityid"
}
},
"qualifiers": {
"P580": [
{
"hash": "c53f3ca845b789e543ed45e3e1ecd1dd950e30dc",
"snaktype": "value",
"property": "P580",
"datatype": "time",
"datavalue": {
"value": {
"time": "+00000002014-01-01T00:00:00Z",
"timezone": 0,
"before": 0,
"after": 0,
"precision": 11,
"calendarmodel": "http://www.wikidata.org/entity/Q1985727"
},
"type": "time"
}
}
]
},
"qualifiers-order": [
"P580"
],
"type": "statement",
"rank": "preferred"
},
{
"id": "q60$cad4e313-4b5e-e089-08b9-3b1c7998e762",
"mainsnak": {
"snaktype": "value",
"property": "P6",
"datatype": "wikibase-item",
"datavalue": {
"value": {
"entity-type": "item",
"numeric-id": 607
},
"type": "wikibase-entityid"
}
},
"qualifiers": {
"P580": [
{
"hash": "47c515b79f80e24e03375b327f2ac85184765d5b",
"snaktype": "value",
"property": "P580",
"datatype": "time",
"datavalue": {
"value": {
"time": "+00000002002-01-01T00:00:00Z",
"timezone": 0,
"before": 0,
"after": 0,
"precision": 11,
"calendarmodel": "http://www.wikidata.org/entity/Q1985727"
},
"type": "time"
}
}
],
"P582": [
{
"hash": "1f463f78538c49ef6adf3a9b18e211af7195240a",
"snaktype": "value",
"property": "P582",
"datatype": "time",
"datavalue": {
"value": {
"time": "+00000002013-12-31T00:00:00Z",
"timezone": 0,
"before": 0,
"after": 0,
"precision": 11,
"calendarmodel": "http://www.wikidata.org/entity/Q1985727"
},
"type": "time"
}
}
]
},
"qualifiers-order": [
"P580",
"P582"
],
"P856": [
{
"id": "Q60$4e3e7a42-4ec4-b7c3-7570-b103eb2bc1ac",
"mainsnak": {
"snaktype": "value",
"property": "P856",
"datatype": "url",
"datavalue": {
"value": "http://nyc.gov/",
"type": "string"
}
},
"type": "statement",
"rank": "normal"
}
]
},
"sitelinks": {
"afwiki": {
"site": "afwiki",
"title": "New York Stad",
"badges": []
},
"dewiki": {
"site": "dewiki",
"title": "New York City",
"badges": [
"Q17437798"
]
},
"dewikinews": {
"site": "dewikinews",
"title": "Kategorie:New York",
"badges": []
},
"elwiki": {
"site": "elwiki",
"title": "\u039d\u03ad\u03b1 \u03a5\u03cc\u03c1\u03ba\u03b7",
"badges": []
},
"enwiki": {
"site": "enwiki",
"title": "New York City",
"badges": []
},
"zhwikivoyage": {
"site": "zhwikivoyage",
"title": "\u7d10\u7d04",
"badges": []
},
"zuwiki": {
"site": "zuwiki",
"title": "New York (idolobha)",
"badges": []
}
}
}