API documentation

This section documents the rocrate_validator package’s API. The rocrate_validator package provides tools for managing validation profiles, for using them to validate RO-Crate metadata, and for interpreting the results. Below, you will find descriptions and usage examples for the core services, models, and other components provided by the package.

The Python API is structured in three main parts.

Core Services: functions for validating RO-Crate metadata and managing profiles.
Core Models: classes representing the main entities used in the validation process.
Python Check API: classes and decorators for defining Python-based validation checks.

Each section includes detailed information about the available functions, classes, and their members.

Core Services

RO-Crate validation

rocrate_validator.services.validate(settings: dict | ValidationSettings, subscribers: list[Subscriber] | None = None) → ValidationResult[source]

Validate a RO-Crate against a profile and return the validation result

Parameters:

settings (Union[dict, ValidationSettings]) – the validation settings
subscribers (Optional[list[Subscriber]]) – the list of subscribers

Returns:

the validation result

Return type:

ValidationResult

RO-Crate profiles

rocrate_validator.services.get_profiles(profiles_path: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/rocrate-validator/checkouts/develop/rocrate_validator/profiles'), extra_profiles_path: Path | None = None, severity=Severity.OPTIONAL, allow_requirement_check_override: bool = True) → list[Profile][source]

Get the list of profiles supported by the package. The profile source path can be overridden by specifying profiles_path.

Parameters:

profiles_path (Path) – the path to the profiles directory
severity (Severity) – the severity level
allow_requirement_check_override (bool) – a flag to enable or disable the requirement check override (default: True). If True, the requirement check of a profile A can be overridden by the requirement check of a profile extension B (i.e., when B extends A) if they share the same name. If False, a profile extension B can only add new requirements to the profile A (i.e., checks with name not present in A) and an error is raised if a check with the same name is found in both profiles.

Returns:

the list of profiles

Return type:

list[Profile]

rocrate_validator.services.get_profile(profile_identifier: str, profiles_path: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/rocrate-validator/checkouts/develop/rocrate_validator/profiles'), extra_profiles_path: Path | None = None, severity=Severity.OPTIONAL, allow_requirement_check_override: bool = True) → Profile[source]

Get the profile with the given identifier. The profile source path can be overridden through profiles_path. The profile is loaded based on the given severity level and the requirement check override flag.

Parameters:

profile_identifier (str) – the profile identifier
profiles_path (Path) – the path to the profiles directory
severity (Severity) – the severity level
allow_requirement_check_override (bool) – a flag to enable or disable the requirement check override (default: True). If True, the requirement check of a profile A can be overridden by the requirement check of a profile extension B (i.e., when B extends A) if they share the same name. If False, a profile extension B can only add new requirements to the profile A (i.e., checks with name not present in A) and an error is raised if a check with the same name is found in both profiles.

Returns:

the profile

Return type:

Profile

Core Models

The validator’s core is built on the main set of classes shown in the following diagram:

RO-Crate

class rocrate_validator.models.ROCrate(uri: str | Path | URI, relative_root_path: Path | None = None)[source]

Base class for representing and interacting with a Research Object Crate (RO-Crate).

property uri: URI: The URI of the RO-Crate.

property metadata: ROCrateMetadata

An ROCrateMetadata object representing the RO-Crate metadata.

Returns:: the metadata object
Return type:: ROCrateMetadata

abstract size() → int[source]

The size of the RO-Crate.

Returns:: the size of the RO-Crate
Return type:: int

abstract property list_files: list[Path]

List all the files in the RO-Crate.

Returns:: a list of file paths
Return type:: list[Path]

has_descriptor() → bool[source]

Check if the RO-Crate has a metadata descriptor file.

Returns:: True if the RO-Crate has a metadata descriptor file, False otherwise
Return type:: bool

has_file(path: Path) → bool[source]

Check if the RO-Crate has a file.

Parameters:: path (Path) – the path to the file
Returns:: True if the RO-Crate has the file, False otherwise
Return type:: bool

has_directory(path: Path) → bool[source]

Check if the RO-Crate has a directory.

Parameters:: path (Path) – the path to the directory
Returns:: True if the RO-Crate has the directory, False otherwise
Return type:: bool

abstract get_file_size(path: Path) → int[source]

Get the size of a file in the RO-Crate.

Parameters:: path (Path) – the path to the file
Returns:: the size of the file
Return type:: int

abstract get_file_content(path: Path, binary_mode: bool = True) → str | bytes[source]

Get the content of a file in the RO-Crate.

Parameters:

path (Path) – the path to the file
binary_mode (bool) – if True, return the file as a bytes object; otherwise, return it as a str

Returns:

the content of the file

Return type:

Union[str, bytes]

static get_external_file_content(uri: str, binary_mode: bool = True) → str | bytes[source]

Get the content of an external file.

Parameters:

uri (str) – the URI of the file
binary_mode (bool) – if True, return the file as a bytes object; otherwise, return it as a str

Returns:

the content of the file

Return type:

Union[str, bytes]

static get_external_file_size(uri: str) → int[source]

Get the size of an external file.

Parameters:: uri (str) – the URI of the file
Returns:: the size of the file
Return type:: int
Raises:: requests.HTTPError – if the request fails

static from_metadata_dict(metadata_dict: dict) → ROCrate[source]

Create a new instance of the RO-Crate based on the metadata dictionary.

Parameters:: metadata_dict (dict) – the metadata dictionary
Raises:: ROCrateInvalidURIError – if the URI is invalid

static new_instance(uri: str | Path | URI, relative_root_path: Path | None = None) → ROCrate[source]

Create a new instance of the RO-Crate based on the URI.

Parameters:: uri (Union[str, Path, URI]) – the URI of the RO-Crate
Returns:: a new instance of the RO-Crate
Return type:: ROCrate
Raises:: ROCrateInvalidURIError – if the URI is invalid

Profiles, Requirements, and Checks

class rocrate_validator.models.Profile(profiles_base_path: Path, profile_path: Path, requirements: list[Requirement] | None = None, identifier: str | None = None, publicID: str | None = None, severity: Severity = Severity.REQUIRED)[source]

RO-Crate Validator profile.

A profile is a named set of requirements that can be used to validate an RO-Crate.

property overrides: list[Profile]: The list of profiles that override this profile.

property overridden_by: list[Profile]: The list of profiles that are overridden by this profile.

property path: The path of the profile directory

property identifier: str: The identifier of the profile.

property name: The name of the profile as specified in the profile specification file (i.e., the value of the rdfs: label property in the profile.ttl file) or a default name if the label is not specified.

property profile_specification_graph: Graph: The RDF graph of the profile specification.

property token: A token that uniquely identifies the profile as specified in the profile specification file (i.e., the value of the prof: hasToken property in the profile.ttl file).

property uri: The URI of the profile.

property comment: The comment added to the profile in the profile specification file (i.e., the value of the rdfs: comment property in the profile.ttl file).

property version: The version of the profile as specified in the profile specification file (i.e., the value of the prof: version property in the profile.ttl file).

property is_profile_of: list[str]: The list of profiles that this profile is a profile of as specified in the profile specification file (i.e., the value of the prof: isProfileOf property in the profile.ttl file).

property is_transitive_profile_of: list[str]: The list of profiles that this profile is a transitive profile of as specified in the profile specification file (i.e., the value of the prof: isTransitiveProfileOf property in the profile.ttl file).

property parents: list[Profile]: The list of profiles that this profile is a profile of as specified in the profile specification file.

property siblings: list[Profile]: The list of profiles that are siblings of this profile (i.e., profiles that share the same parent profile).

property descendants: list[Profile]: The list of profiles that are descendants of this profile (i.e., profiles that have this profile among their inherited profiles).

property readme_file_path: Path: The path of the README file of the profile.

property profile_specification_file_path: Path: The path of the profile specification file.

property severity: Severity: The severity of the profile which the profile is loaded with, i.e., the minimum severity level of the requirements of the profile.

property description: str: The description of the profile as specified in the profile specification file (i.e., the value of the rdfs: comment property in the profile.ttl file).

property requirements: list[Requirement]: The list of requirements of the profile.

get_requirements(severity: Severity = Severity.REQUIRED, exact_match: bool = False) → list[Requirement][source]: Get the requirements of the profile with the given severity level. If the exact_match flag is set to True, only the requirements with the exact severity level are returned; otherwise, the requirements with severity level greater than or equal to the given severity level are returned.

get_requirement(name: str) → Requirement | None[source]: Get the requirement with the given name

get_requirement_check(check_name: str) → RequirementCheck | None[source]: Get the requirement check with the given name

classmethod get_by_identifier(identifier: str) → Profile[source]

Get the profile with the given identifier

Parameters:: identifier (str) – the identifier
Returns:: the profile
Return type:: Profile

classmethod get_by_uri(uri: str) → Profile[source]

Get the profile with the given URI

Parameters:: uri (str) – the URI
Returns:: the profile
Return type:: Profile

classmethod get_by_name(name: str) → list[Profile][source]

Get the profile with the given name

Parameters:: name (str) – the name
Returns:: the profile
Return type:: Profile

classmethod get_by_token(token: str) → Profile[source]

Get the profile with the given token

Parameters:: token (str) – the token
Returns:: the profile
Return type:: Profile

classmethod get_sibling_profiles(profile: Profile) → list[Profile][source]

Get the sibling profiles of the given profile

Parameters:: profile (Profile) – the profile
Returns:: the list of sibling profiles
Return type:: list[Profile]

classmethod get_descendants(profile: Profile) → list[Profile][source]

Get the transitive descendants of the given profile (any profile that has profile among its inherited_profiles).

Parameters:: profile (Profile) – the profile
Returns:: the list of descendant profiles
Return type:: list[Profile]

classmethod all() → list[Profile][source]

Get all the profiles

Returns:: the list of profiles
Return type:: list[Profile]

classmethod find_in_list(profiles: Collection[Profile], profile_identifier: str) → Profile | None[source]

Find a profile with the given identifier in the given list of profiles

Parameters:

profiles (Collection[Profile]) – the list of profiles
identifier (str) – the identifier

Returns:

the profile if found, None otherwise

Return type:

Optional[Profile]

class rocrate_validator.models.Requirement(profile: Profile, name: str = '', description: str | None = None, path: Path | None = None, initialize_checks: bool = True)[source]

Bases: ABC

Abstract class representing a requirement of a profile. A requirement is a named set of checks that can be used to validate an RO-Crate.

__init__(profile: Profile, name: str = '', description: str | None = None, path: Path | None = None, initialize_checks: bool = True)[source]

Initialize the Requirement instance

property order_number: int

The order number of the requirement in the profile

Returns:: the order number
Return type:: int

property identifier: str

The identifier of the requirement

Returns:: the identifier
Return type:: str

__eq__(other: object) → bool[source]: Return self==value.

__ne__(other: object) → bool[source]: Return self!=value.

__hash__()[source]: Return hash(self).

__lt__(other: object) → bool[source]: Return self<value.

__repr__()[source]: Return repr(self).

__str__() → str[source]: Return str(self).

__ge__(other, NotImplemented=NotImplemented): Return a >= b. Computed by @total_ordering from (not a < b).

__gt__(other, NotImplemented=NotImplemented): Return a > b. Computed by @total_ordering from (not a < b) and (a != b).

__le__(other, NotImplemented=NotImplemented): Return a <= b. Computed by @total_ordering from (a < b) or (a == b).

__weakref__: list of weak references to the object (if defined)

class rocrate_validator.models.RequirementCheck(requirement: Requirement, name: str, level: RequirementLevel | None = RequirementLevel(name=REQUIRED, severity=Severity.REQUIRED), description: str | None = None, hidden: bool | None = None, deactivated: bool = False)[source]

get_source_snippet() → SourceSnippet | None[source]: Return the source code that implements this check, or None if the backing source cannot be extracted for this check kind. Concrete subclasses should override this method.

Severity

enum rocrate_validator.models.Severity(value)[source]

Enum ordering “strength” of conditions to be verified

Valid values are as follows:

OPTIONAL = <Severity.OPTIONAL: 0>: the condition is not mandatory

RECOMMENDED = <Severity.RECOMMENDED: 2>: the condition is recommended

REQUIRED = <Severity.REQUIRED: 4>: the condition is mandatory

class rocrate_validator.models.RequirementLevel(name: str, severity: Severity)[source]

Represents a requirement level.

A requirement has a name and a severity level of type Severity. It implements the comparison operators to allow ordering of the requirement levels.

class rocrate_validator.models.LevelCollection[source]

Collection of RequirementLevel instances.

Provides a set of predefined RequirementLevel instances that can be used to define the severity of a requirement. They map the keywords defined in RFC 2119 to the corresponding severity levels.

Note

The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in RFC 2119.

OPTIONAL = RequirementLevel(name=OPTIONAL, severity=Severity.OPTIONAL): The requirement level OPTIONAL is mapped to the OPTIONAL severity level

MAY = RequirementLevel(name=MAY, severity=Severity.OPTIONAL): The requirement level MAY is mapped to the OPTIONAL severity level

REQUIRED = RequirementLevel(name=REQUIRED, severity=Severity.REQUIRED): The requirement level REQUIRED is mapped to the REQUIRED severity level

SHOULD = RequirementLevel(name=SHOULD, severity=Severity.RECOMMENDED): The requirement level SHOULD is mapped to the RECOMMENDED severity level

SHOULD_NOT = RequirementLevel(name=SHOULD_NOT, severity=Severity.RECOMMENDED): The requirement level SHOULD NOT is mapped to the RECOMMENDED severity level

RECOMMENDED = RequirementLevel(name=RECOMMENDED, severity=Severity.RECOMMENDED): The requirement level RECOMMENDED is mapped to the RECOMMENDED severity level

MUST = RequirementLevel(name=MUST, severity=Severity.REQUIRED): The requirement level MUST is mapped to the REQUIRED severity level

MUST_NOT = RequirementLevel(name=MUST_NOT, severity=Severity.REQUIRED): The requirement level MUST_NOT is mapped to the REQUIRED severity level

SHALL = RequirementLevel(name=SHALL, severity=Severity.REQUIRED): The requirement level SHALL is mapped to the REQUIRED severity level

SHALL_NOT = RequirementLevel(name=SHALL_NOT, severity=Severity.REQUIRED): The requirement level SHALL_NOT is mapped to the REQUIRED severity level

Validation

class rocrate_validator.models.ValidationSettings(rocrate_uri: ~rocrate_validator.utils.uri.URI = <property object>, rocrate_relative_root_path: ~pathlib.Path | None = None, profiles_path: ~pathlib.Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/rocrate-validator/checkouts/develop/rocrate_validator/profiles'), extra_profiles_path: ~pathlib.Path | None = None, profile_identifier: str = 'ro-crate-1.1', enable_profile_inheritance: bool = True, abort_on_first: bool | None = False, disable_inherited_profiles_issue_reporting: bool = False, disable_remote_crate_download: bool = True, requirement_severity: str | ~rocrate_validator.models.Severity = Severity.REQUIRED, requirement_severity_only: bool = False, allow_requirement_check_override: bool = True, disable_check_for_duplicates: bool = False, skip_checks: list[str] | None = None, metadata_only: bool = False, metadata_dict: dict | None = None, verbose: bool = False, cache_max_age: int | None = -1, cache_path: ~pathlib.Path | None = None, offline: bool = False, no_cache: bool = False)[source]

Represents the settings for RO-Crate validation.

It includes the following attributes:

rocrate_relative_root_path: Path | None = None: The relative root path of the RO-Crate

profiles_path: Path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/rocrate-validator/checkouts/develop/rocrate_validator/profiles'): The path to the profiles

extra_profiles_path: Path | None = None: The path to the extra profiles

profile_identifier: str = 'ro-crate-1.1': The profile identifier to validate against

abort_on_first: bool | None = False: Flag to abort on first error

disable_inherited_profiles_issue_reporting: bool = False: Flag to disable reporting of issues related to inherited profiles

disable_remote_crate_download: bool = True: Flag to disable remote crate download

requirement_severity: str | Severity = 4: The requirement severity

requirement_severity_only: bool = False: Flag to validate requirement severity only skipping check with lower or higher severity

allow_requirement_check_override: bool = True: Flag to allow requirement check override

disable_check_for_duplicates: bool = False: Flag to disable the check for duplicates

skip_checks: list[str] = None: Checks to skip

metadata_only: bool = False: Flag to validate only the metadata of the RO-Crate

metadata_dict: dict = None: RO-Crate metadata as dictionary

verbose: bool = False: Verbose output

cache_max_age: int | None = -1: Cache max age in seconds (negative values mean “never expire”)

cache_path: Path | None = None: Cache path

offline: bool = False: Flag to enable offline mode: HTTP requests are served only from the cache

no_cache: bool = False: Flag to disable the HTTP cache entirely: every request hits the network

to_dict()[source]: Convert the ValidationSettings to a dictionary

property rocrate_uri: URI | None: The URI of the RO-Crate

classmethod parse(settings: dict | ValidationSettings) → ValidationSettings[source]

Parse the settings to a ValidationSettings object.

Parameters:: settings (Union[dict, ValidationSettings]) – The settings to parse.
Returns:: The parsed settings.
Return type:: ValidationSettings
Raises:: ValueError – If the settings type is invalid.

class rocrate_validator.models.ValidationContext(validator: Validator, settings: ValidationSettings)[source]

Class that represents the context for the validation process.

property ro_crate: ROCrate

The RO-Crate instance

Returns:: The RO-Crate instance
Return type:: ROCrate

property validator: Validator

The validator instance which this context belongs to

Returns:: The validator instance
Return type:: Validator

property result: ValidationResult

The validation result

Returns:: The validation result
Return type:: ValidationResult

property settings: ValidationSettings

The validation settings

Returns:: The validation settings
Return type:: ValidationSettings

property publicID: str: The root URI of the RO-Crate

property profiles_path: Path

The path to the profiles

Returns:: The path to the profiles
Return type:: Path

property extra_profiles_path: Path | None

The path to the extra profiles

Returns:: The path to the extra profiles
Return type:: Optional[Path]

property requirement_severity: Severity

The requirement severity to validate against

Returns:: The requirement severity
Return type:: Severity

property requirement_severity_only: bool

Flag to validate requirement severity only skipping check with lower or higher severity

Returns:: The flag to validate requirement severity only
Return type:: bool

property rocrate_uri: URI

The URI of the RO-Crate

Returns:: The URI of the RO-Crate
Return type:: Path

property fail_fast: bool

Flag to abort on first error

Returns:: The flag to abort on first error
Return type:: bool

property rel_fd_path: Path

The relative path to the file descriptor

Returns:: The relative path to the file descriptor
Return type:: Path

get_data_graph(refresh: bool = False) → Graph[source]

Utility method to get the data graph of the RO-Crate, i.e., the metadata of the RO-Crate as an RDF graph.

Parameters:: refresh (bool) – Flag to refresh the data graph
Returns:: The data graph of the RO-Crate
Return type:: :py:class:rdflib.Graph
Raises:: ROCrateMetadataNotFoundError – If the RO-Crate metadata is not found

property data_graph: Graph

The data graph of the RO-Crate, i.e., the metadata of the RO-Crate as an RDF graph.

Returns:: The data graph of the RO-Crate
Return type:: Graph

property inheritance_enabled: bool

Flag which indicates if profile inheritance is enabled

Returns:: The flag to enable profile inheritance
Return type:: bool

property profile_identifier: str

The profile identifier to validate against

Returns:: The profile identifier
Return type:: str

property allow_requirement_check_override: bool

Flag that indicates if requirement check override is allowed

Returns:: The flag to allow requirement check override
Return type:: bool

property disable_check_for_duplicates: bool

Flag that indicates if the check for duplicates is disabled

Returns:: The flag to disable the check for duplicates
Return type:: bool

property profiles: list[Profile]

The profiles to validate against, i.e., the target profile and its inherited profiles

Returns:: The profiles to validate against
Return type:: list[Profile]

property target_validation_profile: Profile

The target validation profile to validate against

Returns:: The target validation profile
Return type:: Profile

property target_profile: Profile

The target profile to validate against

Returns:: The target profile
Return type:: Profile

get_profile_by_token(token: str) → list[Profile][source]

Get the profile by token from the profiles to validate against

Parameters:: token (str) – The token of the profile
Returns:: The profile with the given token
Return type:: Profile

get_profile_by_identifier(identifier: str) → list[Profile][source]

Get the profile by identifier from the profiles to validate against

Parameters:: identifier (str) – The identifier of the profile
Returns:: The profile with the given identifier
Return type:: Profile

maybe_warn_offline_cache_miss(exc: BaseException) → bool[source]

If exc (or any cause/context in its chain) is an OfflineCacheMissError, emit a single user-facing warning for the missing URL — but only the first time that URL is seen during this validation run — and return True.

Returns False when the exception is unrelated to offline cache misses, so callers can fall back to their generic handling.

class rocrate_validator.models.ValidationResult(context: ValidationContext)[source]

Represents the result of a validation.

Parameters:

context (ValidationContext) – The validation context
rocrate_uri (str) – The URI of the RO-Crate
validation_settings (ValidationSettings) – The validation settings
issues (list[CheckIssue]) – The issues found during the validation

property context: ValidationContext: The validation context

property rocrate_uri: The URI of the RO-Crate

property validation_settings: The validation settings

property statistics: ValidationStatistics: The validation statistics

property executed_checks: set[RequirementCheck]: The checks that have been executed

get_executed_check_result(check: RequirementCheck) → bool | None[source]: Get the result of an executed check

property skipped_checks: set[RequirementCheck]: The checks that have been skipped

property issues: list[CheckIssue]: The issues found during the validation

get_issues(min_severity: Severity | None = None) → list[CheckIssue][source]: Get the issues found during the validation with a severity greater than or equal to min_severity

get_issues_by_check(check: RequirementCheck, min_severity: Severity | None = None) → list[CheckIssue][source]: Get the issues found during the validation for a specific check with a severity greater than or equal to min_severity

has_issues(min_severity: Severity | None = None) → bool[source]: Check if there are issues with a severity greater than or equal to the given severity

passed(min_severity: Severity | None = None) → bool[source]: Check if all checks passed with a severity greater than or equal to the given severity

add_issue(message: str, check: RequirementCheck, violatingEntity: str | None = None, violatingProperty: str | None = None, violatingPropertyValue: str | None = None) → CheckIssue[source]

Add an issue to the validation result

Parameters:: message(str): The message of the issue check(RequirementCheck): The check that generated the issue violatingEntity(Optional[str]): The entity that caused the issue (if any) violatingProperty(Optional[str]): The property that caused the issue (if any) violatingPropertyValue(Optional[str]): The value of the violatingProperty (if any)

property failed_requirements: Collection[Requirement]: Get the requirements that failed at or above the configured requirement_severity.

property failed_checks: Collection[RequirementCheck]: Get the checks that failed at or above the configured requirement_severity.

get_failed_checks_by_requirement(requirement: Requirement) → Collection[RequirementCheck][source]: Get the checks that failed for a specific requirement

get_failed_checks_by_requirement_and_severity(requirement: Requirement, severity: Severity) → Collection[RequirementCheck][source]: Get the checks that failed for a specific requirement and severity

to_dict() → dict[source]: Convert the ValidationResult to a dictionary

to_json(path: Path | None = None) → str[source]: Convert the ValidationResult to a JSON string

class rocrate_validator.models.CheckIssue(check: RequirementCheck, message: str | None = None, violatingProperty: str | None = None, violatingEntity: str | None = None, value: str | None = None)[source]

Represents an issue with a check that has been executed during the validation process.

property message: str | None: The message associated with the issue

property level: RequirementLevel: The level of the issue

property severity: Severity: Severity of the RequirementLevel associated with this check.

property check: RequirementCheck: The check that generated the issue

property violatingEntity: str | None: It represents the specific element being evaluated that fails to meet the defined rules or constraints within a validation process. Also referred to as focusNode in SHACL terminology in the context of an RDF graph, it is the subject of a triple that violates a given constraint on the subject’s property/predicate, represented by the violatingProperty.

property violatingProperty: str | None: It refers to the specific property or relationship within an item that leads to a validation failure. It identifies the part of the data structure that is causing the issue. Also referred to as resultPath in SHACL terminology, in the context of an RDF graph, it is the predicate of a triple that violates a given constraint on the subject’s property/predicate, represented by the violatingProperty.

property violatingPropertyValue: str | None: It represents the value of the violatingProperty that leads to a validation failure.

class rocrate_validator.events.Event(event_type: EventType, message: str | None = None)[source]: Base class for representing events

enum rocrate_validator.events.EventType(value)[source]

Event types

Valid values are as follows:

VALIDATION_START = <EventType.VALIDATION_START: 0>: Validation start

VALIDATION_END = <EventType.VALIDATION_END: 1>: Validation end

PROFILE_VALIDATION_START = <EventType.PROFILE_VALIDATION_START: 2>: Profile validation start

PROFILE_VALIDATION_END = <EventType.PROFILE_VALIDATION_END: 3>: Profile validation end

REQUIREMENT_VALIDATION_START = <EventType.REQUIREMENT_VALIDATION_START: 4>: Requirement validation start

REQUIREMENT_VALIDATION_END = <EventType.REQUIREMENT_VALIDATION_END: 5>: Requirement validation end

REQUIREMENT_CHECK_VALIDATION_START = <EventType.REQUIREMENT_CHECK_VALIDATION_START: 6>: Requirement check validation start

REQUIREMENT_CHECK_VALIDATION_END = <EventType.REQUIREMENT_CHECK_VALIDATION_END: 7>: Requirement check validation end

class rocrate_validator.events.Subscriber(name)[source]

Subscriber interface. Objects that want to be notified of events generated during the validation process should implement this interface.

abstract update(event: Event, ctx: Any | None = None)[source]

Update the subscriber with the event

Parameters:

event (Event) – the event
ctx (Optional[Any]) – optional context

Errors

exception rocrate_validator.errors.ROCValidatorError[source]

exception rocrate_validator.errors.ProfilesDirectoryNotFound(profiles_path: str | None = None)[source]

Raised when the profiles directory is not found.

property profiles_path: str | None: The path to the profiles directory.

exception rocrate_validator.errors.InvalidProfilePath(profile_path: str | None = None)[source]

Raised when an invalid profile path is provided.

property profile_path: str | None: The invalid profile path.

exception rocrate_validator.errors.ProfileNotFound(profile_name: str | None = None, message: str | None = None)[source]

Raised when a profile is not found.

property profile_name: str | None: The name of the profile.

property message: str | None: The error message.

exception rocrate_validator.errors.ProfileSpecificationNotFound(spec_file: str | None = None)[source]

Raised when the profile specification is not found.

property spec_file: str | None: The name of the profile specification file.

exception rocrate_validator.errors.ProfileSpecificationError(message: str | None = None)[source]

Raised when an error occurs in the profile specification.

property message: str | None: The error message.

exception rocrate_validator.errors.DuplicateRequirementCheck(check_name: str, profile_name: str | None = None)[source]

Raised when a duplicate requirement check is found.

property check_name: str: The name of the duplicate requirement check.

property profile_name: str | None: The name of the profile.

exception rocrate_validator.errors.InvalidSerializationFormat(format: str | None = None)[source]

Raised when an invalid serialization format is provided.

property serialization_format: str | None: The invalid serialization format.

exception rocrate_validator.errors.BadSyntaxError(message, path: str = '.', code: int = -1)[source]

Raised when a syntax error occurs.

property message: str: The error message.

property path: str: The path where the error occurred.

property code: int: The error code.

exception rocrate_validator.errors.ValidationError(message, path: str = '.', code: int = -1)[source]

Raised when a validation error occurs.

property message: str: The error message.

property path: str: The path where the error occurred.

property code: int: The error code.

exception rocrate_validator.errors.CheckValidationError(check, message, path: str = '.', code: int = -1)[source]

Raised when a validation check fails.

property check: The check that failed.

exception rocrate_validator.errors.ROCrateInvalidURIError(uri: str | Path | URI, message: str | None = None)[source]

Raised when an invalid URI is provided.

property uri: str | Path | URI: The invalid URI, as originally provided (str, Path, or URI).

property uri_string: str: The invalid URI normalised to its string form.

property message: str: The error message.

exception rocrate_validator.errors.ROCrateMetadataNotFoundError(message: str | None = None, path: str | None = None)[source]

Raised when the RO-Crate metadata is not found.

property message: str | None: The error message.

property path: str | None: The path where the error occurred.

Python Check API

Requirement Class

class rocrate_validator.requirements.python.PyRequirement(profile: Profile, requirement_check_class: Type[PyFunctionCheck], name: str = '', description: str | None = None, path: Path | None = None)[source]

A base class for requirements that are implemented as Python classes.

This class is used to define a requirement that is implemented as a Python class.

The class is a subclass of rocrate_validator.models.Requirement.

Class instances are automatically initialized by the validator providing the profile, the requirement class, the name, the description, and the path to the file that contains the requirement check class within the profile directory.

The class is expected to have a docstring that provides a description of the requirement, even if the description can be provided through the requirement() decorator.

The class should define one or more methods that are decorated with the check() decorator.

Decorators

rocrate_validator.requirements.python.requirement(name: str, description: str | None = None, hidden: bool = False)[source]

A decorator to mark a class as a requirement class.

The decorator can be used to set the name and description of the requirement.

Parameters:

name (str) – the name of the requirement
description (Optional[str]) – the description of the requirement
hidden (bool) – a flag to indicate if the requirement should not be displayed in the list of requirements

Returns:

the decorated class

rocrate_validator.requirements.python.check(name: str | None = None, severity: Severity | None = None, deactivated: bool = False)[source]

A decorator to mark a function as a check.

The function should accept two arguments:

a rocrate_validator.models.RequirementCheck instance
a rocrate_validator.models.ValidationContext instance

The function should return a boolean value.

The decorator can be used to set the name of the check and the severity level.

Parameters:

name (Optional[str]) – the name of the check
severity (Optional[Severity]) – the severity level
deactivated (bool) – when True, the check is skipped during validation. Mirrors SHACL’s sh:deactivated: an extension profile may redeclare a check with the same name as one in a parent profile and set this flag to disable the inherited check.

Returns:

the decorated function

Return type:

Callable