odcs 0.9.1

Reference implementation of the Open Data Contract Standard (ODCS)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

//! Schema and contract indexes for reference resolution.

use std::collections::{HashMap, HashSet};

use crate::model::{DataContract, SchemaProperty};

/// Index of schema object and property names within a single contract.
#[derive(Debug, Clone, Default)]
pub struct SchemaIndex {
    objects: HashMap<String, HashSet<String>>,
}

impl SchemaIndex {
    /// Build an index from a parsed contract.
    #[must_use]
    pub fn build(contract: &DataContract) -> Self {
        let mut objects = HashMap::new();
        for schema in &contract.schema {
            if let Some(name) = schema.element.name.as_deref() {
                if !name.is_empty() {
                    let mut properties = HashSet::new();
                    collect_property_names(&schema.properties, &mut properties);
                    objects.insert(name.to_string(), properties);
                }
            }
        }
        Self { objects }
    }

    /// Returns `true` when a shorthand reference (`table.column`) resolves.
    #[must_use]
    pub fn resolve_shorthand(&self, reference: &str) -> bool {
        let Some((table, column)) = reference.split_once('.') else {
            return false;
        };
        self.objects
            .get(table)
            .is_some_and(|properties| properties.contains(column))
    }
}

/// Index of contracts by root `id` for cross-file FQN resolution.
#[derive(Debug, Clone, Default)]
pub struct ContractIndex {
    contracts: HashMap<String, SchemaIndex>,
}

impl ContractIndex {
    /// Build an index from multiple contracts keyed by root `id`.
    #[must_use]
    pub fn from_contracts(contracts: &[&DataContract]) -> Self {
        let mut index = Self::default();
        for contract in contracts {
            if !contract.id.is_empty() {
                index
                    .contracts
                    .insert(contract.id.clone(), SchemaIndex::build(contract));
            }
        }
        index
    }

    /// Returns `true` when a fully-qualified reference resolves against the set.
    #[must_use]
    pub fn resolve_fqn(&self, reference: &str) -> bool {
        let Some((contract_id, schema_name, property_name)) = parse_fqn_triple(reference) else {
            return false;
        };
        self.contracts.get(contract_id).is_some_and(|schema_index| {
            schema_index.resolve_shorthand(&format!("{schema_name}.{property_name}"))
        })
    }
}

/// Strip optional URL prefix from a fully-qualified reference.
#[must_use]
pub fn normalize_fqn_path(reference: &str) -> Option<&str> {
    let path = if let Some(idx) = reference.find('#') {
        reference.get(idx + 1..)?
    } else {
        reference
    };
    let path = path.trim_start_matches('/');
    if path.is_empty() {
        None
    } else {
        Some(path)
    }
}

/// Parse `{contractId}/{schemaObject}/{property}` from a fully-qualified reference.
#[must_use]
pub fn parse_fqn_triple(reference: &str) -> Option<(&str, &str, &str)> {
    let path = normalize_fqn_path(reference)?;
    let parts: Vec<&str> = path.split('/').collect();
    if parts.len() >= 3 {
        Some((parts[0], parts[1], parts[2]))
    } else {
        None
    }
}

fn collect_property_names(properties: &[SchemaProperty], out: &mut HashSet<String>) {
    for property in properties {
        if let Some(name) = property.element.name.as_deref() {
            if !name.is_empty() {
                out.insert(name.to_string());
            }
        }
        collect_property_names(&property.properties, out);
        if let Some(items) = &property.items {
            collect_property_names(std::slice::from_ref(items), out);
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn parse_fqn_triple_extracts_segments() {
        assert_eq!(
            parse_fqn_triple("provider-contract/customers/customer_id"),
            Some(("provider-contract", "customers", "customer_id"))
        );
        assert_eq!(
            parse_fqn_triple(
                "https://example.com/contracts/foo.yaml#provider/customers/customer_id"
            ),
            Some(("provider", "customers", "customer_id"))
        );
    }
}