fix(typedef): fix code examples and cross-doc inconsistencies from second review
- Fix code examples hardcoding little-endian: read_string, write_string, read_string_indirect now take endian parameter and use match on Endian. - Fix TUnion dispatch examples: remove undefined functions (read_u8, read_field, read_struct, read_f32_raw), remove Value returns (contradicts 'no intermediate Value tree'), add endian-aware discriminator reading for Uint8/Uint16/Uint32. - Fix read_f32 example: inline the endian-aware conversion instead of calling undefined read_f32_raw; document it as aligned-mode only. - Fix architecture README: 16→17 kinds in schema-layer and validation descriptions. - Fix ADR-095: clarify validation operates on Value instances, not raw byte buffers directly. Fix 'defense in depth' paragraph. - Fix ADR-097: add §3a defining TRecord 'values' property shape. - Fix ADR-098: TTimestamp format ISO 8601→RFC 3339. - Tighten OQ-071 impacts field: state what IS blocked, not just what isn't.
This commit is contained in:
1 parent
01cc3a0367
commit
dd232c3d47
6 files changed
+172
-50
No files matched your search
@@ -65,8 +65,12 @@ functions, and validation — all driven by the schema.
|
||||
2. **Read/write functions** — given a `&[u8]` buffer and a field path,
|
||||
read the field's bytes at its offset (zero-copy for fixed-size types).
|
||||
Given a `&mut [u8]` buffer, write a value at its offset.
|
||||
3. **Validation** — via `jsonschema` custom keywords, validates that a
|
||||
buffer's bytes match the schema's type constraints.
|
||||
3. **Validation** — via `jsonschema` custom keywords, validates that data
|
||||
conforms to the schema's type constraints. The jsonschema validator
|
||||
operates on `serde_json::Value` instances (JSON representations), not
|
||||
raw byte buffers directly. A consumer that wants to validate a binary
|
||||
buffer reads it into a `Value` tree via the data access layer, then
|
||||
validates that `Value` against the jsonschema validator.
|
||||
|
||||
**The heavy lifting is done by the `jsonschema` crate (validation) and
|
||||
`serde_json` (schema parsing).** The novel code is the offset computation
|
||||
@@ -114,10 +118,11 @@ read/write) is already allocation-free. See OQ-070.
|
||||
under `$defs`. That JSON feeds directly into `jsonschema::validator_for`
|
||||
on the Rust side. Zero translation. The same schema validates in both
|
||||
ecosystems.
|
||||
- **Defense in depth.** Schema validation at the byte level — a malformed
|
||||
binary payload fails validation before any consumer touches it. The
|
||||
`jsonschema` crate's compiled validators are fast enough to run on
|
||||
every incoming frame.
|
||||
- **Defense in depth.** Schema validation via jsonschema custom keywords —
|
||||
a malformed binary payload can be read into a `Value` tree via the data
|
||||
access layer and validated against the schema before any consumer
|
||||
touches it. The `jsonschema` crate's compiled validators are fast enough
|
||||
to run on every incoming frame.
|
||||
|
||||
### Negative
|
||||
|
||||
|
||||
@@ -129,6 +129,26 @@ reserving worst-case space.
|
||||
types: `TypeDef:String`, `TypeDef:Bytes`, `TypeDef:Array`,
|
||||
`TypeDef:Record`, `TypeDef:Timestamp`.
|
||||
|
||||
### 3a. TRecord value type
|
||||
|
||||
`TypeDef:Record` is a string-keyed map. The value type is declared via
|
||||
the `"values"` property in the schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"TypeDef:Record": true,
|
||||
"values": { "TypeDef:Float32": true }
|
||||
}
|
||||
```
|
||||
|
||||
- `"values"` is a schema object declaring the `TypeDef:*` kind of all
|
||||
values in the record. All values share the same type.
|
||||
- The binary layout is a count-prefixed sequence of `(key, value)` pairs:
|
||||
`[count: u32][key_len: u32][key_bytes][value_len: u32][value_bytes]...`.
|
||||
- The count prefix respects the schema's endianness.
|
||||
- In aligned static mode with `maxLength`, the entire record is reserved
|
||||
at `maxLength` bytes (zero-padded).
|
||||
|
||||
### 4. TUnion discriminators
|
||||
|
||||
**Two discriminator kinds: byte-offset (protocol dispatch) and
|
||||
|
||||
@@ -95,7 +95,7 @@ Each `TypeDef:*` kind gets a `Keyword` implementation registered via
|
||||
- **`TypeDef:Union`**: discriminator value membership in the mapping.
|
||||
- **`TypeDef:Array`**: element type conformance.
|
||||
- **`TypeDef:Boolean`**: value is `true` or `false`.
|
||||
- **`TypeDef:Timestamp`**: ISO 8601 string format.
|
||||
- **`TypeDef:Timestamp`**: RFC 3339 string format (the internet profile of ISO 8601).
|
||||
|
||||
The `jsonschema` crate handles all the structural validation (object
|
||||
properties, required fields, array items, enum values) — the custom
|
||||
|
||||
Reference in new issue
Block a user