Validation rules (v0.2)

The profile’s machine-checkable rules are published as SHACL: fairscape-shapes.ttl (shapes version 0.2.0). Run them with:

pip install 'fairscape-models[shacl]'

from fairscape_models.validation.shacl import validate_shacl

report = validate_shacl("./my-crate")  # crate dir, metadata file, dict or ROCrateV1_2
report.passes      # True iff there are no Violations; Warnings are advisory
report.results     # severity, shape, message, focusNode, path

Any SHACL engine (e.g. pyshacl -s fairscape-shapes.ttl ro-crate-metadata.json) gives the same results.

Graph rules

These rules check how entities link to each other, which the per-entity JSON Schemas cannot express. A Violation is raised only when this file alone proves the defect. When a flagged reference could legitimately point into a sibling crate of a release, the rule is a Warning. Edge rules match both the schema: and evi: expansions of each key, and skip targets that have no @type in this crate.

Reference edges point at a node of the right type

Severity: Violation — fails conformance · Applies to: the whole graph, once · Shape: fsh:ProvenanceEdgeTypingShape

Edge	Target, when described in this crate, must be
dataSchema	evi:Schema
generated, derivedFrom	not an Activity — the data entity, never the process
generatedBy	Activity (Computation/Experiment/Activity)
usedByComputation	evi:Computation
usedByExperiment	evi:Experiment
usedDataset, trainedOn	evi:Dataset
usedInstrument	evi:Instrument
usedMLModel	evi:MLModel
usedSample	evi:Sample
usedSoftware	evi:Software

SPARQL

SELECT $this ?subj ?value WHERE {
?subj evi:Schema ?value .
FILTER EXISTS { ?value rdf:type ?t } FILTER NOT EXISTS { ?value rdf:type evi:Schema } }

SELECT $this ?subj ?value WHERE {
?subj ( schema:generated | evi:generated | schema:derivedFrom | evi:derivedFrom ) ?value .
?value rdf:type ?at .
FILTER( STRENDS(STR(?at),"Computation") || STRENDS(STR(?at),"Experiment") || STRENDS(STR(?at),"Activity") ) }

SELECT $this ?subj ?value WHERE {
?subj ( schema:generatedBy | evi:generatedBy ) ?value .
FILTER EXISTS { ?value rdf:type ?t }
FILTER NOT EXISTS { ?value rdf:type ?at .
    FILTER( STRENDS(STR(?at),"Computation") || STRENDS(STR(?at),"Experiment") || STRENDS(STR(?at),"Activity") ) } }

SELECT $this ?subj ?value WHERE {
?subj ( schema:usedByComputation | evi:usedByComputation ) ?value .
FILTER EXISTS { ?value rdf:type ?t } FILTER NOT EXISTS { ?value rdf:type evi:Computation } }

SELECT $this ?subj ?value WHERE {
?subj ( schema:usedByExperiment | evi:usedByExperiment ) ?value .
FILTER EXISTS { ?value rdf:type ?t } FILTER NOT EXISTS { ?value rdf:type evi:Experiment } }

SELECT $this ?subj ?value WHERE {
?subj ( schema:usedDataset | evi:usedDataset | schema:trainedOn | evi:trainedOn ) ?value .
FILTER EXISTS { ?value rdf:type ?t } FILTER NOT EXISTS { ?value rdf:type evi:Dataset } }

SELECT $this ?subj ?value WHERE {
?subj ( schema:usedInstrument | evi:usedInstrument ) ?value .
FILTER EXISTS { ?value rdf:type ?t } FILTER NOT EXISTS { ?value rdf:type evi:Instrument } }

SELECT $this ?subj ?value WHERE {
?subj ( schema:usedMLModel | evi:usedMLModel ) ?value .
FILTER EXISTS { ?value rdf:type ?t } FILTER NOT EXISTS { ?value rdf:type evi:MLModel } }

