Struct Assertion

pub struct Assertion { /* private fields */ }

A predicate-object relationship representing an assertion about a subject.

In Gordian Envelope, assertions are the basic building blocks for attaching information to a subject. An assertion consists of a predicate (which states what is being asserted) and an object (which provides the assertion’s value).

Assertions can be attached to envelope subjects to form semantic statements like: “subject hasAttribute value” or “document signedBy signature”.

Assertions are equivalent to RDF (Resource Description Framework) triples, where:

• The envelope’s subject is the subject of the triple
• The assertion’s predicate is the predicate of the triple
• The assertion’s object is the object of the triple

Generally you do not create an instance of this type directly, but instead use Envelope::new_assertion, or the various functions on Envelope that create assertions.

Implementations

impl Assertion

pub fn new( predicate: impl EnvelopeEncodable, object: impl EnvelopeEncodable, ) -> Self

Creates a new assertion and calculates its digest.

This constructor takes a predicate and object, both of which are converted to envelopes using the EnvelopeEncodable trait. It then calculates the assertion’s digest by combining the digests of the predicate and object.

The digest is calculated according to the Gordian Envelope specification, which ensures that semantically equivalent assertions always produce the same digest.

Parameters

• predicate - The predicate of the assertion, which states what is being asserted
• object - The object of the assertion, which provides the assertion’s value

Returns

A new assertion with the specified predicate, object, and calculated digest.

Example

// Direct method - create an assertion envelope
let assertion_envelope = Envelope::new_assertion("name", "Alice");

// Or create and add an assertion to a subject
let person = Envelope::new("person").add_assertion("name", "Alice");

pub fn predicate(&self) -> Envelope

Returns the predicate of the assertion.

The predicate states what is being asserted about the subject. It is typically a string or known value, but can be any envelope.

Returns

A clone of the assertion’s predicate envelope.

pub fn object(&self) -> Envelope

Returns the object of the assertion.

The object provides the value or content of the assertion. It can be any type that can be represented as an envelope.

Returns

A clone of the assertion’s object envelope.

pub fn digest_ref(&self) -> &Digest

Returns a reference to the digest of the assertion.

The digest is calculated when the assertion is created and is used for verification and deduplication. The digest calculation follows the rules specified in the Gordian Envelope IETF draft, Section 4.4.

Returns

A reference to the assertion’s digest.

impl Assertion

Support for adding vendor-specific attachments to Gordian Envelopes.

This module extends Gordian Envelope with the ability to add vendor-specific attachments to an envelope. Attachments provide a standardized way for different applications to include their own data in an envelope without interfering with the main data structure or with other attachments.

Each attachment has:

• A payload (arbitrary data)
• A required vendor identifier (typically a reverse domain name)
• An optional conformsTo URI that indicates the format of the attachment

This allows for a common envelope format that can be extended by different vendors while maintaining interoperability.

Example

use bc_envelope::prelude::*;

// Create a base envelope
let envelope = Envelope::new("Alice").add_assertion("knows", "Bob");

// Add a vendor-specific attachment
let with_attachment = envelope.add_attachment(
    "Custom data for this envelope",
    "com.example",
    Some("https://example.com/attachment-format/v1"),
);

// The attachment is added as an assertion with the 'attachment' predicate
assert!(
    !with_attachment
        .assertions_with_predicate(known_values::ATTACHMENT)
        .is_empty()
);

// The attachment can be extracted later
let attachment = with_attachment.attachments().unwrap()[0].clone();
let payload = attachment.attachment_payload().unwrap();
let vendor = attachment.attachment_vendor().unwrap();
let format = attachment.attachment_conforms_to().unwrap();

