Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add "Validating attribute values" section to user_doc #54

Merged
merged 1 commit into from
Dec 26, 2023
Merged

Add "Validating attribute values" section to user_doc #54

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 41 additions & 0 deletions user_guide.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -310,6 +310,47 @@ definitely not recommended in real-life specs):
NOTE: There's no need to specify `type` or `size` for fixed contents
data — it all comes naturally from the `contents`.

[[valid-values]]
=== Validating attribute values

To ensure attributes in your data structures adhere to expected formats and ranges, Kaitai Struct provides a mechanism for validating attribute values using the `valid` key. This key allows you to define constraints for values, enhancing the robustness of your specifications. Here's how you can enforce these constraints:

* `eq` (or directly `valid: value`): Ensures the attribute value exactly matches the given value.
* `min`: Specifies the minimum valid value for the attribute.
* `max`: Specifies the maximum valid value for the attribute.
* `any-of`: Defines a list of acceptable values, one of which the attribute must match.
* `expr`: An expression that evaluates to true for the attribute to be considered valid.

For most cases, the direct `valid: value` shortcut is preferred for its simplicity, effectively functioning as `valid/eq`.

[source,yaml]
----
seq:
- id: exact_value
type: u1
valid: 0x42 # Shortcut for eq: The only valid value is 0x42

- id: bounded_value
type: u2
valid:
min: 100 # Value must be at least 100
max: 200 # and at most 200

- id: enum_value
type: u4
valid:
any-of: [3, 5, 7] # Value must be one of 3, 5, or 7

- id: calculated_value
type: u4
valid:
expr: _ % 2 == 0 # Value must be even
----

When a value does not meet the specified criteria, Kaitai Struct raises a validation error, halting further parsing. This preemptive measure ensures the data being parsed is within the expected domain, providing a first layer of error handling.

NOTE: The actual implementation of validation checks is language-dependent and may vary in behavior and supported features across different target languages.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand why this note is here - it goes against the principles of Kaitai Struct. Once everything is correctly implemented in all target languages (which may with any KS feature temporarily not be the case, but it's simply the reality that individual target languages are in various stages of development at any point in time), the checks will not vary in behavior across different target languages. The status (passed/failed) of any check in one language must be consistent with the status of the same check in the same situation in any other language, any violation is a bug that will be eventually fixed.

@mblsha Did you have something specific in mind when you wrote this sentence? I've just checked the Valid* tests at https://ci.kaitai.io/ and I don't see any current issues with valid, except for Nim, Perl and Construct (all of which are somewhat niche targets), where valid presumably isn't implemented at all, but I don't see any behavior variations.

I remember that valid still doesn't have type checks (kaitai-io/kaitai_struct_formats#678 (comment)), so perhaps you mean the implications of that.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe what @mblsha meant here was that exception handling by itself is not a universal mechanism by any stretch, and indeed individual exception names and notation will vary widely between languages. That's at least how I interpreted this. I certainly won't argue that we should also have language-dependent explanations on how these validation exceptions (or error codes, or whatever it will manifest in) work for specific languages.


[[var-length-struct]]
=== Variable-length structures

Expand Down