SELECT $this ?subj ?value WHERE {
?subj ( schema:usedSample | evi:usedSample ) ?value .
FILTER EXISTS { ?value rdf:type ?t } FILTER NOT EXISTS { ?value rdf:type evi:Sample } }

SELECT $this ?subj ?value WHERE {
?subj ( schema:usedSoftware | evi:usedSoftware ) ?value .
FILTER EXISTS { ?value rdf:type ?t } FILTER NOT EXISTS { ?value rdf:type evi:Software } }

ark: references should resolve within this crate (else warn)

Severity: Warning — reported, crate still conforms · Applies to: the whole graph, once · Shape: fsh:DanglingReferenceShape

• N ark: reference(s) point to a node not described in this crate. Expected for a release/nested crate that links sibling crates; if this crate should be self-contained, they are broken links.

SPARQL

SELECT $this ( COUNT( DISTINCT ?value ) AS ?n ) WHERE {
    ?subj ?p ?value .
    FILTER( isIRI(?value) && STRSTARTS(STR(?value), "ark:") )
    FILTER NOT EXISTS { ?value rdf:type ?anyType }
}
GROUP BY $this
HAVING ( COUNT( DISTINCT ?value ) > 0 )

ARK identifiers are well-formed (ark:NNNNN/…)

Severity: Warning — reported, crate still conforms · Applies to: the whole graph, once · Shape: fsh:ArkIdentifierFormatShape

• Malformed ARK identifier Y (expected ark:NNNNN/name, no spaces or commas). A trailing comma is the usual culprit.

SPARQL

SELECT $this ?value WHERE {
    ?value ?p ?o .
    FILTER( isIRI(?value) && STRSTARTS(STR(?value), "ark:") )
    FILTER( ! REGEX(STR(?value), "^ark:[0-9]{5}/[^ ,]+$") )
}

A Dataset must name an author

Severity: Violation — fails conformance · Applies to: every evi:Dataset node · Shape: fsh:DatasetAuthorShape

• author: required — a name (xsd:string) or an @id reference

Per-class structure

One shape per entity type, generated from the fairscape_models Pydantic classes (the same source as the JSON Schemas). All are open shapes: properties not listed are allowed. Card. is the allowed number of values (0..1, 1..1, 0..*, 1..*).

ROCrateMetadataElem

Applies to every evi:ROCrate node.

