Where can I find the rationale about why values are included in observables?

[joachimmetz]

I'm trying to map POSIX "struct stat" to CASE/UCO I ran into several challenges that are not clear from existing documentation (or I was unable to locate them). Hope you can assist:

• how do I deal with runtime only values?
• which observable(s) should apply, and why? I found https://caseontology.org/documentation/shape-observableextinodefacet.html and https://caseontology.org/documentation/shape-observablefilesystemobject.html neither seem to map cleanly to "struct stat".
• "observable:ExtInodeFacet" states An extInode facet is a grouping of characteristics unique to a file system object (file, directory, etc.) conformant to the extended file system (EXT or related derivations) specification. where can I find more details how the CASE obsersable (or facet) corresponds to https://docs.kernel.org/filesystems/ext4/inodes.html ? Given technically an inode can contain arbitrary data.
• which values are required and which not? e.g. https://caseontology.org/documentation/shape-observableextinodefacet.html defines "MIN COUNT" but this appears to be 0 for most values. Am I correctly assuming that an empty observable:ExtInodeFacet is valid in CASE/UCO?
• how to deal with different date and time values What is the correct representation for a timestamp? #181 what would be the best convention for timestamp that is 0 (not set) ?
• how to deal with values that combine multiple concepts such as the st_size of a directory vs. that of a file?

For context of what I'm trying to accomplish https://osdfir.blogspot.com/2026/07/case-study-of-comparing-command-line.html

[vulnmaster]

Response created with the assistance of CASE/UCO SDK - https://github.com/vulnmaster/CASE-UCO-SDK

Thanks Joachim — and thanks for the write-up in https://osdfir.blogspot.com/2026/07/case-study-of-comparing-command-line.html. You’re asking exactly the right design question: what is in scope for an observable, and where is that rationale recorded?

Short answer: CASE/UCO does not currently publish a field-by-field rationale that maps struct stat / struct statx / the on-disk EXT inode onto ontology terms. That is a real documentation gap. What we can do is explain the modeling pattern, give a practical mapping for your use case, and point to the historical design trail where it exists.

Design pattern (why it doesn’t look like struct stat)

UCO splits “file entry” metadata across:

1. A host observable (File, FileSystemObject, or plain ObservableObject)
2. One or more facets attached via hasFacet

Cross-filesystem / POSIX-ish attributes that many tools share tend to land on FileFacet. Filesystem-specific attributes land on specialized facets such as ExtInodeFacet (EXT) or NTFSFileFacet / MftRecordFacet (NTFS).

So ExtInodeFacet is intentionally not “everything in an inode / everything in stat.” It is the EXT-specific remainder after the shared file properties have been factored out. That factoring is why neither ExtInodeFacet nor FileSystemObject alone maps cleanly to struct stat.

Historical trail for ExtInodeFacet: ucoProject/UCO#3. Early discussion explicitly considered (and deferred) direct/indirect block pointers on the grounds that deep filesystem meta-provenience was out of scope for the first cut. There is not, unfortunately, a maintained correspondence table to https://docs.kernel.org/filesystems/ext4/inodes.html.

Practical mapping for a POSIX stat / EXT inode baseline

Recommended shape for one file/directory entry:

• Host: File or FileSystemObject (either is fine; File is the common pattern)
• Always (when known): FileFacet
• Additionally when the source is EXT on-disk / EXT-aware tooling: ExtInodeFacet
• Optionally: ContentDataFacet if you also carry hashes / content size separately
• Record the producing tool as Tool + InvestigativeAction (your blog’s point about tool/version in the comparison baseline is important here)

Rough field mapping:

Source concept	Suggested CASE/UCO home
st_size	FileFacet.sizeInBytes
st_atim	FileFacet.accessedTime
st_mtim	FileFacet.modifiedTime
st_ctim	FileFacet.metadataChangeTime (and/or ExtInodeFacet.extInodeChangeTime when emphasizing EXT inode ctime)
birth / crtime (statx stx_btime)	FileFacet.observableCreatedTime
directory vs file	FileFacet.isDirectory (and/or typed host where applicable)
st_ino	ExtInodeFacet.extInodeID
file type bits / mode type	ExtInodeFacet.extFileType
permission bits	ExtInodeFacet.extPermissions
st_nlink	ExtInodeFacet.extHardLinkCount
st_uid / st_gid	ExtInodeFacet.extSUID / extSGID
flags	ExtInodeFacet.extFlags
deletion time (EXT; not in stat)	ExtInodeFacet.extDeletionTime
FS-level I/O / cluster size (st_blksize-ish)	parent FileSystem + FileSystemFacet (e.g. clusterSize), not on the per-inode facet
st_dev (device containing file)	treat as runtime / mount context, not intrinsic inode content — see below
st_blocks	no first-class property today
st_rdev	limited support via special-file classes (BlockDeviceNode / CharacterDeviceNode); not a full major/minor model

So for your normalized “stat observable” JSON, most of the shared fields should go on FileFacet; the EXT-specific identifiers/mode/uid/gid/nlink/flags/deletion fields go on ExtInodeFacet.

Answers to your specific questions

1. Runtime-only values (st_dev, mount-dependent IDs, etc.)
Do not force them onto ExtInodeFacet. Prefer:

• omit them from the inode characterization if the goal is on-disk / tool-independent comparison, or
• attach them to observation context: the InvestigativeAction / mount environment / parent FileSystem object that produced the observation.

That matches the distinction you already draw in the blog: some values are only meaningful when the filesystem is mounted.

