qubit_metadata/schema/
metadata_field.rs

1// =============================================================================
2//    Copyright (c) 2025 - 2026 Haixing Hu.
3//
4//    SPDX-License-Identifier: Apache-2.0
5//
6//    Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! [`MetadataField`] — one field definition in a metadata schema.
9
10use qubit_datatype::DataType;
11use serde::Deserialize;
12use serde::Deserializer;
13use serde::Serialize;
14
15/// Definition of one metadata field in a [`crate::MetadataSchema`].
16///
17/// Its V1 wire representation is an object with exactly the `data_type` and
18/// `required` fields. Positional arrays are rejected by deserialization.
19///
20/// # Examples
21///
22/// ```
23/// use qubit_datatype::DataType;
24/// use qubit_metadata::MetadataField;
25///
26/// let field = MetadataField::new(DataType::String, true);
27/// assert!(field.is_required());
28/// ```
29#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
30pub struct MetadataField {
31    /// Runtime data type of this field.
32    data_type: DataType,
33    /// Whether this field must be present when validating metadata.
34    required: bool,
35}
36
37impl<'de> Deserialize<'de> for MetadataField {
38    /// Deserializes a field definition from its strict object representation.
39    ///
40    /// # Type Parameters
41    ///
42    /// * `D` - Deserializer providing the field object.
43    ///
44    /// # Parameters
45    ///
46    /// * `deserializer` - Source of the serialized field definition.
47    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
48    where
49        D: Deserializer<'de>,
50    {
51        let (data_type, required) = super::internal::deserialize_metadata_field(deserializer)?;
52        Ok(Self::new(data_type, required))
53    }
54}
55
56impl MetadataField {
57    /// Creates a field definition.
58    ///
59    /// # Parameters
60    ///
61    /// * `data_type` - Concrete data type accepted by the field.
62    /// * `required` - Whether metadata must provide a concrete value.
63    ///
64    /// # Returns
65    ///
66    /// A new field definition.
67    #[inline(always)]
68    #[must_use = "the constructed metadata field should be used"]
69    pub fn new(data_type: DataType, required: bool) -> Self {
70        Self { data_type, required }
71    }
72
73    /// Returns the runtime data type of this field.
74    ///
75    /// # Returns
76    ///
77    /// The declared field data type.
78    #[inline(always)]
79    #[must_use = "the metadata field type should be inspected"]
80    pub fn data_type(&self) -> DataType {
81        self.data_type
82    }
83
84    /// Returns `true` when this field is required.
85    ///
86    /// # Returns
87    ///
88    /// `true` when validation requires a concrete value for this field.
89    #[inline(always)]
90    #[must_use]
91    pub fn is_required(&self) -> bool {
92        self.required
93    }
94}
qubit_metadata/schema/metadata_field.rs

qubit_metadata/schema/
metadata_field.rs