Property	Path	Status	Card.	Value	Constraints	Description
description	schema:description	required	1..1	xsd:string		A human-readable description of the dataset.
name	schema:name	required	1..1	xsd:string		A human-readable name for the dataset.
version	schema:version	required	1..1	xsd:string		Version string for this release of the dataset (e.g. ‘1.0’, ‘2.3.1’).
completeness	schema:completeness	optional	0..1	xsd:string		Assessment of how complete the dataset is relative to its intended scope (e.g. percentage of expected records present, known gaps).
conditionsOfAccess	schema:conditionsOfAccess	optional	0..1	xsd:string		Terms and conditions governing access to and use of this dataset, including any data use agreements required.
confidentialityLevel	schema:confidentialityLevel	optional	0..1	xsd:string		HL7 Confidentiality code indicating the level of confidentiality or sensitivity of the dataset (e.g. ‘normal’, ‘restricted’, ‘very restricted’).
contactEmail	schema:contactEmail	optional	0..1	xsd:string		Email address for questions or correspondence about the dataset.
contentSize	schema:contentSize	optional	0..1	xsd:string		Total size of the dataset content (e.g. ‘2.4 GB’, ‘150 MB’). Used in AI-Ready Characterization scoring.
copyrightNotice	schema:copyrightNotice	optional	0..1	xsd:string		Copyright statement for the dataset, including year and rights holder.
d4d:contentWarning	<d4d:contentWarning>	optional	0..1	xsd:string		Does the dataset contain any data that might be offensive, insulting, threatening, or otherwise anxiety-provoking if viewed directly? (D4D_Composition: ContentWarning)
d4d:informedConsent	<d4d:informedConsent>	optional	0..1	xsd:string		Details about informed consent procedures used in human subjects research — consent type, documentation, withdrawal mechanisms, and scope. (D4D_Human: InformedConsent)
dataGovernanceCommittee	schema:dataGovernanceCommittee	optional	0..1	any		Name or contact for the data governance committee responsible for oversight, access control, and policy enforcement for this dataset. Accepts a plain name string, a reference stub, or an inline Person.
datePublished	schema:datePublished	optional	0..1	xsd:string		Date the dataset was published or made publicly available (ISO 8601).
deidentified	schema:deidentified	optional	0..1	any		Whether the dataset has been de-identified to remove or obscure personally identifiable information.
ethicalReview	schema:ethicalReview	optional	0..1	xsd:string		Were any ethical or compliance review processes conducted (e.g. by an Institutional Review Board)? If so, describe the process, frequency of review, and outcomes. Or provide a contact for ethical review information.
evi:computationCount	evi:computationCount	optional	0..1	any		Pre-aggregated count of Computation and Experiment entities across all sub-crates. Used in AI-Ready Provenance scoring.
evi:datasetCount	evi:datasetCount	optional	0..1	any		Pre-aggregated count of Dataset entities across all sub-crates. Used in AI-Ready Provenance scoring in place of counting entities at query time.
evi:entitiesWithChecksums	evi:entitiesWithChecksums	optional	0..1	any		Pre-aggregated count of entities that have md5, sha256, or hash set. Used with evi:totalEntities to compute checksum coverage percentage.
evi:entitiesWithSummaryStats	evi:entitiesWithSummaryStats	optional	0..1	any		Pre-aggregated count of entities that have hasSummaryStatistics set. Used in AI-Ready Characterization scoring.
evi:formats	evi:formats	optional	0..*	xsd:string		Pre-aggregated list of unique file format values (up to 5) across all entities. Used in AI-Ready Computability scoring.
evi:processed	evi:processed	optional	0..1	any		Flag indicating whether this release-level RO-Crate has been processed and aggregated metrics computed.
evi:schemaCount	evi:schemaCount	optional	0..1	any		Pre-aggregated count of Schema entities across all sub-crates. Used in AI-Ready Characterization scoring.
evi:softwareCount	evi:softwareCount	optional	0..1	any		Pre-aggregated count of Software entities across all sub-crates. Used in AI-Ready Provenance scoring.
evi:totalContentSizeBytes	evi:totalContentSizeBytes	optional	0..1	any		Pre-aggregated total content size in bytes across all sub-crate datasets. Used in AI-Ready Characterization scoring.
evi:totalEntities	evi:totalEntities	optional	0..1	any		Pre-aggregated total count of Dataset and Software entities. Used as denominator for checksum coverage in AI-Ready Pre-Model Explainability scoring.
fdaRegulated	schema:fdaRegulated	optional	0..1	any		Whether this dataset is subject to FDA regulations (e.g. clinical trial data, medical device data).
hash	schema:hash	optional	0..1	xsd:string		Hash of the digital object content (if not MD5)
hasPart	schema:hasPart	optional	0..*	@id reference		Dataset, Software, Computation, and other entities that are part of this RO-Crate, referenced by identifier.
hasSummaryStatistics	schema:hasSummaryStatistics	optional	0..1	any		Reference to a summary statistics entity describing distributions, counts, and key statistics for this dataset.
humanSubjectExemption	schema:humanSubjectExemption	optional	0..1	xsd:string		If human subjects research qualifies for exemption from full IRB review, the applicable exemption category (e.g. 45 CFR 46 Exemption 4).
humanSubjectResearch	schema:humanSubjectResearch	optional	0..1	xsd:string		Does this dataset involve human subjects? Indicate Yes/No and describe the nature of human subjects involvement.
identifier	schema:identifier	optional	0..1	xsd:string		DOI or other external persistent identifier for the dataset (used for Findability and Sustainability scoring).
irb	schema:irb	optional	0..1	any		Institutional Review Board (IRB) information — approval status, approving institution, and contact details.
irbProtocolId	schema:irbProtocolId	optional	0..1	xsd:string		IRB protocol identifier number assigned by the reviewing institution.
isPartOf	schema:isPartOf	optional	0..*	@id reference		Parent organization(s) or project(s) this crate belongs to, referenced by identifier.
keywords	schema:keywords	optional	0..*	xsd:string		Keywords or tags describing the dataset, used for discovery and search.
license	schema:license	optional	0..1	xsd:string		Will the dataset be distributed under a copyright or other IP license? Provide a link to or copy of the license terms (e.g. CC BY 4.0, MIT).
md5	schema:md5	optional	0..1	xsd:string		MD5 checksum of the digital object content
principalInvestigator	schema:principalInvestigator	optional	0..1	any		A key individual (Principal Investigator) responsible for or overseeing dataset creation. Accepts a plain name string, a reference stub ({“@id”: ”…”}) to a Person in @graph, or an inline Person object.
prohibitedUses	schema:prohibitedUses	optional	0..1	xsd:string		Explicit statement of prohibited or forbidden uses for this dataset — uses that are not permitted by license, ethics, or policy. Stronger than discouraged uses.
publisher	schema:publisher	optional	0..1	xsd:string		Organization or person responsible for publishing or distributing the dataset.
rai:annotationsPerItem	rai:annotationsPerItem	optional	0..1	xsd:string		Number of annotations collected per data item. Multiple annotations per item enable calculation of inter-annotator agreement. (rai:annotationsPerItem)
rai:dataAnnotationProtocol	rai:dataAnnotationProtocol	optional	0..1	xsd:string		Annotation methodology, tasks, and protocols followed during labeling. Includes annotation guidelines, quality control procedures, task definitions, workforce type, annotation characteristics, and label distributions. (rai:dataAnnotationProtocol)
rai:dataCollection	rai:dataCollection	optional	0..1	xsd:string		What mechanisms or procedures were used to collect the data (e.g. hardware sensors, manual curation, software APIs)? Also covers how these mechanisms were validated. (rai:dataCollection)
rai:dataCollectionMissingData	rai:dataCollectionMissingData	optional	0..1	xsd:string		Documentation of missing data in the dataset, including patterns (e.g. MCAR, MAR, MNAR), known or suspected causes (e.g. sensor failures, participant dropout, privacy constraints), and strategies used to handle missing values. (rai:dataCollectionMissingData)
rai:dataCollectionRawData	rai:dataCollectionRawData	optional	0..1	xsd:string		Description of raw data sources before preprocessing, cleaning, or labeling. Documents where the original data comes from and how it can be accessed. (rai:dataCollectionRawData)
rai:dataImputationProtocol	rai:dataImputationProtocol	optional	0..1	xsd:string		Description of data imputation methodology, including techniques used to handle missing values (e.g. mean/median imputation, forward fill, model-based imputation) and rationale for chosen approaches. (rai:dataImputationProtocol)
rai:dataSocialImpact	rai:dataSocialImpact	optional	0..1	xsd:string		Is there anything about the dataset’s composition or collection that might impact future uses or create risks/harm (e.g. unfair treatment, legal or financial risks)? Describe potential impacts and any mitigation strategies. (rai:dataSocialImpact)
usageInfo	schema:usageInfo	optional	0..1	xsd:string		Additional usage information or instructions for working with this dataset.

