Struct Style 

pub struct Style {
    pub version: SchemaVersion,
    pub info: StyleInfo,
    pub templates: Option<HashMap<String, Vec<TemplateComponent>>>,
    pub options: Option<Config>,
    pub citation: Option<CitationSpec>,
    pub bibliography: Option<BibliographySpec>,
    pub custom: Option<HashMap<String, Value>>,
    pub extends: Option<StyleReference>,
    pub extends_pin: Option<String>,
    pub raw_yaml: Option<Value>,
    pub scoped_raw_options: ScopedRawOptions,
    pub unknown_fields: BTreeMap<String, Value>,
}

The new Citum Style model.

This is the target schema for Citum, featuring declarative options and simple template components instead of procedural conditionals.

Fields

version: SchemaVersion

Style schema version.

info: StyleInfo

Style metadata.

templates: Option<HashMap<String, Vec<TemplateComponent>>>

Named reusable templates.

options: Option<Config>

Global style options.

citation: Option<CitationSpec>

Citation specification.

bibliography: Option<BibliographySpec>

Bibliography specification.

custom: Option<HashMap<String, Value>>

Custom user-defined fields for extensions.

extends: Option<StyleReference>

Extends a base style, with optional local overrides.

When present, the base StyleReference is resolved and the local overrides are merged before any further processing. Explicit options, citation, and bibliography keys at the same document level take precedence over the resolved base.

extends_pin: Option<String>

Optional content-addressed integrity pin for the parent style referenced by extends.

When present, the resolver verifies that the SHA-256 of the fetched parent matches this CIDv1 string before merging. Mismatches abort resolution with ResolutionError::IntegrityFailure. Absent means “no integrity check” — appropriate for file:// parents under user control or trusted local registries.

raw_yaml: Option<Value>

Raw YAML captured when the style was loaded via Style::from_yaml_str or Style::from_yaml_bytes. Used during style resolution for null-aware overlay merging (e.g., ibid: ~ correctly clears an inherited preset value). Absent in programmatically-constructed styles.

scoped_raw_options: ScopedRawOptions

Chain-merged authored citation.options / bibliography.options mappings, captured at parse time and maintained through extends resolution. Basis for the runtime scope cascade’s field-level merge (see crate::options::cascade::ScopedRawOptions). Empty in programmatically-constructed styles, which fall back to the typed whole-block merge.

Public like Self::raw_yaml and Self::unknown_fields: other workspace crates construct Style via Style { .. } .. Default::default(), which requires every field visible at the call site, so a pub(crate) field would break those construction sites rather than only external struct-literal callers.

unknown_fields: BTreeMap<String, Value>

Forward-compat: captures unknown keys when an older engine reads a style produced by a newer schema. Empty by default; treated as a SoftDegrade signal. See docs/specs/FORWARD_COMPATIBILITY.md.

Implementations

impl Style

pub fn from_yaml_str(s: &str) -> Result<Style, Error>

Parse a Citum style from a YAML string, preserving raw YAML for null-aware overlay merging during base resolution.

Preferred over serde_yaml::from_str when the style extends a base, so that ibid: ~ and similar null overrides correctly clear inherited values.

Errors

Returns a serde error if YAML parsing or deserialization fails.

pub fn apply_scoped_options(&mut self)

Apply scoped citation and bibliography option overrides to this style.

Translates typed option values (label mode, label wrap, repeated-author rendering, date position, title terminator) into concrete template mutations. Call this after mutating bibliography.options at runtime — e.g. after applying per-document overrides — so that template state stays consistent with the option values.

pub fn apply_overlay(&mut self, overlay: &Style)

Merge a partial overlay style over this style in place; overlay fields win.

Overlay merging is typed and matches extends inheritance for the fields it supports:

• info, templates, options, and custom are merged (overlay wins for Some fields / keys).
• citation / bibliography are deep-merged; explicit YAML ~ can clear inherited fields when overlay.raw_yaml is populated (e.g. via Style::from_yaml_bytes).

