Skip to main content

evalhub_schema/
common.rs

1//! Pieces shared by Card and Eval: producer, attachments, relations, `ext`.
2//!
3//! # Producer
4//!
5//! `producer { name, version }` identifies the software that wrote the
6//! record. It is informational and is not a facet: two harnesses can produce
7//! comparable records, and one harness can produce incomparable ones.
8//!
9//! # Attachments
10//!
11//! ```text
12//! attachments[] { path, sha256, size, media_type }
13//! ```
14//!
15//! An attachment is a file in object storage, addressed by its sha256. The
16//! record refers to it by `path`, a relative, `..`-free, unique-within-record
17//! name that other fields (`results[].samples_ref`, `runs[].calls`,
18//! `runs[].artifacts[]`) point at. The hub checks that referenced paths
19//! exist in `attachments[]` and that every `sha256` has been uploaded and
20//! confirmed (see `evalhub_store::objects`); it does not open the file.
21//! `media_type` is a hint for display and download, nothing more.
22//!
23//! Content addressing means two records attaching the same file share one
24//! object, and a record cannot be published against an object that does not
25//! exist. It also means the record commits to the exact bytes: a different
26//! file is a different sha256 and therefore a different record.
27//!
28//! # Relations
29//!
30//! ```text
31//! relations[] { type, to, attrs }
32//! ```
33//!
34//! `type` is a registry id (`core/uses_eval`, `core/retry_of`, …). `to` is a
35//! pinned reference, `{ns}/{name}@{seq}`, which the hub resolves to a
36//! `version_id` on ingest; an unresolvable reference is accepted and simply
37//! does not earn the `refs_resolved` badge. Targets outside the hub are
38//! written `external:https://…` or `hf:org/repo@sha` and stored with no
39//! `version_id`. `attrs` is free-form per relation type (for `uses_eval`,
40//! which runs of the Eval this Card used).
41//!
42//! Relations are edges between *versions*. Publishing a new version of a
43//! Card does not move its edges; a reader who wants "the latest Card that
44//! used this Eval" asks the API with `follow_latest=true`.
45//!
46//! # `ext`
47//!
48//! The one open door. `ext` is a map from namespace (`{ns}/{name}`) to an
49//! arbitrary JSON object. Namespacing is mandatory so that two producers'
50//! extensions cannot collide, and so that a namespace can later register an
51//! `ext_schema` to make its keys typed and indexable. Until it does, `ext`
52//! values can be searched with `eq` and `exists` only.
53
54use std::collections::BTreeMap;
55
56use schemars::JsonSchema;
57use serde::{Deserialize, Serialize};
58
59/// Producer-private extensions, keyed by namespace (`{ns}/{name}`). Each value
60/// is an arbitrary JSON object owned by that namespace.
61pub type Ext = BTreeMap<String, serde_json::Value>;
62
63/// Free-form attributes carried by a relation, keyed by attribute name.
64pub type Attrs = serde_json::Map<String, serde_json::Value>;
65
66/// True when an extension map is empty; used to omit it on output.
67pub(crate) fn ext_is_empty(ext: &Ext) -> bool {
68    ext.is_empty()
69}
70
71/// The software that wrote the record. Informational; not a facet.
72#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
73#[serde(deny_unknown_fields)]
74pub struct Producer {
75    /// Name of the producing software (a harness, a converter, a script).
76    pub name: String,
77    /// Version of the producing software.
78    pub version: String,
79}
80
81/// A file in object storage that the record refers to by `path`.
82#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
83#[serde(deny_unknown_fields)]
84pub struct Attachment {
85    /// Relative, `..`-free name, unique within the record; other fields point at it.
86    pub path: String,
87    /// Lower-case hex sha256 of the file's bytes; the object's address in storage.
88    pub sha256: String,
89    /// Size of the file in bytes.
90    pub size: u64,
91    /// Media type of the file, for display and download only.
92    #[serde(default, skip_serializing_if = "Option::is_none")]
93    pub media_type: Option<String>,
94}
95
96/// An edge from this version to another record version or an external target.
97#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
98#[serde(deny_unknown_fields)]
99pub struct Relation {
100    /// Relation type as a registry id, `{ns}/{name}` (for example `core/uses_eval`).
101    #[serde(rename = "type")]
102    pub relation_type: String,
103    /// Target: `{ns}/{name}@{seq}` on the hub, or `external:<url>` / `hf:<org>/<repo>@<sha>` outside it.
104    pub to: String,
105    /// Attributes specific to the relation type (for `uses_eval`, which runs were used).
106    #[serde(default, skip_serializing_if = "Option::is_none")]
107    pub attrs: Option<Attrs>,
108}
109
110/// The producer's statement about what it removed before publishing.
111#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, JsonSchema)]
112#[serde(deny_unknown_fields)]
113pub struct Redaction {
114    /// Whether any redaction was applied.
115    pub applied: bool,
116    /// How it was applied (for example `regex+llm`).
117    #[serde(default, skip_serializing_if = "Option::is_none")]
118    pub method: Option<String>,
119    /// Which fields were redacted, as `attachment path:field` or a record path.
120    #[serde(default, skip_serializing_if = "Vec::is_empty")]
121    pub fields: Vec<String>,
122}