1use serde::{Deserialize, Serialize};
34
35use crate::engram::{Engram, TimeBounds};
36use crate::manifest::{BlobFetcher, BlobSource};
37use crate::schema::{
38 Hash, ManifestId, ModerationState, PrivacyClass, ProvenanceOrigin, ProvenanceRecord, SchemaRef,
39 Timestamp, TrustEnvelope, TrustLevel,
40};
41use crate::typed::{TypedPayload, load_typed, save_typed};
42use crate::{Error, Result, Store};
43
44#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
50pub enum SchemaFormat {
51 #[serde(rename = "mere-native")]
53 MereNative,
54 #[serde(rename = "json-schema")]
56 JsonSchema,
57 #[serde(rename = "json-ld")]
59 JsonLd,
60}
61
62#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
69pub struct SchemaDefinition {
70 pub format: SchemaFormat,
71 pub schema_id: String,
75 pub body: serde_json::Value,
78}
79
80impl TypedPayload for SchemaDefinition {
81 fn schema_ref() -> SchemaRef {
82 *META_SCHEMA_REF
83 }
84}
85
86const META_SCHEMA_PAYLOAD: &[u8] = br#"{"format":"mere-native","schema_id":"eidetic.meta-schema/v1","body":{"version":1,"description":"Schema engram payload describing another schema in one of: mere-native, json-schema, json-ld.","required":["format","schema_id","body"],"fields":{"format":{"type":"enum","values":["mere-native","json-schema","json-ld"]},"schema_id":{"type":"string"},"body":{"type":"object"}}}}"#;
96
97pub fn meta_schema_ref() -> SchemaRef {
102 SchemaRef::from_id(ManifestId::from_hash(Hash::of(META_SCHEMA_PAYLOAD)))
103}
104
105pub static META_SCHEMA_REF: std::sync::LazyLock<SchemaRef> =
111 std::sync::LazyLock::new(meta_schema_ref);
112
113pub async fn bootstrap_meta_schema(store: &mut dyn Store) -> Result<()> {
125 let meta_id = META_SCHEMA_REF.0;
126 if crate::manifest::load_manifest(store, meta_id)
127 .await?
128 .is_some()
129 {
130 return Ok(());
131 }
132
133 let local_key = format!("blob:{}", Hash::of(META_SCHEMA_PAYLOAD).to_hex());
137 store.put(&local_key, META_SCHEMA_PAYLOAD).await?;
138
139 let manifest = crate::manifest::BlobManifest {
140 id: meta_id,
141 schema: *META_SCHEMA_REF,
142 content_hash: Hash::of(META_SCHEMA_PAYLOAD),
143 byte_size: META_SCHEMA_PAYLOAD.len() as u64,
144 created_at: Timestamp::ZERO,
145 last_accessed: None,
146 sources: vec![crate::manifest::BlobSource::Local { key: local_key }],
147 privacy: PrivacyClass::PublicPortable,
148 provenance: ProvenanceRecord {
149 origin: ProvenanceOrigin::Generated,
150 upstream: Vec::new(),
151 tooling: Some(format!("eidetic/{}", env!("CARGO_PKG_VERSION"))),
152 generated_at: Timestamp::ZERO,
153 },
154 trust: TrustEnvelope {
155 level: TrustLevel::CheckpointAccepted,
156 signatures: Vec::new(),
157 moderation_state: ModerationState::Accepted,
158 },
159 schema_metadata: serde_json::Value::Null,
160 manifest_version: crate::manifest::BlobManifest::CURRENT_VERSION,
161 };
162 crate::manifest::save_manifest(store, &manifest).await?;
163 Ok(())
164}
165
166pub fn meta_schema_engram() -> Engram {
172 Engram::new(
173 *META_SCHEMA_REF,
174 META_SCHEMA_PAYLOAD.to_vec(),
175 PrivacyClass::PublicPortable,
176 ProvenanceRecord {
177 origin: ProvenanceOrigin::Generated,
178 upstream: Vec::new(),
179 tooling: Some(format!("eidetic/{}", env!("CARGO_PKG_VERSION"))),
180 generated_at: Timestamp::ZERO,
181 },
182 TrustEnvelope {
183 level: TrustLevel::CheckpointAccepted,
184 signatures: Vec::new(),
185 moderation_state: ModerationState::Accepted,
186 },
187 TimeBounds::at(Timestamp::ZERO),
188 )
189}
190
191pub trait SchemaValidator {
200 fn format(&self) -> SchemaFormat;
201 fn validate(&self, definition: &SchemaDefinition, payload_bytes: &[u8]) -> Result<()>;
202}
203
204pub fn validate_payload(definition: &SchemaDefinition, payload_bytes: &[u8]) -> Result<()> {
207 match definition.format {
208 SchemaFormat::MereNative => MereNativeValidator.validate(definition, payload_bytes),
209 SchemaFormat::JsonSchema => JsonSchemaValidator.validate(definition, payload_bytes),
210 SchemaFormat::JsonLd => JsonLdValidator.validate(definition, payload_bytes),
211 }
212}
213
214pub async fn save_schema(
219 store: &mut dyn Store,
220 definition: &SchemaDefinition,
221 privacy: PrivacyClass,
222 provenance: ProvenanceRecord,
223 trust: TrustEnvelope,
224 created_at: Timestamp,
225) -> Result<ManifestId> {
226 save_typed(
227 store,
228 definition,
229 Vec::<BlobSource>::new(),
230 privacy,
231 provenance,
232 trust,
233 created_at,
234 )
235 .await
236}
237
238pub async fn load_schema(
241 store: &mut dyn Store,
242 fetcher: &mut dyn BlobFetcher,
243 schema_id: ManifestId,
244) -> Result<Option<SchemaDefinition>> {
245 load_typed::<SchemaDefinition>(store, fetcher, schema_id).await
246}
247
248pub async fn validate_against_schema(
256 store: &mut dyn Store,
257 fetcher: &mut dyn BlobFetcher,
258 schema_ref: SchemaRef,
259 payload_bytes: &[u8],
260) -> Result<()> {
261 let Some(definition) = load_schema(store, fetcher, schema_ref.0).await? else {
262 return Ok(());
264 };
265 validate_payload(&definition, payload_bytes)
266}
267
268pub struct MereNativeSchemaBuilder {
285 schema_id: String,
286 description: String,
287 fields: Vec<(String, MereNativeFieldSpec, bool)>,
288 version: u32,
289}
290
291impl MereNativeSchemaBuilder {
292 pub fn new(schema_id: impl Into<String>) -> Self {
293 Self {
294 schema_id: schema_id.into(),
295 description: String::new(),
296 fields: Vec::new(),
297 version: 1,
298 }
299 }
300
301 pub fn description(mut self, description: impl Into<String>) -> Self {
302 self.description = description.into();
303 self
304 }
305
306 pub fn version(mut self, version: u32) -> Self {
307 self.version = version;
308 self
309 }
310
311 pub fn field(
313 mut self,
314 name: impl Into<String>,
315 spec: MereNativeFieldSpec,
316 required: bool,
317 ) -> Self {
318 self.fields.push((name.into(), spec, required));
319 self
320 }
321
322 pub fn build(self) -> SchemaDefinition {
323 let mut required = Vec::new();
324 let mut fields = serde_json::Map::new();
325 for (name, spec, is_required) in self.fields {
326 if is_required {
327 required.push(name.clone());
328 }
329 fields.insert(
330 name,
331 serde_json::to_value(&spec).expect("field spec serializes"),
332 );
333 }
334 let body = serde_json::json!({
335 "version": self.version,
336 "description": self.description,
337 "required": required,
338 "fields": fields,
339 });
340 SchemaDefinition {
341 format: SchemaFormat::MereNative,
342 schema_id: self.schema_id,
343 body,
344 }
345 }
346}
347
348pub async fn find_schema_by_id(
359 store: &mut dyn Store,
360 fetcher: &mut dyn BlobFetcher,
361 schema_id: &str,
362) -> Result<Option<(ManifestId, SchemaDefinition)>> {
363 let manifests = crate::manifest::list_manifests(store, Some(*META_SCHEMA_REF)).await?;
364 for manifest in manifests {
365 let definition: SchemaDefinition =
366 match load_typed::<SchemaDefinition>(store, fetcher, manifest.id).await {
367 Ok(Some(d)) => d,
368 _ => continue,
369 };
370 if definition.schema_id == schema_id {
371 return Ok(Some((manifest.id, definition)));
372 }
373 }
374 Ok(None)
375}
376
377#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, Default)]
380pub struct MereNativeSchemaBody {
381 #[serde(default)]
382 pub version: u32,
383 #[serde(default)]
384 pub description: String,
385 #[serde(default)]
386 pub required: Vec<String>,
387 #[serde(default)]
388 pub fields: std::collections::BTreeMap<String, MereNativeFieldSpec>,
389}
390
391#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
394#[serde(tag = "type", rename_all = "snake_case")]
395pub enum MereNativeFieldSpec {
396 String,
397 U64,
398 I64,
399 F64,
400 Bool,
401 Object,
402 Array,
403 Enum { values: Vec<String> },
404}
405
406pub struct MereNativeValidator;
408
409impl SchemaValidator for MereNativeValidator {
410 fn format(&self) -> SchemaFormat {
411 SchemaFormat::MereNative
412 }
413
414 fn validate(&self, definition: &SchemaDefinition, payload_bytes: &[u8]) -> Result<()> {
415 if definition.format != SchemaFormat::MereNative {
416 return Err(Error::new(format!(
417 "MereNativeValidator received non-MereNative format: {:?}",
418 definition.format
419 )));
420 }
421 let body: MereNativeSchemaBody = serde_json::from_value(definition.body.clone())
422 .map_err(|e| Error::new(format!("mere-native schema body parse: {e}")))?;
423
424 let payload_value: serde_json::Value = serde_json::from_slice(payload_bytes)
425 .map_err(|e| Error::new(format!("payload parse (mere-native): {e}")))?;
426 let object = payload_value
427 .as_object()
428 .ok_or_else(|| Error::new("mere-native payloads must be JSON objects".to_string()))?;
429
430 for required in &body.required {
431 if !object.contains_key(required) {
432 return Err(Error::new(format!(
433 "mere-native schema {}: missing required field `{}`",
434 definition.schema_id, required
435 )));
436 }
437 }
438
439 for (name, spec) in &body.fields {
440 if let Some(value) = object.get(name) {
441 check_field_spec(&definition.schema_id, name, spec, value)?;
442 }
443 }
444
445 Ok(())
446 }
447}
448
449fn check_field_spec(
450 schema_id: &str,
451 name: &str,
452 spec: &MereNativeFieldSpec,
453 value: &serde_json::Value,
454) -> Result<()> {
455 let kind_ok = match spec {
456 MereNativeFieldSpec::String => value.is_string(),
457 MereNativeFieldSpec::U64 => value.as_u64().is_some(),
458 MereNativeFieldSpec::I64 => value.as_i64().is_some(),
459 MereNativeFieldSpec::F64 => value.as_f64().is_some(),
460 MereNativeFieldSpec::Bool => value.is_boolean(),
461 MereNativeFieldSpec::Object => value.is_object(),
462 MereNativeFieldSpec::Array => value.is_array(),
463 MereNativeFieldSpec::Enum { values } => match value.as_str() {
464 Some(s) => values.iter().any(|v| v == s),
465 None => false,
466 },
467 };
468 if !kind_ok {
469 return Err(Error::new(format!(
470 "schema {}: field `{}` failed type check (expected {:?}, got {})",
471 schema_id, name, spec, value
472 )));
473 }
474 Ok(())
475}
476
477mod validators;
478pub use validators::{JsonLdValidator, JsonSchemaValidator};
479#[cfg(test)]
480mod tests;