schema.json

{
    "meta": {
        "context": {
            "context": {
                "type": "object",
                "properties": {
                    "schema": {
                        "description": "The psych-DS schema",
                        "type": "object"
                    },
                    "dataset": {
                        "description": "Properties and contents of the entire dataset",
                        "type": "object",
                        "properties": {
                            "dataset_description": {
                                "description": "Contents of /dataset_description.json",
                                "type": "object"
                            },
                            "files": {
                                "description": "List of all files in dataset",
                                "type": "array"
                            },
                            "tree": {
                                "description": "Tree view of all files in dataset",
                                "type": "object"
                            },
                            "ignored": {
                                "description": "Set of ignored files",
                                "type": "array"
                            }
                        }
                    },
                    "path": {
                        "description": "Path of the current file",
                        "type": "string"
                    },
                    "suffix": {
                        "description": "Suffix of current file",
                        "type": "string"
                    },
                    "extension": {
                        "description": "Extension of current file including initial dot",
                        "type": "string"
                    },
                    "sidecar": {
                        "description": "Sidecar metadata constructed via the inheritance principle",
                        "type": "object"
                    },
                    "columns": {
                        "description": "TSV columns, indexed by column header, values are arrays with column contents",
                        "type": "object",
                        "additionalProperties": {
                            "type": "array"
                        }
                    },
                    "json": {
                        "description": "Contents of the current JSON file",
                        "type": "object"
                    },
                    "keywords": {
                        "description": "List of key-value pairings associated with the data file, derived from the filename",
                        "type": "array",
                        "properties": {
                            "study": {
                                "name": "Study",
                                "description": "Label designating a given study",
                                "type": "string"
                            },
                            "site": {
                                "name": "Site",
                                "description": "Label designating the site where the data was collected",
                                "type": "string"
                            },
                            "subject": {
                                "name": "Subject",
                                "description": "Label designating the subject corresponding to the data in the file",
                                "type": "string"
                            },
                            "session": {
                                "name": "Session",
                                "description": "Label designating a given session of the study",
                                "type": "string"
                            },
                            "task": {
                                "name": "Task",
                                "description": "Label designating the type of task in which the data was collected",
                                "type": "string"
                            },
                            "condition": {
                                "name": "Condition",
                                "description": "Label designating the condition under which the data was collected",
                                "type": "string"
                            },
                            "trial": {
                                "name": "Trial",
                                "description": "Label designating the trial associated with the data",
                                "type": "string"
                            },
                            "stimulus": {
                                "name": "Stimulus",
                                "description": "Label designating the stimulus item associated with the data",
                                "type": "string"
                            },
                            "description": {
                                "name": "Description",
                                "description": "Label describing the data file in question",
                                "type": "string"
                            }
                        }
                    }
                }
            }
        }
    },
    "objects": {
        "common_principles": {
            "dataset": {
                "name": "Dataset",
                "display_name": "Dataset",
                "description": "A set of behavioral data acquired for the purpose of a particular study or set of studies.\n"
            },
            "extension": {
                "name": "File extension",
                "display_name": "File extension",
                "description": "A portion of the file name after the left-most period (`.`) preceded by any other alphanumeric.\nFor example, `.gitignore` does not have a file extension,\nbut the file extension of 'study-1_data.csv' is '.csv'.\nNote that the left-most period is included in the file extension.\n"
            },
            "keywords": {
                "name": "Keywords",
                "display_name": "Keywords",
                "description": "A set of identifying key-value duples associated with a given data file.\nKeys are limited to a vocabulary of:\n  - study\n  - site\n  - subject\n  - session\n  - task\n  - condition\n  - trial\n  - stimulus\n  - description\n"
            }
        },
        "metadata": {
            "name": {
                "name": "name",
                "display_name": "Name",
                "description": "Name of the dataset.\n",
                "type": "string"
            },
            "schemaVersion": {
                "name": "schemaVersion",
                "display_name": "Schema Version",
                "description": "The version of the data specification that this dataset conforms to.\n",
                "type": "string"
            },
            "description": {
                "name": "description",
                "display_name": "Description",
                "description": "Detailed description of the dataset.\n",
                "type": "string"
            },
            "variableMeasured": {
                "name": "variableMeasured",
                "display_name": "Variable Measured",
                "description": "List of the column names that appear in the data files.\n",
                "type": "array"
            },
            "author": {
                "name": "author",
                "display_name": "Author",
                "description": "List of individuals who contributed to the creation/curation of the dataset.\n",
                "type": "array",
                "items": {
                    "type": "string"
                }
            },
            "citation": {
                "name": "citation",
                "display_name": "Citation",
                "description": "Citation data for referencing the dataset, or URL/path for structured citation file.\n",
                "type": "string"
            },
            "license": {
                "name": "license",
                "display_name": "Kucebse",
                "description": "Author-assigned 'license' for data/material use. While this can be a string of text, \na URL pointing to a specific license file (online or in the project directory) is preferred.\n",
                "type": "string"
            },
            "funder": {
                "name": "funder",
                "display_name": "Funder",
                "description": "List of sources of funding (grant numbers).\n",
                "type": "string"
            },
            "url": {
                "name": "url",
                "display_name": "URL",
                "description": "Canonical source for the dataset.\n",
                "type": "string"
            },
            "identifier": {
                "name": "identifier",
                "display_name": "Identifier",
                "description": "Identifier that uniquely distinguishes the dataset.\n",
                "type": "string"
            },
            "privacyPolicy": {
                "name": "privacyPolicy",
                "display_name": "Privacy Policy",
                "description": "A string to indicate whether any of the values in the dataset are desired to be shareable.\nThis does not guarantee that the dataset HAS been shared or HAS been de identified,.\n",
                "type": "string"
            },
            "keywords": {
                "name": "keywords",
                "display_name": "Keywords",
                "description": "Keywords with which to tag the dataset for reference.\n",
                "type": "array"
            }
        },
        "extensions": {
            "json": {
                "value": ".json",
                "display_name": "JavaScript Object Notation",
                "description": "A JSON file.\n\nTop-level and collated metadata files are all stored in the JSON format in psych-DS.\n"
            },
            "csv": {
                "value": ".csv",
                "display_name": "Comma-Separated Values",
                "description": "A CSV file with a header row of column names spanning all filled columns."
            }
        },
        "files": {
            "CHANGES": {
                "display_name": "Changelog",
                "file_type": "regular",
                "description": "Version history of the dataset (describing changes, updates and corrections) MAY be provided in\nthe form of a `CHANGES` text file. (.txt or .md).\n"
            },
            "README": {
                "display_name": "README",
                "file_type": "regular",
                "description": "File describing the dataset in detail. This is an OPTIONAL file, and only one README file should appear in dataset.\n"
            },
            "dataset_description": {
                "display_name": "Dataset Description",
                "file_type": "regular",
                "description": "The metadata file `dataset_description.json` is a JSON file describing the dataset.\n"
            },
            "analysis": {
                "display_name": "Analysis",
                "file_type": "directory",
                "description": "A directory in which to store any code used to analyze the data in /data.\n"
            },
            "results": {
                "display_name": "Results",
                "file_type": "directory",
                "description": "A directory in which to store any results generated using the data in /data.\n"
            },
            "materials": {
                "display_name": "Materials",
                "file_type": "directory",
                "description": "A directory in which to store any materials used to conduct the study.\n"
            },
            "documentation": {
                "display_name": "Documentation",
                "file_type": "directory",
                "description": "A directory in which to store any project-related documentation that is used for conducting the study (e.g. consent forms)\n"
            },
            "products": {
                "display_name": "Products",
                "file_type": "directory",
                "description": "A directory in which to store any Any relevant products resulting from the project \n(e.g., publications, posters, software descriptions, presentations, etc.) "
            }
        }
    },
    "rules": {
        "files": {
            "tabular_data": {
                "data": {
                    "Datafile": {
                        "selectors": [
                            "extension == \".csv\"",
                            "path.endswith(\"_data.csv\")"
                        ],
                        "additional_columns": "allowed_if_defined"
                    }
                }
            },
            "common": {
                "core": {
                    "dataset_description": {
                        "level": "required",
                        "path": "dataset_description.json"
                    },
                    "README": {
                        "level": "optional",
                        "stem": "README",
                        "extensions": [
                            ".md",
                            ".txt"
                        ]
                    },
                    "CHANGES": {
                        "level": "optional",
                        "path": "CHANGES"
                    },
                    "analysis": {
                        "level": "optional",
                        "path": "analysis"
                    },
                    "results": {
                        "level": "optional",
                        "path": "results"
                    },
                    "materials": {
                        "level": "optional",
                        "path": "materials"
                    },
                    "documentation": {
                        "level": "optional",
                        "path": "documentation"
                    }
                }
            }
        },
        "dataset_metadata": {
            "dataset_description": {
                "selectors": [
                    "path == \"/dataset_description.json\""
                ],
                "fields": {
                    "name": "required",
                    "schemaVersion": "required",
                    "description": "required",
                    "variableMeasured": "required",
                    "author": "recommended",
                    "citation": "recommended",
                    "license": "recommended",
                    "funder": "recommended",
                    "url": "recommended",
                    "identifier": "recommended",
                    "privacyPolicy": "recommended",
                    "keywords": "recommended"
                }
            }
        },
        "errors": {
            "JsonInvalid": {
                "code": "JSON_INVALID",
                "message": "Not a valid JSON file.\n",
                "level": "error",
                "selectors": [
                    "extension == \".json\""
                ]
            },
            "FileRead": {
                "code": "FILE_READ",
                "message": "We were unable to read this file.\nMake sure it contains data (file size > 0 kB) and is not corrupted,\nincorrectly named, or incorrectly symlinked.\n",
                "level": "error"
            },
            "JsonSchemaValidationError": {
                "code": "JSON_SCHEMA_VALIDATION_ERROR",
                "message": "Invalid JSON file. The file is not formatted according the schema.\n",
                "level": "error",
                "selectors": [
                    "extension == \".json\""
                ]
            },
            "EmptyFile": {
                "code": "EMPTY_FILE",
                "message": "Empty files not allowed.\n",
                "level": "error"
            },
            "InvalidJsonEncoding": {
                "code": "INVALID_JSON_ENCODING",
                "message": "JSON files must be valid utf-8.\n",
                "level": "error",
                "selectors": [
                    "extension == \".json\""
                ]
            }
        },
        "common_principles": [
            "dataset",
            "extension",
            "keywords"
        ]
    }
}