assert_eq!(payload.format_flat(), r#""Custom data for this envelope""#);
assert_eq!(vendor, "com.example");
assert_eq!(
    format,
    Some("https://example.com/attachment-format/v1".to_string())
);

Methods for creating and accessing attachments at the assertion level

pub fn new_attachment( payload: impl EnvelopeEncodable, vendor: &str, conforms_to: Option<&str>, ) -> Self

Creates a new attachment assertion.

An attachment assertion consists of:

• The predicate known_values::ATTACHMENT
• An object that is a wrapped envelope containing:
  • The payload (as the subject)
  • A required 'vendor': String assertion
  • An optional 'conformsTo': String assertion

See BCR-2023-006 for the detailed specification.

Parameters

• payload - The content of the attachment
• vendor - A string that uniquely identifies the vendor (typically a reverse domain name)
• conforms_to - An optional URI that identifies the format of the attachment

Returns

A new attachment assertion

Examples

Example:

Create an attachment assertion that contains vendor-specific data, then use it to access the payload, vendor ID, and conformsTo value.

The assertion will have a predicate of “attachment” and an object that’s a wrapped envelope containing the payload with vendor and conformsTo assertions added to it.

pub fn attachment_payload(&self) -> Result<Envelope>

Returns the payload of an attachment assertion.

This extracts the subject of the wrapped envelope that is the object of this attachment assertion.

Returns

The payload envelope

Errors

Returns an error if the assertion is not a valid attachment assertion

pub fn attachment_vendor(&self) -> Result<String>

Returns the vendor identifier of an attachment assertion.

Returns

The vendor string

Errors

Returns an error if the assertion is not a valid attachment assertion

pub fn attachment_conforms_to(&self) -> Result<Option<String>>

Returns the optional conformsTo URI of an attachment assertion.

Returns

The conformsTo string if present, or None

Errors

Returns an error if the assertion is not a valid attachment assertion

pub fn validate_attachment(&self) -> Result<()>

Validates that an assertion is a proper attachment assertion.

This ensures:

• The attachment assertion’s predicate is known_values::ATTACHMENT
• The attachment assertion’s object is an envelope
• The attachment assertion’s object has a 'vendor': String assertion
• The attachment assertion’s object has an optional 'conformsTo': String assertion

Returns

Ok(()) if the assertion is a valid attachment assertion

Errors

Returns EnvelopeError::InvalidAttachment if the assertion is not a valid attachment assertion

Trait Implementations

impl Clone for Assertion

fn clone(&self) -> Assertion

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Assertion

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

Formats the value using the given formatter.

impl DigestProvider for Assertion

Implementation of DigestProvider for Assertion.

This allows an assertion to provide its digest for calculation of higher-level digests in the envelope digest tree.

fn digest(&self) -> Cow<'_, Digest>

Returns a reference to the assertion’s digest.

This is used in the envelope digest tree calculation.

impl EnvelopeEncodable for Assertion

Implementation of EnvelopeEncodable for Assertion.

This implementation converts an assertion into an envelope with the assertion as its subject.

fn into_envelope(self) -> Envelope

Creates an envelope with this assertion as its subject.

fn to_envelope(&self) -> Envelope

where Self: Clone,

Converts a reference to this value into a Gordian Envelope.

impl From<Assertion> for CBOR

Converts an assertion to its CBOR representation.

The CBOR representation of an assertion is a map with a single key-value pair, where the key is the predicate’s CBOR and the value is the object’s CBOR.

fn from(value: Assertion) -> Self

Converts to this type from the input type.

impl PartialEq for Assertion

Equality is based on digest equality, not structural equality.

Two assertions are considered equal if they have the same digest, regardless of how they were constructed.

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

const fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl TryFrom<CBOR> for Assertion

Attempts to convert a CBOR value to an assertion.

The CBOR must be a map with exactly one entry, where the key represents the predicate and the value represents the object.

type Error = Error

The type returned in the event of a conversion error.

fn try_from(value: CBOR) -> Result<Self>

Performs the conversion.

impl TryFrom<Map> for Assertion

Attempts to convert a CBOR map to an assertion.

The map must have exactly one entry, where the key represents the predicate and the value represents the object. This is used in the deserialization process.

type Error = Error

The type returned in the event of a conversion error.

fn try_from(map: Map) -> Result<Self>

Performs the conversion.

impl Eq for Assertion

Assertion implements full equality.