Schema Reference Documentation

Overview

The Psych-DS schema defines the structure, rules, and validation requirements for psychological and behavioral science datasets. This reference documentation is generated from our LinkML schema model.

What is LinkML?

LinkML (Linked data Modeling Language) is a flexible modeling language for describing structured data. It provides:

• A human-readable YAML syntax for defining data models
• Machine-readable schemas that can validate data
• Integration with semantic web standards
• Tools for generating documentation and code

For Psych-DS, LinkML enables us to:

1. Define precise rules for dataset organization
2. Generate validation tools that reference a central source of ground truth
3. Generate reference documents automatically
4. Support machine-readable metadata

Reference Structure

The schema reference is organized into three main sections:

Meta

Field Definitions

Definitions and specifications for fields and properties that can be used across different objects and rules in the schema. This includes:

• Data types like JSON-LD
• File naming elements like suffix and extension
• Rules to be associated with objects like columsnMatchMetadata and fileRegex

Objects

Core Components

Definitions of key Psych-DS concepts and structures:

• Dataset components such as:
  • Metadata files
  • Data directory
  • Data files
  • Optional directories and files such as READMEs and analysis directories
• Relevant concepts such as "column", "dataset", and "inheritance"

Rules

Rules, Errors, and Warnings

Definitions of errors and warnings that occur during validation, as well as specifications of which rules (as defined in Meta) apply to which objects (as defined in Objects). These include:

• General errors such as:
  • INVALID_JSON_FORMATTING
  • CSV_FORMATTING_ERROR
• Object-specific errors such as:
  • MISSING_DATA_DIRECTORY
  • MISSING_DATASET_DESCRIPTION
• Warnings such as:
  • UNKNOWN_NAMESPACE
  • UNOFFICIAL_KEYWORD_WARNING
  • INVALID_SCHEMAORG_PROPERTY
• Object classes such as:
  • dataset_description with its fields:
    • stem and its value dataset_description
    • extension and its value .json
  • Datafile with its fields:
    • columnsMatchMetadata and its value true
    • fileRegex and its value ([a-z]+-[a-zA-Z0-9]+)(_[a-z]+-[a-zA-Z0-9]+)*_data\.csv