The caller is responsible for calling apply_scoped_options afterwards if scoped-option side-effects (label-wrap, date-position, etc.) are needed.

pub fn from_yaml_bytes(bytes: &[u8]) -> Result<Style, Error>

Parse a Citum style from YAML bytes, preserving raw YAML for null-aware overlay merging during preset resolution.

Errors

Returns a serde error if YAML parsing or deserialization fails.

pub fn from_document_bytes( bytes: &[u8], format: StyleDocumentFormat, ) -> Result<Style, StyleDocumentError>

Parse a Citum style from bytes in any StyleDocumentFormat, preserving a format-neutral raw value tree for null-aware overlay merging.

This is the canonical entry point for every style load path — file, store, registry, CLI conversion, and server resolution — so that explicit-null inherited-field clearing (see Style::apply_overlay) behaves identically regardless of load path or wire format. JSON and YAML documents parse directly into the same generic value tree used by Style::from_yaml_bytes; CBOR documents are decoded the same way but are rejected if any map uses a non-string key, since the raw-tree presence lookups used by overlay merging key on string field names.

Errors

Returns StyleDocumentError if the bytes cannot be decoded in the requested format, if a CBOR document contains a non-string map key, or if the decoded style fails schema or resource-limit validation.

impl Style

pub fn into_resolved(self) -> Style

Resolve this style into its final effective form by applying base inheritance.

If the extends field is present, the base StyleBase is loaded and any explicit options, citation, or bibliography keys in the current style document are merged on top (taking ultimate precedence).

Styles without a base still resolve Template V3 variants and scoped options, but do not merge any inherited style data.

Panics

Panics when style resolution fails. Use Style::try_into_resolved to handle profile-contract and inheritance errors explicitly.

pub fn try_into_resolved(self) -> Result<Style, ResolutionError>

Resolve this style into its final effective form, returning validation errors.

Unlike Style::into_resolved, this preserves resolution failures as structured ResolutionError values.

Errors

Returns an error when profile wrappers try to override template-bearing structure, when profile capability validation fails, or when inheritance loops are detected.

pub fn try_into_resolved_with( self, resolver: Option<&(dyn StyleResolver<Locale = Locale, Style = Style> + 'static)>, ) -> Result<Style, ResolutionError>

Resolve this style into its final effective form using an optional style resolver.

The resolver is used for URI, registry, and remote extends references that cannot be satisfied by embedded bases alone.

Errors

Returns an error when style inheritance or Template V3 variant resolution fails.

pub fn into_resolved_recursive(self, visited: &mut HashSet<String>) -> Style

Internal recursive resolver with loop protection.

Panics

Panics when style resolution fails. Use Style::try_into_resolved_recursive to preserve errors.

pub fn try_into_resolved_recursive( self, visited: &mut HashSet<String>, ) -> Result<Style, ResolutionError>

Internal recursive resolver with loop protection.

Errors

Returns an error when profile wrappers violate the config-only contract, when profile capability validation fails, or when inheritance loops are detected.

pub fn try_into_resolved_recursive_with( self, resolver: Option<&(dyn StyleResolver<Locale = Locale, Style = Style> + 'static)>, visited: &mut HashSet<String>, ) -> Result<Style, ResolutionError>

Internal recursive resolver with loop protection and optional external resolver.

Errors

Returns an error when style inheritance or Template V3 variant resolution fails.

impl Style

pub fn validate_resource_limits(&self) -> Result<(), String>

Validate hard resource limits for style templates.

Errors

Returns an error when authored template structure exceeds the maximum depth or component count accepted by the engine.

pub fn validate(&self) -> Vec<SchemaWarning>

Validate the style and return any non-fatal warnings.

This method checks for issues that are syntactically valid but semantically suspect, such as unrecognized reference type names in TypeSelector values.

Warnings do not prevent rendering; they are informational only.

Trait Implementations

impl Clone for Style

fn clone(&self) -> Style

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Style

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Style

fn default() -> Style

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Style

fn deserialize<__D>( __deserializer: __D, ) -> Result<Style, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Style

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.