2. Which observable, and why?
Use a file-entry host + FileFacet as the baseline. Add ExtInodeFacet only when you are characterizing EXT (or an EXT-derived source). FileSystemObject is a valid host type, but it does not by itself define the stat property set — the facets do.

3. Correspondence to the kernel EXT inode docs
There is no published property-by-property mapping in the CASE/UCO docs today. Closest design history is UCO#3 plus the property comments in observable.ttl. Your point stands: “technically an inode can contain arbitrary data,” and UCO deliberately models a forensically common subset, not the full on-disk structure (block/extent maps were explicitly deferred).

4. Required vs optional / empty ExtInodeFacet
Yes: SHACL minCount 0 means every ExtInodeFacet property is optional, so an empty ExtInodeFacet is syntactically valid. Practically, don’t emit an empty facet — only attach ExtInodeFacet when you have at least one EXT-specific value to record. “Valid” ≠ “useful.”

5. Timestamps / value 0 (“not set”) — related to #181
Best convention in CASE/UCO today:

• represent asserted timestamps as xsd:dateTime / xsd:dateTimeStamp literals on the specific property;
• if the source means unset / not present (e.g. deletion time 0), omit the property rather than serializing Unix epoch or inventing a sentinel;
• preserve original precision when you have it (your granularity-mismatch point in the blog is exactly why).

There is still no general “timestamp with semantics/sentinel” datatype in core UCO (see #181 and Alex’s options there). For rich timestamp provenance (precision, timezone ambiguity, special meanings), communities often keep that beside UCO for now (e.g. dfdatetime-style metadata) or via a local extension — core does not yet standardize that.

6. Combined concepts (directory st_size vs file st_size)
Use the same property: FileFacet.sizeInBytes, and disambiguate with FileFacet.isDirectory=true.
Interpretation rule for consumers/tests: sizeInBytes means “size value as recorded by the filesystem/tool for that entry,” which for directories is directory metadata size, not recursive content size. If a tool chooses to emit 0 for directories as a policy, that is a tool convention to document in the action/tool provenance (and in your comparison rules), not a separate UCO property.

Honest gaps / where rationale is thin

You are right that CASE/UCO currently lacks a clear published rationale for:

• why ExtInodeFacet includes deletion time but not birth time (birth is on FileFacet instead);
• why some inode fields never made it in (st_blocks, generation, project id, etc.);
• how runtime vs on-disk fields should be partitioned;
• how directory size should be compared across tools.

Those are fair issues to track on the UCO side (property selection + mapping notes), with CASE docs/examples as the place to show the recommended composition pattern.

One last thing, there is active discussion within our community about removing facets in CASE/UCO v2.0.0, but that decision has not been made. The idea is that removing facets will make it easier for adopters to do mappings and serializations. The SDK seems to handle it ok, but facets seem to be difficult for humans to work with directly. We would be open to your thoughts on this subject if you'd like to share them here or at an Ontology Committee or Adoption Committee meeting.

If useful, we can next sketch a small exemplar JSON-LD for your inode-22 baseline (File + FileFacet + ExtInodeFacet + Tool/InvestigativeAction) and/or open a UCO issue specifically for a struct stat / EXT inode mapping note. Happy to do either.

[joachimmetz]

Thanks for the detailed reply, looks like having a closer look to "CASE/UCO SDK" could be beneficial.

if the source means unset / not present (e.g. deletion time 0), omit the property rather than serializing Unix epoch or inventing a sentinel;

The reason for "not set" versus omission is to distinguish between (1) value exists but is not set and (2) value does not exist. E.g. apply this to creation time, this allows to distinguish between a tool that does not extract it or is missing from the data, versus the value being not set (0).

One last thing, there is active discussion within our community about removing facets in CASE/UCO v2.0.0, but that decision has not been made. The idea is that removing facets will make it easier for adopters to do mappings and serializations.

How I (currently) read it the facets are an entity component system, which is a perfectly fine approach. Rekall also used it, given it was otherwise very complex to model certain concepts, such as Mac OS intermixed Mach and BSD internals. Entity component system do typically have a bigger learning curve.

My current observation is that examples with rationales could significantly help, but I also realize this is a large amount of work. My reason for looking into CASE/UCO, was to potentially leverage it as a shared baseline, but unfortunately in my case it introduced more questions than answers.

If a tool chooses to emit 0 for directories as a policy, that is a tool convention to document in the action/tool provenance (and in your comparison rules), not a separate UCO property.

I was referring mostly to aspect that size of directory is different conceptually, e.g. stat on Mac OS on HFS+ (for a directory) sets it to a different value than Linux stat on the same file system. IMHO it could be beneficial if CASE/UCO, as an onthology, would indicate a value is affected by such conceptual differences, even if it is just as a side note. I would not see "how directory size should be compared across tools" necessary as part of the onthology, but I would expect it to call out that directory size should not be interpreted the same as file size.

If useful, we can next sketch a small exemplar JSON-LD for your inode-22 baseline (File + FileFacet + ExtInodeFacet + Tool/InvestigativeAction) and/or open a UCO issue specifically for a struct stat / EXT inode mapping note.

Thanks, not urgent for my purpose, the makeshift observable is sufficient for my current needs. However this could be a beneficial example. Also happy to include it in a part of 2 "Case study of comparing command line tools".

[joachimmetz]

Given that this answers most of my questions, feel free to close this issue or split it into separate follow up items.

[joachimmetz]

Maybe interesting side note, there might be more platform/file system intricacies around stat, namely different behavior of st_nlink on Mac OS with APFS versus Linux with btrfs. Where the former shows a link count of 7 (the number of directory entries) and the latter 1 (the number of hard links of the directory file system object) for an equivalent directory structure.