jcard 0.3.0

RFC 7095 jCard (JSON representation of vCard) types with serde support
Documentation
  • Coverage
  • 100%
    73 out of 73 items documented2 out of 43 items with examples
  • Size
  • Source code size: 80.85 kB This is the summed size of all the files inside the crates.io package for this release.
  • Documentation size: 5.5 MB This is the summed size of all files generated by rustdoc for all configured targets
  • Ø build duration
  • this release: 29s Average build duration of successful builds.
  • all releases: 29s Average build duration of successful builds in releases after 2024-10-23.
  • Links
  • ticpu/jcard
    0 0 0
  • crates.io
  • Dependencies
  • Versions
  • Owners
  • ticpu

jcard

CI crates.io docs.rs MSRV license

RFC 7095 jCard (JSON representation of vCard) types with serde support.

All value types from RFC 7095 §3.5 are supported: text, uri, date, time, date-time, date-and-or-time, timestamp, boolean, integer, float, utc-offset, language-tag, and unknown. Structured property values with nested arrays (§3.3.1.3) are handled. Type identifiers are stored separately for round-trip fidelity, including extension types.

Usage

[dependencies]
jcard = "0.3"

Builder

use jcard::JCard;

let jcard = JCard::builder()
    .fn_("Jane Doe")
    .n("Doe", "Jane", "", "", "")
    .email("jane.doe@example.com")
    .build();

let json = serde_json::to_string_pretty(&jcard).unwrap();
let parsed: JCard = serde_json::from_str(&json).unwrap();
assert_eq!(jcard, parsed);

Lenient parsing with warnings

use jcard::JCard;

let parsed = JCard::from_json(r#"["vcard",[
    ["version",{},"text","4.0"],
    ["fn",{},"text","Jane Doe"],
    ["email","bad-params","text","jane@example.com"]
]]"#).unwrap();

// Best-effort result is always available
assert_eq!(parsed.value.properties().len(), 3);

// Warnings report what went wrong
for w in &parsed.warnings {
    eprintln!("{w}");
}

Deserialization behavior

The serde Deserialize impl returns Err on structurally invalid jCard input (wrong tag, not an array, etc.) by default. This is the expected behavior for standalone use — the caller sees the error and decides what to do.

When jCard is embedded as a field in a parent struct (e.g., EIDO's agencyJcard: Option<JCard>), a deserialization error on the jCard poisons the entire parent. Enable the lenient-deserialize feature to return an empty JCard (with only the mandatory version property) instead of Err:

[dependencies]
jcard = { version = "0.3", features = ["lenient-deserialize"] }

Both paths discard warnings. Use from_json() or from_value() when you need structured warning collection alongside the best-effort result.

From an existing serde_json::Value

use jcard::JCard;

let value: serde_json::Value = serde_json::from_str(
    r#"["vcard",[["version",{},"text","4.0"],["fn",{},"text","Test"]]]"#
).unwrap();

let parsed = JCard::from_value(&value).unwrap();
assert!(!parsed.has_warnings());

License

Licensed under either of

at your option.