Skip to main content Link Menu Expand (external link) Document Search Copy Copied
Metadata Spreadsheet Validator Documentation

Here is some information to help you understand the basic functions of the RESTful API, including making requests, reading responses, and potential errors.

Base URL: https://api.metadatavalidator.metadatacenter.org/

Validate Spreadsheet

To validate a spreadsheet, you create a list of MetadataRecord objects which represents each row in the spreadsheet, and a link to a CEDAR template by adding the template IRI that you can get from browsing the CEDAR template repository.

POST /service/validate
Example cURL:
curl --request POST \
  --url https://api.metadatavalidator.metadatacenter.org/service/validate \
  --header 'Content-Type: application/json' \
  --data '{
    "spreadsheetData": [
      {
        "sample_id": "Visium_9OLC_I4_S2",
        "source_storage_time_value": 208,
        "source_storage_time_unit": "day",
        "preparation_medium": "Methanol (100%)",
        "preparation_condition": "Ice",
        "processing_time_value": 4,
        "processing_time_unit": "minute",
        "storage_medium": "OCT embedded",
        "storage_condition": "-80 celsius freezer",
        "quality_criteria": "",
        "histological_report": "",
        "thickness_value": 10,
        "thickness_unit": "millimeter",
        "section_index_number": 3,
        "area_value": 15.84,
        "area_unit": "square millimeter",
        "notes": ""
      },
      {
        "sample_id": "",
        "source_storage_time_value": "86 days",
        "source_storage_time_unit": "days",
        "preparation_medium": "Formalin",
        "preparation_condition": "",
        "processing_time_value": "10 minutes",
        "processing_time_unit": "minutes",
        "storage_medium": "Paraffin embedded",
        "storage_condition": "Liquid nitrogen",
        "quality_criteria": "",
        "histological_report": 12.05,
        "thickness_value": 10,
        "thickness_unit": "mm",
        "section_index_number": 1,
        "area_value": 12.05,
        "area_unit": "mm^2",
        "notes": ""
      },
      {
        "sample_id": "",
        "source_storage_time_value": "86 days",
        "source_storage_time_unit": "days",
        "preparation_medium": "Formalin",
        "preparation_condition": "",
        "processing_time_value": "10 minutes",
        "processing_time_unit": "minutes",
        "storage_medium": "Paraffin embedded",
        "storage_condition": "Liquid nitrogen",
        "quality_criteria": "",
        "histological_report": 15.84,
        "thickness_value": 10,
        "thickness_unit": "mm",
        "section_index_number": 2,
        "area_value": 15.84,
        "area_unit": "mm^2",
        "notes": ""
      }
    ],
    "cedarTemplateIri": "https://repo.metadatacenter.org/templates/a9efb30e-4e2c-4d66-8890-b66204a4a774"
  }'

This API call expects an input in JSON format, and you need to inform the server that you are sending a JSON-formatted payload. To do that you must include the Content-Type: application/json HTTP header with every call.

Variable Name Value When to send it
Content-Type application/json MUST be sent with every call.

Body Schema

The input object that needs to be sent to the validation server.

{
  "spreadsheetData": [ MetadataRecord ],
  "cedarTemplateIri": "string"
}
Attribute Name Type Description
spreadsheetData [ MetadataRecord ] The metadata records.
cedarTemplateIri string The CEDAR Template IRI that provides the metadata specification.

Details on MetadataRecord type

This object represents a row in the spreadsheet.

{
  column1: Any,
  column2: Any,
  column3: Any,
  ...
}
Attribute Name Type Description
column1, column2, …, columnN Any The column value. (Note: the variables column1, column2, …, columnN shall be replaced by the actual column names in the spreadsheet).

Response Schema

The response object that the validation server will send you back if the call is a success.

{
  "schema": Schema,
  "data": [ OrderedMetadataRecord ],
  "reporting": [ ErrorReport ]
}
Attribute Name Type Description
schema Schema The metadata specification object.
data [ OrderedMetadataRecord ] The metadata records.
reporting [ ErrorReport ] The error reports generated by the validator algorithm.

Details on Schema type

This object represents the overview of the metadata specification schema.

{
  "name": "string",
  "columnDescription": ColumnDescription,
  "columnOrder": [ "string" ],
  "generatedFrom": "string"
}
Attribute Name Type Description
name string The name of the metadata specification (i.e., CEDAR template name).
columnDescription ColumnDescription The column description as mentioned in the metadata specification.
columnOrder [ string ] The column order as it appears in the metadata specification.
generatedFrom string The CEDAR template IRI which links to the metadata specification.

Details on ColumnDescription type

This object represents a collection of column definitions that the server has extracted from reading the CEDAR template.

{
  "column1": ColumnSchema,
  "column2": ColumnSchema,
  "column3": ColumnSchema,
  ...
}
Attribute Name Type Description
column1, column2, …, columnN ColumnSchema The column specification. (Note: the variables column1, column2, …, columnN shall be replaced by the actual column names in the spreadsheet).

Details on ColumnSchema type

This object represents the details of the column definition.

{
  "name": "string",
  "label": "string",
  "type": "string",
  "subType": "string",
  "min": 0,
  "max": 0,
  "required": true,
  "description": "string",
  "permissibleValues: [ PermissibleValue ]
}
Attribute Name Type Description
name string The column’s variable name.
label string The column’s label.
type string The column’s value type (possible values: “string”, “number”).
subType string The column’s value sub-type (possible values: “decimal”, “integer”).
min number The minimum number constraint (used only when type = “number”).
max number The maximum number constraint (used only when type = “number”).
required boolean Whether the column must have a value or not.
description string The column’s description.
permissibleValues [ PermissibleValue ] A list of values that can be used to fill out the column.

Details on PermissibleValue type

This object represents a pair of term label and term IRI from a source ontology.

{
  "label": "string",
  "meaning": "string"
}
Attribute Name Type Description
label string The term’s label found on the rdfs:label property in an ontology.
meaning string The term’s IRI found in an ontology.

Details on OrderedMetadataRecord type

This object represents a row in the spreadsheet but with an extra rowNumber attribute to make clear the row indexing.

{
  rowNumber: number,
  column1: Any,
  column2: Any,
  column3: Any,
  ...
}
Attribute Name Type Description
rowNumber number The order number of the metadata record in the spreadsheet (start from 0).
column1, column2, …, columnN Any The column value. (Note: the variables column1, column2, …, columnN shall be replaced by the actual column names in the spreadsheet).

Details on ErrorReport type

This object represents the error details detected by the validator’s algorithm.

{
  "errorType": "string",
  "column": "string",
  "row": 0,
  "value": Any
  "repairSuggestion": Any,
}
Attribute Name Type Description
errorType string The type of error (possible values: “missingRequired”, “notStandardTerm”, “notNumberType”, “notStringType”, “numberOutOfRange”).
column string The column name (not label).
row number The row index number (start from 0).
value Any The original value from spreadsheet.
repairSuggestion Any The new value suggested by the validator’s algorithm.

Response Code

The HTTP status code used by the RESTful Validate API.

Code Description
200 Success.
400 The request could not be understood by the server due to malformed syntax in the request body.
500 The server encountered an unexpected condition that prevented it from fulfilling the request.