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.