# D4D Rubric10 - Ten-Element Hierarchical Evaluation Rubric
# Schema Version: 2.1
# Last Updated: 2026-01-12

# =============================================================================
# FIELD REFERENCE GUIDE
# =============================================================================
# Use these exact field names when evaluating D4D files against the schema.
# The D4D schema uses a class-based structure, not dot-notation.
#
# Discovery & Access:
#   - id: Unique identifier (URI)
#   - doi: Digital Object Identifier
#   - rrid: Research Resource Identifier
#   - title: Dataset title
#   - description: Dataset description
#   - keywords: Search keywords (list)
#   - download_url: Download URL
#   - page: Landing page URL
#   - distribution_formats: DistributionFormat (list)
#
# Licensing & Governance:
#   - license_and_use_terms: LicenseAndUseTerms class
#   - ip_restrictions: IPRestrictions class
#   - regulatory_restrictions: ExportControlRegulatoryRestrictions class
#   - confidentiality_level: ConfidentialityLevelEnum
#
# Human Subjects:
#   - human_subject_research: HumanSubjectResearch class
#   - informed_consent: InformedConsent (list)
#   - participant_privacy: ParticipantPrivacy (list)
#   - participant_compensation: HumanSubjectCompensation class
#   - vulnerable_populations: VulnerablePopulations class
#   - ethical_reviews: EthicalReview (list)
#
# Data Composition:
#   - instances: Instance (list)
#   - variables: VariableMetadata (list)
#   - subpopulations: Subpopulation (list)
#   - is_tabular: Boolean
#   - is_deidentified: Deidentification class
#
# Data Quality:
#   - anomalies: DataAnomaly (list)
#   - known_biases: DatasetBias (list)
#   - known_limitations: DatasetLimitation (list)
#
# Use Guidance:
#   - intended_uses: IntendedUse (list)
#   - prohibited_uses: ProhibitedUse (list)
#   - discouraged_uses: DiscouragedUse (list)
#   - existing_uses: ExistingUse (list)
#
# Hierarchical Structure:
#   - resources: Dataset (list) - nested sub-resources
#   - parent_datasets: Dataset (list) - parent datasets
#   - related_datasets: DatasetRelationship (list) - typed relationships
#
# Funding & Motivation:
#   - purposes: Purpose (list)
#   - tasks: Task (list)
#   - funders: FundingMechanism (list)
#   - creators: Creator (list)
#
# Technical Methods:
#   - collection_mechanisms: CollectionMechanism (list)
#   - acquisition_methods: DataAcquisition (list)
#   - preprocessing_strategies: PreprocessingStrategy (list)
#   - cleaning_strategies: CleaningStrategy (list)
#   - labeling_strategies: LabelingStrategy (list)
#   - software_and_tools: Software (list)
#
# Versioning & Maintenance:
#   - version: Version string
#   - version_access: VersionAccess class
#   - updates: UpdatePlan class
#   - errata: Erratum (list)
#   - maintainers: Maintainer (list)
#   - was_derived_from: Source provenance
#   - release_notes: Release documentation
#
# Distribution:
#   - format: File format specification
#   - media_type: MIME type
#   - encoding: Character encoding
#   - bytes: File size in bytes
#   - conforms_to: Standards conformance
#   - conforms_to_schema: Schema conformance
#
# Other:
#   - publisher: Publishing organization
#   - citation: Recommended citation
#   - external_resources: ExternalResource (list)
#   - sensitive_elements: Sensitive content description
#   - content_warnings: Content warnings
#
# Data Protection & Compliance:
#   - data_protection_impacts: DataProtectionImpact (list)
#   - reidentification_risk: Re-identification risk assessment
#   - hipaa_compliant: ComplianceStatusEnum
#   - other_compliance: Other regulatory frameworks (list)
#   - governance_committee_contact: Governance committee contact person
#
# Responsible AI (CROISSANT RAI Alignment):
#   - future_use_impacts: FutureUseImpact (rai:dataSocialImpact) - Social impact analysis
#   - intended_uses: IntendedUse (rai:dataUseCases) - Explicit intended uses
#   - known_biases: DatasetBias (rai:dataBiases) - Categorized with BiasTypeEnum
#
# Data Quality & Documentation:
#   - missing_data_documentation: MissingDataDocumentation (list)
#   - annotation_analyses: AnnotationAnalysis (list)
#   - machine_annotation_tools: MachineAnnotationTool (list)
#   - raw_data_sources: RawDataSource (list)
#   - imputation_protocols: ImputationProtocol (list)
#
# Dataset Structure Flags:
#   - is_data_split: Boolean - Training/test split flag
#   - is_subpopulation: Boolean - Subpopulation subset flag
#   - confidential_elements: Confidentiality (list)
#
# Provenance (W3C PROV-O):
#   - was_derived_from: Source provenance with entity-activity-agent relationships
#   - Note: Provenance may be represented as text OR as W3C PROV-O graphs
#
# AI/ML Readiness (Bridge2AI):
#   - Reference: Bridge2AI AI-readiness characterization criteria
#   - Tool: Bridge2AI AI-readiness scorecard
#
# Data Sustainability:
#   - Persistent identifiers (DOI, ARK, Handle)
#   - Long-term governance plan
#   - Domain-appropriate repository
#   - Institutional commitment documentation
#
# Integration/Merging Capability:
#   - Common identifiers for cross-dataset integration
#   - Standardized formats for data harmonization
#   - Integration procedure documentation
# =============================================================================

