Creating a new Catalogue Template

This article takes administrators through the steps for adding a new catalogue template to their FAIR hub.

1. Create a long life token with appropriate permissions

New catalogue templates are created using the FAIR API, to interact with this user must create a long life token, which has the following catalogue permissions:

• The token can create catalogue definitions for use in datasets
• The token can view all catalogue definitions
• The token can modify which catalogue fields will be used when creating datasets
• The token can delete catalogue definitions

This will allow them to view, edit, create and delete catalogue templates via the FAIR API.

2. Identify an existing catalogue template as a base for your new template

We recommend that users base new catalogues on an existing template, the JSON for existing templates can be retrieved from the following endpoints:

3. Edit the template as required

Once the user has the JSON for their desired base template, they should edit as required by adding and removing fields as needed.

An example catalogue schema and full list of supported field types is available here.

The JSON for existing templates also contains system information related to that template, an example of this is shown below:

"code": "example-catalogue",
  "name": "Example Catalogue",
  "description": "Test Catalgoue",
  "created_at": "2023-07-27T13:51:35.993Z",
  "updated_at": "2023-07-27T14:11:29.082Z",
  "system": false,
  "enabled": true,

The fields code, created_at, updated_at, and system should be deleted, they are not required to submit the new template.

The user should enter a name and description for the new template. The enabled field determines if the new template is available in the FAIR UI, if set to 'true' the new template will be available for data owners to select for their datasets, if set to false it will not be.

4. Post new template to FAIR

When the user has finished creating their new template they can upload it to FAIR using the POST/templates/catalogues endpoint, an example payload is shown below:

{
  "name": "Example Catalogue",
  "description": "Example",
  "enabled": true,
  "sections": {
    "first": {
      "label": "Attribution",
      "fields": [
        {
          "name": "sector",
          "type": "list",
          "label": "Sector",
          "defaultValue": "1",
          "placeholder": "The Sector the data is for",
          "options": [
            {
              "text": "Pharma",
              "value": "1",
              "description": "Pharmaceutical"
            }
          ],
          "validation": {
            "required": true
          }
        }
      ]
    },
    "second": {
      "label": "DOI and keywords",
      "fields": [
        {
          "name": "age",
          "type": "list",
          "label": "Age",
          "defaultValue": 10,
          "validation": {
            "minimum": 1,
            "maximum": 120,
            "required": true
          }
        }
      ]
    },
    "third": {
      "label": "Versioning and other information",
      "fields": [
        {
          "name": "contactPoint",
          "type": "list",
          "label": "Contact Email",
          "defaultValue": "example@example.com",
          "placeholder": "Add Contact Email",
          "validation": {
            "required": true,
            "format": "email"
          }
        }
      ]
    }
  }
}

As noted in the edit section above, the code, created_at, and updated_at are not included, these will be generated by the system at the point of submission. The system field has also been removed as this does not relate to user created catalogue templates.

Also in this example, the user has set enabled to true, which would make this template available to all data owners after it has been successfully submitted.