Python API

Import Assessor from fair_offline_assessor. Choose an assessor once, then call assess() for each dataset.

Select an assessor

Assessor(name, version=...) chooses an assessor and a version included in the installed library.

Name
name
Type
str
Description
Assessor name: FUJI or FAIR_CHAMPION. Uppercase and lowercase are accepted.
Name
version
Type
str | None
Description
The version to use. This determines how the assessor maps metadata fields and which checks and scoring rules it applies. If omitted, the library uses its default: 3.5.1 for F-UJI, or 0.5.12 for Champion's FAIR Core Tests. An existing Assessor keeps its selected version across calls.

An unknown name or unavailable version raises ProfileError before the assessment starts. Its code explains which selection failed.

Use the default version

from fair_offline_assessor import Assessor

assessor = Assessor("FUJI")

Choose a specific version

assessor = Assessor("FUJI", version="3.5.1")

Assess a dataset

assessor.assess(...) runs the checks and returns an AssessmentResult. Pass arguments by name, as in the example.

Name
metadata
Type
dict | list[dict] | str
Description
The metadata to check. Supply a Python dictionary, a list of dictionaries, or the text of a document. The supported formats depend on the assessor; see F-UJI metadata or Champion metadata.
Name
metadata_format
Type
str | None
Description
The format of the supplied metadata. F-UJI defaults to json-ld; other options include datacite-json, xml, html, turtle and rdfxml. Pass the document's contents in metadata; the library does not open file paths or URLs for you. Champion accepts only the default JSON-LD format or explicit json-ld.
Name
subject
Type
str | None
Description
For F-UJI with JSON-LD or other RDF formats, the identifier of the dataset you expect it to assess. This verifies F-UJI's choice; it does not change the choice. If the choice cannot be confirmed, affected checks return indeterminate with subject_not_selected. Omit this argument for XML, DataCite JSON and HTML.
For Champion, selects the entire RDF graph containing that node's outgoing statements. It does not set the identifier being assessed. See Champion graph selection.
Name
metadata_url
Type
str | None
Description
The metadata document's original URL or identifier. In JSON-LD it provides the base for relative identifiers. F-UJI also uses it for identifier and protocol checks. Champion uses it as the metadata origin when checking outward links; its assessment target is separate. The library never opens this URL.
Name
target_identifier
Type
str | None
Description
For Champion, the identifier being assessed, such as 10.1234/example. It is not inferred from @id, subject or metadata_url. Missing or invalid targets leave dependent checks indeterminate; graph-only checks can still run. Omit this argument for F-UJI.
Name
local_contexts
Type
dict[str, dict] | None
Description
JSON-LD context documents: definitions of what field names mean. Dictionary keys are context URLs; values are the corresponding documents, each containing @context. The bundled Schema.org context works for both assessors. Other remote contexts must be supplied locally; they are never downloaded. See contexts for the argument format.

Use model_dump() to get a dictionary or model_dump_json() to get a JSON string.

Assess metadata

from fair_offline_assessor import Assessor

result = Assessor("FUJI", version="3.5.1").assess(
    metadata={
        "@context": "https://schema.org",
        "@type": "Dataset",
        "@id": "https://example.org/datasets/1",
        "name": "Example dataset",
        "license": "https://creativecommons.org/licenses/by/4.0/",
    }
)

print(result.coverage.model_dump_json(indent=2))

How many checks could run

{
  "evaluated": 15,
  "indeterminate": 16,
  "errors": 0,
  "not_applicable": 0,
  "total": 31
}

Save the result

from pathlib import Path

Path("assessment.json").write_text(
    result.model_dump_json(indent=2),
    encoding="utf-8",
)

result.diagnostics contains messages about invalid or unsupported metadata. Checks that cannot use that information remain indeterminate; other checks can still run. A missing field can cause a failure or an indeterminate result, depending on what the check requires.

Read each check's reason_code and message alongside the diagnostics. F-UJI troubleshooting lists common problems and fixes. For Champion, see input problems.

Select by profile

A profile is the stored configuration selecting an assessor's code and resources. The lower-level API accepts an exact id@version and either a dictionary or a typed input. It uses the same checks as Assessor:

from fair_offline_assessor import ChampionInput, assess, list_profiles

result = assess(
    ChampionInput(metadata={}, target_identifier="10.1234/example"),
    profile="fair-champion-offline@0.5.12",
)
print([f"{profile.id}@{profile.version}" for profile in list_profiles()])

F-UJI uses AssessmentInput and fusji-offline@3.5.1.