d4d_complex_proxy_rubric:
  schema_version: "2.0"
  description: >
    Ten-element hierarchical rubric for evaluating D4D YAML completeness and usability.
    Each element represents a complex metadata-driven goal and includes up to five measurable
    sub-elements. Scores can be computed at the element or sub-element level.

  scoring_scale:
    element: 0–5
    sub_element: [0, 1]  # 0 = not present/fail, 1 = present/pass

  rubric:
    # ---------------------------------------------------- #
    - id: 1
      name: "Dataset Discovery and Identification"
      description: "Can a user or system discover and uniquely identify this dataset?"
      sub_elements:
        - name: "Persistent Identifier (DOI, RRID, or URI)"
          field: ["doi", "rrid", "id"]
        - name: "Dataset Title and Description Completeness"
          field: ["title", "description"]
        - name: "Keywords or Tags for Searchability"
          field: ["keywords"]
        - name: "Landing Page and Resources (page, hierarchical resources)"
          field: ["page", "resources"]
        - name: "Hierarchical Structure (parent datasets, relationships)"
          field: ["parent_datasets", "related_datasets"]
      scoring_method: "Sum of sub_element presence / 5"

    # ---------------------------------------------------- #
    - id: 2
      name: "Dataset Access and Retrieval"
      description: "Can the dataset and its associated resources be located, accessed, and downloaded?"
      sub_elements:
        - name: "Access Policy and IP Restrictions Defined"
          field: ["license_and_use_terms", "ip_restrictions"]
        - name: "Regulatory Compliance and Confidentiality Classification"
          field: ["regulatory_restrictions", "confidentiality_level", "hipaa_compliant", "other_compliance", "governance_committee_contact"]
        - name: "Download URL or Platform Link Available"
          field: ["download_url"]
        - name: "Distribution Formats and File Types Specified"
          field: ["distribution_formats", "format", "media_type"]
        - name: "Related Datasets and External Resources Linked"
          field: ["related_datasets", "external_resources"]
      scoring_method: "Sum of sub_element presence / 5"

    # ---------------------------------------------------- #
    - id: 3
      name: "Data Reuse and Interoperability"
      description: >
        Is sufficient information provided to reuse and integrate the dataset with others?

        Note: Evaluate whether the dataset is designed for integration with similar datasets,
        including: common identifiers for cross-dataset linking, standardized formats for data
        harmonization, and documented integration procedures.
      sub_elements:
        - name: "License Terms Allow Reuse"
          field: ["license_and_use_terms"]
        - name: "Data Formats Are Standardized (encoding, format)"
          field: ["format", "encoding"]
        - name: "Schema or Ontology Conformance Stated"
          field: ["conforms_to", "conforms_to_schema"]
        - name: "Variable Metadata with Identifiers Defined"
          field: ["variables"]
        - name: "Use Guidance Provided (intended, prohibited uses)"
          field: ["intended_uses", "prohibited_uses", "discouraged_uses"]
      scoring_method: "Sum of sub_element presence / 5"

    # ---------------------------------------------------- #
    - id: 4
      name: "Ethical Use and Privacy Safeguards"
      description: "Does the dataset provide clear information about consent, privacy, and ethical oversight?"
      sub_elements:
        - name: "IRB or Ethics Review and Data Protection Impact"
          field: ["ethical_reviews", "human_subject_research", "data_protection_impacts"]
        - name: "Deidentification Method Described"
          field: ["is_deidentified"]
        - name: "Privacy Protections and Re-identification Risk Assessment"
          field: ["participant_privacy", "reidentification_risk"]
        - name: "Informed Consent Obtained from Participants"
          field: ["informed_consent"]
        - name: "Vulnerable Populations and Compensation Documented"
          field: ["vulnerable_populations", "participant_compensation"]
      scoring_method: "Sum of sub_element presence / 5"

    # ---------------------------------------------------- #
    - id: 5
      name: "Data Composition and Structure"
      description: "Can the dataset's structure, modality, and population be understood from metadata?"
      sub_elements:
        - name: "Cohort or Subpopulations Characteristics Described"
          field: ["subpopulations"]
        - name: "Number of Instances or Samples Reported"
          field: ["instances"]
        - name: "Variable-Level Metadata, Tabular Flag, and Data Splits"
          field: ["variables", "is_tabular", "is_data_split", "is_subpopulation"]
        - name: "Data Topics or Conditions Represented"
          field: ["instances"]
        - name: "Data Quality, Anomalies, and Missing Data Documented"
          field: ["anomalies", "sampling_strategies", "missing_data_documentation"]
      scoring_method: "Sum of sub_element presence / 5"

    # ---------------------------------------------------- #
    - id: 6
      name: "Data Provenance and Version Tracking"
      description: "Can a user determine dataset versions, update history, and provenance?"
      sub_elements:
        - name: "Dataset Version Number Provided"
          field: ["version"]
        - name: "Version Access Methods Documented"
          field: ["version_access"]
        - name: "Change Descriptions and Errata Provided"
          field: ["errata", "updates"]
        - name: "Update Schedule or Frequency Indicated"
          field: ["updates"]
        - name: "Provenance, Source Derivation, and Raw Data Sources"
          field: ["was_derived_from", "release_notes", "raw_data_sources"]
      scoring_method: "Sum of sub_element presence / 5"

    # ---------------------------------------------------- #
    - id: 7
      name: "Scientific Motivation and Funding Transparency"
      description: "Does the metadata clearly state why the dataset exists and who funded it?"
      sub_elements:
        - name: "Motivation or Purpose for Dataset Creation"
          field: ["purposes"]
        - name: "Primary Research Objectives or Tasks"
          field: ["tasks"]
        - name: "Funding Sources and Mechanisms Listed"
          field: ["funders"]
        - name: "Grant IDs or Award Numbers Present"
          field: ["funders"]
        - name: "Creators and Acknowledgements Documented"
          field: ["creators", "funders"]
      scoring_method: "Sum of sub_element presence / 5"

    # ---------------------------------------------------- #
    - id: 8
      name: "Technical Transparency (Data Collection and Processing)"
      description: >
        Can data collection and processing steps be replicated or understood?

        Note: Preprocessing and collection metadata may be represented as structured text
        descriptions OR as machine-readable provenance graphs (e.g., W3C PROV-O, workflow graphs).
        Evaluation should check for: (1) structured text descriptions OR (2) graph representations
        with entity-activity-agent relationships. Both formats are acceptable.
      sub_elements:
        - name: "Collection Mechanisms and Settings Described"
          field: ["collection_mechanisms"]
        - name: "Data Acquisition Methods Listed"
          field: ["acquisition_methods"]
        - name: "Preprocessing, Cleaning, Labeling, and Annotation Quality"
          field: ["preprocessing_strategies", "cleaning_strategies", "labeling_strategies", "annotation_analyses", "machine_annotation_tools"]
        - name: "Software and Tools Documented"
          field: ["software_and_tools"]
        - name: "External Standards, Resources, and Imputation Protocols"
          field: ["external_resources", "conforms_to", "imputation_protocols"]
      scoring_method: "Sum of sub_element presence / 5"

    # ---------------------------------------------------- #
    - id: 9
      name: "Dataset Evaluation and Limitations Disclosure"
      description: "Does the metadata communicate known risks, biases, or dataset limitations?"
      sub_elements:
        - name: "Known Limitations Documented"
          field: ["known_limitations"]
        - name: "Biases Categorized Using Standard Taxonomy (RAI-aligned)"
          field: ["known_biases"]
        - name: "Data Anomalies and Quality Issues Noted"
          field: ["anomalies"]
        - name: "Sensitive Content and Warnings Provided"
          field: ["sensitive_elements", "content_warnings"]
        - name: "Ethical Review and Social Impact Analysis"
          field: ["ethical_reviews", "future_use_impacts"]
      scoring_method: "Sum of sub_element presence / 5"

    # ---------------------------------------------------- #
    - id: 10
      name: "Cross-Platform and Community Integration"
      description: >
        Does the dataset connect to wider data ecosystems, repositories, or standards?

        Note: For Bridge2AI datasets, citation metadata is mandatory and should include:
        (1) formatted citation string, (2) DOI, and (3) citation instructions. Hosting
        platform identification should specify the publisher or repository (e.g., PhysioNet,
        Dataverse, institutional repositories).
      sub_elements:
        - name: "Dataset Published on a Recognized Platform"
          field: ["publisher"]
        - name: "Citation and DOI for Cross-referencing"
          field: ["citation", "doi"]
        - name: "Community Standards or Schema Conformance"
          field: ["conforms_to"]
        - name: "Outreach Materials and Documentation Links"
          field: ["external_resources", "page"]
        - name: "Related Datasets with Typed Relationships"
          field: ["related_datasets"]
      scoring_method: "Sum of sub_element presence / 5"