ROCrateMetadataFileElem

Applies to every schema:CreativeWork node.

Property	Path	Status	Card.	Value	Constraints	Description
about	schema:about	required	1..1	@id reference
conformsTo	schema:conformsTo	required	1..1	@id reference

Dataset

Applies to every evi:Dataset node.

Property	Path	Status	Card.	Value	Constraints	Description
datePublished	schema:datePublished	required	1..1	xsd:string
description	schema:description	required	1..1	xsd:string	min length 10
format	schema:format	required	1..1	xsd:string
name	schema:name	required	1..1	xsd:string
additionalDocumentation	schema:additionalDocumentation	optional	0..1	xsd:string
columnCount	schema:columnCount	optional	0..1	any		Number of columns / fields for tabular datasets.
contentSize	schema:contentSize	optional	0..1	xsd:string		Total size of the dataset content (e.g. ‘2.4 GB’, ‘150 MB’).
derivedFrom	schema:derivedFrom	optional	0..*	@id reference
evi:Schema	evi:Schema	optional	0..1	@id reference
hasSummaryStatistics	schema:hasSummaryStatistics	optional	0..1	any		Reference to a summary statistics entity describing distributions, counts, and key statistics for this dataset.
isPartOf	schema:isPartOf	optional	0..*	@id reference
keywords	schema:keywords	optional	0..*	xsd:string
rowCount	schema:rowCount	optional	0..1	any		Number of rows / records for tabular datasets.
sampleSize	schema:sampleSize	optional	0..1	any		Number of samples represented by the dataset (often == rowCount for tabular data, but may differ).
usedByComputation	schema:usedByComputation	optional	0..*	@id reference
version	schema:version	optional	0..1	xsd:string

