List Schema

Entries in the org-id.guide platform MUST be provided as JSON data following the latest version of the list schema, available here.

The schema structure is documented below. More details on how to populate schema elements are found in the research guidance

Additional schema information

The schema is compiled from a number of source files that contain codelists embedded within the schema. These codelist files also contain weighting used to calculate quality scores.

The schema includes some additional properties to aid interface creation:

Schema overview

Title Description Type Format Required
name object    
List name Provide the name of this list in English, and then the local language, if applicable.
name/en string    
English
name/local string    
Local language If this list has a local language name, please provide that here. If local law requires the name to be provided in multiple languages, separate these with ‘/’.
url string uri  
List URL Provide a URL where further information about this list can be found (e.g. the homepage of the relevant registar or list maintainer).
description object    
List description The list description should be written in plain text or markdown, and should contain the following paragraphs: (1) A description of the kinds of organisations that will be found on this list (this should be summarised from official websites/information where available); (2) A short (1-2 sentence) explanation of how organisations end up on this list (e.g. relevant information on registration procedures); and (3) Any essential considerations for users of this list. Numbered footnotes can be included using markdown syntax (e.g. [1] in-line to indicate a footnote, and list of citations at the bottom of the text each on their own line formatted as ‘[1]: Citation’ etc.).
description/en string textarea  
None
coverage array[[string]]    
Geographic coverage Which country, countries or kind of region does this organisation list cover? For any list which contains entries only from a given country, or a defined list of countries, the ISO 2-digit country code(s) should be used. For lists that contain entries from multiple countries (but not a restricted list), one of the following codes should be used: XM for Multilateral/international agencies; XI for International; XR for Regional and ZZ for publisher created lists with no particular jurisdictional focus.
subnationalCoverage array[[string, null]]    
Subnational jurisdiction If this list does not cover a whole country, but only covers one or more sub-national territories, enter the ISO 3166-2 Subdivision Assigned Code.
structure array[[string]] table  
Legal structure Select all the legal structures which this list covers. Note that legal structures are organised hierarchically in the dataset. So, for example, ‘Sole Trader’ is a kind of company.
sector array[[string, null]]    
Sector If this list is specific to a particular sector, you can declare that here. If the list is not specific to a particular sector, leave this field blank.
code string    
List code Each organisation list code is made up of two parts: (1) a jurisdiction code; and (2) a list code. The list code should be: between 2 and 7 characters long; using a recognisable acronym or contraction of the name of the organisation list; based on the local language version of the list name; and memorable wherever possible.
confirmed boolean    
List reviewed? Once this list has been reviewed by an administrator, this value can be set as true. Only reviewed codes should be included in production systems, and non-confirmed codes should be treated as drafts.
deprecated boolean    
Deprecated? If this list has been removed from active use, deprecated should be set to true. The description of the list should be updated to explain the reason for deprecation. Systems should warn users against using deprecated lists.
listType string    
List type You will need to determine if this list is a primary identifier list or whether it has secondary, third-party or local status.
access object    
Access information Information about access to this list, the identifiers and additional information it contains.
access/availableOnline boolean    
Available online? Is is possible to access this list online in any form (search / bulk download etc.)
access/onlineAccessDetails [string, null] textarea  
Online access details An optional description of how to access this list online, including details of any registration requirements or other limitations on free access.
access/publicDatabase string url  
List URL Where should users go to search or access this list?
access/guidanceOnLocatingIds string textarea  
How to locate identifiers Provide brief guidance on how someone visiting the URL for this list should locate an identifier. This should include a description of any steps that need to be taken for format the identifier that is returned.
access/exampleIdentifiers string    
Example identifiers Please give a short list (3 - 5 entries) with example identifiers from this register. These should be formatted for use in an org-id string (e.g. removing spaces, or special characters). Where a list contains a range of different kinds of identifiers, try to provide a representative sample.
access/languages array[string]    
Languages Which languages is this list, and/or the interfaces to access it, available in?
data object    
Dataset access Details of whether or not an open dataset is available for this list.
data/availability array[string]    
Data availability (was DataAccessProperties) Is structured data available from this list in any of these formats or mechanisms?
data/dataAccessDetails string textarea  
Data access details (was dataAccessDetails) Please describe how to access data in the formats listed above. Include additional URLs where neccessary.
data/features array[string]    
Dataset features (was datasetFeatures) Does the data available from this list (in any format) contain any of these features?
data/licenseStatus string    
License status Is the data described above available under an open license?
data/licenseDetails string    
License details Details of the license, including a link to the license where applicable.
meta object    
Metadata Every list should be supported by a meta-data record
meta/source string    
Source Please briefly describe the source of the information (e.g. original research; official records etc.).
meta/lastUpdated string datetime  
Last updated A timestamp to the last update to this record
links object    
Links For links to supporting information, or other database records, about this list
links/opencorporates string url  
Open Corporates A link to the Open Corporates page for this identifier should be provide only when Open Corporates has dataset for this list.
links/wikipedia string url  
Wikipedia page If there is a wikipedia page that provides context to this this list (e.g. page describing the registrar behind the list) the link should be included here.
formerPrefixes array[string]    
Former list codes In some cases a list code may be changed. This field will list deprecated codes for this list.