Struct DataRef 

pub struct DataRef {
    pub ref_type: DataRefType,
    pub description: Option<String>,
    pub size_bytes: Option<u64>,
    pub format: Option<String>,
    pub schema_version: Option<String>,
    pub content_hash: Option<ContentHash>,
    pub location: Option<Location>,
    pub embedded: Option<EmbeddedContent>,
    pub extensions: Map<String, Value>,
}

A reference to a piece of data the context describes.

Per acdp-data-ref.schema.json oneOf: exactly one of location or embedded MUST be present. The struct does not enforce this at construction time; runtime validation is done by validate_data_ref.

Fields

ref_type: DataRefType

Role of this reference within the context.

description: Option<String>

Human-readable description (≤ 1000 chars).

Optional and absent-or-string in acdp-data-ref.schema.json — not nullable. de_present rejects an explicit "description": null.

size_bytes: Option<u64>

Size of the referenced or embedded data in bytes.

format: Option<String>

Producer-defined format identifier (e.g. parquet, csv).

schema_version: Option<String>

Producer-specific schema version for this data.

content_hash: Option<ContentHash>

Optional SHA-256 hash for verifying data integrity at fetch time. For embedded data, computed over the decoded bytes per acdp-data-ref.schema.json.

location: Option<Location>

Where the data resides — either a URI string or a structured locator object with a dotted-namespace scheme field.

embedded: Option<EmbeddedContent>

Inline embedded payload. Decoded size MUST NOT exceed 64 KB.

extensions: Map<String, Value>

Unknown producer-controlled DataRef fields, preserved verbatim.

acdp-data-ref.schema.json has NO additionalProperties: false at its root — the object is open by design. A DataRef lives inside ProducerContent (the content_hash preimage), so a future ACDP minor version that adds a producer-controlled DataRef field must round-trip through this map: without it an older consumer would silently drop the new field on deserialization and recompute a different content_hash, falsely failing verification. Mirrors the crate::types::body::Body::extensions pattern (RFC-ACDP-0001 §5.7, conformance fixture can-010).

Implementations

impl DataRef

pub fn uri(ref_type: DataRefType, uri: impl Into<String>) -> Self

URI-form data reference (no integrity hash).

pub fn uri_verified( ref_type: DataRefType, uri: impl Into<String>, hash: ContentHash, ) -> Self

URI-form data reference with a SHA-256 integrity hash.

pub fn structured( ref_type: DataRefType, scheme: impl Into<String>, extra: Map<String, Value>, ) -> Self

Structured-locator data reference. scheme MUST match ^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$. Additional fields go in extra.

In debug builds, an invalid scheme triggers a debug_assert! to surface the bug at construction time. Release builds accept the malformed value silently — pair this constructor with crate::validation::validate_data_ref (called automatically by RequestBuilder::build) for runtime rejection. For a fallible variant, use Self::try_structured.

pub fn try_structured( ref_type: DataRefType, scheme: impl Into<String>, extra: Map<String, Value>, ) -> Result<Self, AcdpError>

Fallible structured-locator constructor. Returns crate::error::AcdpError::SchemaViolation if scheme does not match the dotted-namespace pattern.

pub fn embedded_json(ref_type: DataRefType, content: Value) -> Self

Embedded JSON data reference.

pub fn embedded_utf8(ref_type: DataRefType, text: impl Into<String>) -> Self

Embedded UTF-8 text data reference. The text is stored as a JSON string.

pub fn embedded_base64(ref_type: DataRefType, b64: impl Into<String>) -> Self

Embedded base64 binary data reference. b64 is stored as a JSON string.

pub fn primary_result_uri(uri: impl Into<String>) -> Self

DataRef::uri(DataRefType::PrimaryResult, uri).

pub fn raw_data_uri(uri: impl Into<String>) -> Self

DataRef::uri(DataRefType::RawData, uri).

pub fn supporting_info_uri(uri: impl Into<String>) -> Self

DataRef::uri(DataRefType::SupportingInfo, uri).

pub fn derived_data_uri(uri: impl Into<String>) -> Self

DataRef::uri(DataRefType::DerivedData, uri).

pub fn primary_result_json(content: Value) -> Self

DataRef::embedded_json(DataRefType::PrimaryResult, content).

pub fn derived_data_json(content: Value) -> Self

DataRef::embedded_json(DataRefType::DerivedData, content).

Trait Implementations

impl Clone for DataRef

fn clone(&self) -> DataRef

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DataRef

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for DataRef

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for DataRef

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

where __S: Serializer,

Serialize this value into the given Serde serializer.