Software

Applies to every evi:Software node.

Property	Path	Status	Card.	Value	Constraints	Description
description	schema:description	required	1..1	xsd:string	min length 10
format	schema:format	required	1..1	xsd:string
name	schema:name	required	1..1	xsd:string
additionalDocumentation	schema:additionalDocumentation	optional	0..1	xsd:string
dateModified	schema:dateModified	optional	0..1	xsd:string
isPartOf	schema:isPartOf	optional	0..*	@id reference
usedByComputation	schema:usedByComputation	optional	0..*	@id reference
version	schema:version	optional	0..1	xsd:string

MLModel

Applies to every evi:MLModel node.

Property	Path	Status	Card.	Value	Constraints	Description
description	schema:description	required	1..1	xsd:string	min length 10
format	schema:format	required	1..1	xsd:string
name	schema:name	required	1..1	xsd:string
additionalDocumentation	schema:additionalDocumentation	optional	0..1	xsd:string
dateModified	schema:dateModified	optional	0..1	xsd:string
derivedFrom	schema:derivedFrom	optional	0..*	@id reference
isPartOf	schema:isPartOf	optional	0..*	@id reference
modelArchitecture	schema:modelArchitecture	optional	0..1	xsd:string
modelTask	schema:modelTask	optional	0..1	xsd:string
trainedOn	schema:trainedOn	optional	0..*	@id reference
usedByComputation	schema:usedByComputation	optional	0..*	@id reference
version	schema:version	optional	0..1	xsd:string

Computation

Applies to every evi:Computation node.

Property	Path	Status	Card.	Value	Constraints	Description
dateCreated	schema:dateCreated	required	1..1	xsd:string
description	schema:description	required	1..1	xsd:string	min length 10
name	schema:name	required	1..1	xsd:string
runBy	schema:runBy	required	1..1	any
additionalDocumentation	schema:additionalDocumentation	optional	0..1	xsd:string
associatedPublication	schema:associatedPublication	optional	0..1	xsd:string
evi:annotatedBy	evi:annotatedBy	optional	0..*	@id reference
generated	schema:generated	optional	0..*	@id reference
isPartOf	schema:isPartOf	optional	0..*	@id reference
usedDataset	schema:usedDataset	optional	0..*	@id reference
usedMLModel	schema:usedMLModel	optional	0..*	@id reference
usedSoftware	schema:usedSoftware	optional	0..*	@id reference

Experiment

Applies to every evi:Experiment node.

