switchback_traits/model/
entity.rs

1//! Entity bodies and stored entities.
2
3use crate::model::link::{IntraLink, Reference};
4use crate::model::manual::Source;
5use crate::response_severity::ResponseSeverity;
6
7/// One entity as stored in a serialized switchback [`Group`](super::contract::Group).
8#[derive(Clone, Debug, PartialEq, Eq)]
9pub struct StoredEntity {
10    /// Entity name within its group and category.
11    pub name: String,
12    /// Family-specific category slug (mirrors [`EntityCategory::as_str`](crate::traits::EntityCategory::as_str)).
13    pub category: String,
14    /// Human-readable entity title for page headings.
15    pub title: String,
16    /// Leading documentation prose, when present.
17    pub doc: Option<String>,
18    /// Provenance pointer into the switchback source layer, when available.
19    pub source: Option<Source>,
20    /// Structural cross-references in the entity body (schema `$ref`, FQN, etc.).
21    pub refs: Vec<Reference>,
22    /// Prose-level intra-links extracted from `doc` and fence bodies.
23    pub intra_links: Vec<IntraLink>,
24    /// Category-specific payload (mirrors the proto `oneof body`).
25    pub body: EntityBody,
26}
27
28/// Discriminated entity payload mirroring the proto `oneof body`.
29#[derive(Clone, Debug, PartialEq, Eq)]
30pub enum EntityBody {
31    /// RPC or HTTP operation entity.
32    Operation(OperationBody),
33    /// Schema or message type entity.
34    Schema(SchemaBody),
35    /// Async messaging channel entity.
36    Channel(ChannelBody),
37    /// Message payload entity (distinct from schema in some families).
38    Message(MessageBody),
39    /// Standalone parameter entity.
40    Parameter(ParameterBody),
41    /// Standalone response entity.
42    Response(ResponseBody),
43    /// Request body entity.
44    RequestBody(RequestBodyBody),
45    /// Security scheme entity.
46    SecurityScheme(SecuritySchemeBody),
47    /// Service definition entity.
48    Service(ServiceBody),
49    /// Opaque family-specific extension payload.
50    Extension(ExtensionBody),
51}
52
53/// Operation entity body (RPC signature, parameters, responses).
54#[derive(Clone, Debug, Default, PartialEq, Eq)]
55pub struct OperationBody {
56    /// Human-readable operation signature line.
57    pub signature: String,
58    /// Language tag for the fenced code block (e.g. `"protobuf"`, `"yaml"`).
59    pub fence_language: String,
60    /// Fenced source excerpt for the operation definition.
61    pub fence_body: String,
62    /// Parameter references attached to the operation.
63    pub parameters: Vec<ParameterRef>,
64    /// Response references attached to the operation.
65    pub responses: Vec<ResponseRef>,
66    /// Request body attachment when the operation defines one.
67    pub request_body: Option<OperationRequestBodyRef>,
68    /// Protocol-specific invocation metadata (for example HTTP method/path).
69    pub protocols: Vec<crate::model::ProtocolAttachment>,
70}
71
72/// Request body attachment on an [`OperationBody`].
73#[derive(Clone, Debug, PartialEq, Eq)]
74pub struct OperationRequestBodyRef {
75    /// Whether the request body is required.
76    pub required: bool,
77    /// Primary content media type (e.g. `"application/json"`).
78    pub media_type: String,
79    /// Structural reference to the request body schema entity.
80    pub schema_ref: Reference,
81    /// Human-readable schema type label for rendering.
82    pub type_label: String,
83}
84
85/// Schema entity body (type definition with optional properties).
86#[derive(Clone, Debug, Default, PartialEq, Eq)]
87pub struct SchemaBody {
88    /// Language tag for the fenced code block.
89    pub fence_language: String,
90    /// Fenced source excerpt for the schema definition.
91    pub fence_body: String,
92    /// Serialization format hint (e.g. `"application/json"`).
93    pub payload_format: String,
94    /// Object properties when the schema represents a structured type.
95    pub properties: Vec<Property>,
96}
97
98/// Channel entity body (async messaging endpoint).
99#[derive(Clone, Debug, Default, PartialEq, Eq)]
100pub struct ChannelBody {
101    /// Human-readable channel signature line.
102    pub signature: String,
103    /// Language tag for the fenced code block.
104    pub fence_language: String,
105    /// Fenced source excerpt for the channel definition.
106    pub fence_body: String,
107}
108
109/// Message entity body (payload type excerpt).
110#[derive(Clone, Debug, Default, PartialEq, Eq)]
111pub struct MessageBody {
112    /// Language tag for the fenced code block.
113    pub fence_language: String,
114    /// Fenced source excerpt for the message definition.
115    pub fence_body: String,
116}
117
118/// Parameter entity body (location, requirement, schema excerpt).
119#[derive(Clone, Debug, Default, PartialEq, Eq)]
120pub struct ParameterBody {
121    /// Parameter name.
122    pub name: String,
123    /// Parameter location (e.g. `"query"`, `"path"`, `"header"`).
124    pub location: String,
125    /// Whether the parameter is required.
126    pub required: bool,
127    /// Language tag for the fenced code block.
128    pub fence_language: String,
129    /// Fenced source excerpt for the parameter schema.
130    pub fence_body: String,
131    /// Protocol-specific parameter metadata (for example HTTP header location).
132    pub protocols: Vec<crate::model::ProtocolAttachment>,
133}
134
135/// Response entity body (status, media type, schema excerpt).
136#[derive(Clone, Debug, Default, PartialEq, Eq)]
137pub struct ResponseBody {
138    /// HTTP or RPC status label.
139    pub status: String,
140    /// Outcome severity class derived from the status at populate time.
141    pub severity: ResponseSeverity,
142    /// Response media type when applicable.
143    pub media_type: String,
144    /// Language tag for the fenced code block.
145    pub fence_language: String,
146    /// Fenced source excerpt for the response schema.
147    pub fence_body: String,
148    /// Protocol-specific response or error metadata.
149    pub protocols: Vec<crate::model::ProtocolAttachment>,
150}
151
152/// Request body entity (requirement flag and schema excerpt).
153#[derive(Clone, Debug, Default, PartialEq, Eq)]
154pub struct RequestBodyBody {
155    /// Whether the request body is required.
156    pub required: bool,
157    /// Language tag for the fenced code block.
158    pub fence_language: String,
159    /// Fenced source excerpt for the request body schema.
160    pub fence_body: String,
161    /// Protocol-specific request body metadata when applicable.
162    pub protocols: Vec<crate::model::ProtocolAttachment>,
163}
164
165/// Security scheme entity body.
166#[derive(Clone, Debug, Default, PartialEq, Eq)]
167pub struct SecuritySchemeBody {
168    /// Scheme type label (e.g. `"apiKey"`, `"oauth2"`).
169    pub scheme_type: String,
170    /// Language tag for the fenced code block.
171    pub fence_language: String,
172    /// Fenced source excerpt for the security scheme definition.
173    pub fence_body: String,
174}
175
176/// Service definition entity body.
177#[derive(Clone, Debug, Default, PartialEq, Eq)]
178pub struct ServiceBody {
179    /// Human-readable service signature line.
180    pub signature: String,
181    /// Language tag for the fenced code block.
182    pub fence_language: String,
183    /// Fenced source excerpt for the service definition.
184    pub fence_body: String,
185}
186
187/// Opaque family-specific extension entity body.
188#[derive(Clone, Debug, PartialEq, Eq)]
189pub struct ExtensionBody {
190    /// Family-defined extension type identifier.
191    pub extension_type: String,
192    /// Opaque extension payload bytes.
193    pub payload: Vec<u8>,
194    /// Optional language tag when a fenced excerpt is also provided.
195    pub fence_language: Option<String>,
196    /// Optional fenced source excerpt for human-readable rendering.
197    pub fence_body: Option<String>,
198}
199
200/// One property on a schema-like entity, pointing at another entity via [`Reference`].
201#[derive(Clone, Debug, PartialEq, Eq)]
202pub struct Property {
203    /// Property field name.
204    pub name: String,
205    /// Structural reference to the property's schema entity.
206    pub schema_ref: Reference,
207    /// Whether the property is required on the parent type.
208    pub required: bool,
209}
210
211/// Parameter attachment on an [`OperationBody`], referencing a schema entity.
212#[derive(Clone, Debug, PartialEq, Eq)]
213pub struct ParameterRef {
214    /// Parameter name.
215    pub name: String,
216    /// Parameter location (e.g. `"query"`, `"path"`).
217    pub location: String,
218    /// Whether the parameter is required.
219    pub required: bool,
220    /// Structural reference to the parameter schema entity.
221    pub schema_ref: Reference,
222    /// Human-readable schema type label for rendering (e.g. `"string"`, `"coordinate"`).
223    pub type_label: String,
224    /// OpenAPI parameter description prose, when present.
225    pub description: String,
226    /// Protocol-specific parameter metadata.
227    pub protocols: Vec<crate::model::ProtocolAttachment>,
228}
229
230/// Response attachment on an [`OperationBody`], referencing a schema entity.
231#[derive(Clone, Debug, PartialEq, Eq)]
232pub struct ResponseRef {
233    /// HTTP or RPC status label.
234    pub status: String,
235    /// Outcome severity class derived from the status at populate time.
236    pub severity: ResponseSeverity,
237    /// Structural reference to the response schema entity.
238    pub schema_ref: Reference,
239    /// Response media type when applicable.
240    pub media_type: String,
241    /// OpenAPI response description prose, when present.
242    pub description: String,
243    /// Protocol-specific response or error metadata.
244    pub protocols: Vec<crate::model::ProtocolAttachment>,
245}
switchback_traits/model/entity.rs

switchback_traits/model/
entity.rs
