citeformer.csl

CSL-JSON schema validation helpers (§10.2 enforcement, opt-in).

Source.metadata is declared as dict[str, Any] so the pydantic model stays permissive — passing a malformed item through raises at render time with a formatter-level error rather than a schema violation. That’s pragmatic for exploratory usage, but strict downstream pipelines (academic publishing, compliance) want the schema policed up-front.

This module exposes:

• data:

  KNOWN_TYPES — the CSL 1.0 item types we recognise.

• data:

  KNOWN_FIELDS — the top-level field names we render; a superset of what any single style uses.

• func:

  validate_csl_json — pure-Python validator. Returns a

  class:

  ValidationReport; optionally raises :class:CSLValidationError on any failure.

• func:

  validate_source_metadata — thin wrapper that validates a Source.metadata directly and re-raises with a friendlier message.

The validator is strict by default: unknown top-level fields produce warnings (not errors). That’s a deliberate looseness — the CSL-JSON spec evolves, and we don’t want to block new fields like custom that downstream styles might rely on.

Module Contents

Classes

ValidationReport

Outcome of a CSL-JSON validation pass.

Functions

validate_csl_json	Validate a single CSL-JSON item against the §10.2 contract.
validate_source_metadata	Validate the metadata field of a :class:citeformer.Source.

Data

KNOWN_TYPES
KNOWN_FIELDS

API

exception citeformer.csl.CSLValidationError

Bases: ValueError

Raised when validate_csl_json(..., raise_on_error=True) hits a hard error.

Initialization

Initialize self. See help(type(self)) for accurate signature.

citeformer.csl.KNOWN_TYPES: frozenset[str]

‘frozenset(…)’

citeformer.csl.KNOWN_FIELDS: frozenset[str]

‘frozenset(…)’

class citeformer.csl.ValidationReport

Outcome of a CSL-JSON validation pass.

Attributes: errors: Hard validation errors — missing required fields, wrong types for known fields, id conflicts. An item with any error is unrenderable until the caller fixes it. warnings: Soft flags — unknown type values, unknown top-level fields, empty string values where a non-empty is expected. Rendering still works; output may degrade.

errors: list[str]

‘field(…)’

warnings: list[str]

‘field(…)’

property ok: bool

True iff there are no errors. Warnings are allowed.

citeformer.csl.validate_csl_json(item: dict[str, Any], *, raise_on_error: bool = False, strict_types: bool = False) → citeformer.csl.ValidationReport

Validate a single CSL-JSON item against the §10.2 contract.

Args: item: The CSL-JSON item (typically source.metadata). raise_on_error: If True, raise :class:CSLValidationError on any error. Warnings never raise. strict_types: If True, promote unknown type values to errors (default: warning).

Returns: A :class:ValidationReport with errors and warnings lists.

Raises: CSLValidationError: If raise_on_error is True and any error is found. The error message lists every error.

citeformer.csl.validate_source_metadata(metadata: dict[str, Any], *, raise_on_error: bool = False, strict_types: bool = False) → citeformer.csl.ValidationReport

Validate the metadata field of a :class:citeformer.Source.

Sugar over :func:validate_csl_json that reframes error messages to mention Source.metadata instead of raw CSL-JSON — matters for users reading the exception in the context of their pipeline.