Property	Path	Status	Card.	Value	Constraints	Description
datePerformed	schema:datePerformed	required	1..1	xsd:string
description	schema:description	required	1..1	xsd:string	min length 10
experimentType	schema:experimentType	required	1..1	xsd:string
name	schema:name	required	1..1	xsd:string
runBy	schema:runBy	required	1..1	any
associatedPublication	schema:associatedPublication	optional	0..1	xsd:string
generated	schema:generated	optional	0..*	@id reference
isPartOf	schema:isPartOf	optional	0..*	@id reference
protocol	schema:protocol	optional	0..1	xsd:string
usedInstrument	schema:usedInstrument	optional	0..*	@id reference
usedSample	schema:usedSample	optional	0..*	@id reference
usedStain	schema:usedStain	optional	0..*	@id reference
usedTreatment	schema:usedTreatment	optional	0..*	@id reference

Schema

Applies to every evi:Schema node.

Property	Path	Status	Card.	Value	Constraints	Description
description	schema:description	required	1..1	xsd:string	min length 5
name	schema:name	required	1..1	xsd:string
properties	schema:properties	required	1..1	any
additionalProperties	schema:additionalProperties	optional	0..1	any
header	schema:header	optional	0..1	any
isPartOf	schema:isPartOf	optional	0..*	@id reference
keywords	schema:keywords	optional	0..*	xsd:string
license	schema:license	optional	0..1	xsd:string
published	schema:published	optional	0..1	any
required	schema:required	optional	0..*	xsd:string
separator	schema:separator	optional	0..1	xsd:string
type	schema:type	optional	0..1	xsd:string
url	schema:url	optional	0..1	any

Sample

Applies to every evi:Sample node.

Property	Path	Status	Card.	Value	Constraints	Description
description	schema:description	required	1..1	xsd:string	min length 1
name	schema:name	required	1..1	xsd:string
cellLineReference	schema:cellLineReference	optional	0..1	@id reference
isPartOf	schema:isPartOf	optional	0..*	@id reference
keywords	schema:keywords	optional	0..*	xsd:string

Instrument

Applies to every evi:Instrument node.

Property	Path	Status	Card.	Value	Constraints	Description
description	schema:description	required	1..1	xsd:string	min length 10
manufacturer	schema:manufacturer	required	1..1	xsd:string	min length 4
model	schema:model	required	1..1	xsd:string
name	schema:name	required	1..1	xsd:string
additionalDocumentation	schema:additionalDocumentation	optional	0..1	xsd:string
associatedPublication	schema:associatedPublication	optional	0..1	xsd:string
contentUrl	schema:contentUrl	optional	0..1	xsd:string
isPartOf	schema:isPartOf	optional	0..*	@id reference
usedByExperiment	schema:usedByExperiment	optional	0..*	@id reference

Annotation

Applies to every evi:Annotation node.

Property	Path	Status	Card.	Value	Constraints	Description
createdBy	schema:createdBy	required	1..1	any
dateCreated	schema:dateCreated	required	1..1	xsd:string
description	schema:description	required	1..1	xsd:string	min length 10
name	schema:name	required	1..1	xsd:string
associatedPublication	schema:associatedPublication	optional	0..1	xsd:string
generated	schema:generated	optional	0..*	@id reference
isPartOf	schema:isPartOf	optional	0..*	@id reference
usedDataset	schema:usedDataset	optional	0..*	@id reference

BioChemEntity

Applies to every evi:BioChemEntity node.

Property	Path	Status	Card.	Value	Constraints	Description
name	schema:name	required	1..1	xsd:string
associatedDisease	schema:associatedDisease	optional	0..1	@id reference
description	schema:description	optional	0..1	xsd:string
isPartOf	schema:isPartOf	optional	0..*	@id reference
usedBy	schema:usedBy	optional	0..*	@id reference

MedicalCondition

Applies to every schema:MedicalCondition node.

Property	Path	Status	Card.	Value	Constraints	Description
description	schema:description	required	1..1	xsd:string
name	schema:name	required	1..1	xsd:string
drug	schema:drug	optional	0..*	@id reference
isPartOf	schema:isPartOf	optional	0..*	@id reference
usedBy	schema:usedBy	optional	0..*	@id reference