The high-level explanation of what OmniBOR is.

[alilleybrinker]

Had a conversation this morning which has crystallized my sense of how best to explain OmniBOR, and it goes like this:

You start out with identifiers, Artifact Identifiers (implemented as GitOIDs), which are hashes of whatever artifacts you have related to your software. Could be source files, configuration files, object files created during a build, the final executable made after linking, or anything else. These Artifact Identifiers give you a consistent, independently reproducible way to identify these objects. However, these identifiers only give you identity, no relationship or knowledge of how artifacts relate to one another in a build.

So next you have an Artifact Input Manifest, one for each object which is built using some inputs. Objects which are created without prior inputs don't have an Artifact Input Manifest, but anything with prior inputs does get a Manifest. Manifests may be in their own file, or they may be embedded within the file whose build inputs they describe. Each Manifest lists, in a canonical order, the Artifact Identifier of each build input for the object the Manifest describes. Each Manifest, whether in its own file or embedded, also has its own Artifact Identifier based on the Manifest's contents. Manifest listings only ever show one "layer" of dependencies; if an input to the object being described has its own inputs, then the object's Manifest simply notes that its input has its own Manifest.

You can then take a collection of objects and manifests and construct an Artifact Dependency Graph which describes the full graph of inputs which produce an artifact. This is a directed acyclic graph (DAG), not a tree.

So, when distributing a software artifact like an executable, you can also distribute its Manifest (either separately or embedded). Whenever an input anywhere in that artifact's Artifact Dependency Graph changes, the hashes for all Manifests of objects which use the changed input are themselves changed. This creates a clear signal of supply chain input changes, and allows comparison of two sets of artifacts and manifests to identify what specific differences exist in their inputs.

---

All of this said, I think this gives a clear way to explain OmniBOR to others:

1. Explain Artifact Identifiers
2. Explain Artifact Input Manifests
3. Explain Artifact Dependency Graphs

EDIT: The terms above where changed from OmniBor Identifier to Artifact Identifier, and from OmniBOR Manifest to Artifact Input Manifest, based on the conversations with Ed below.

[edwarnicke]

I like the overall a structure of this.

It builds nicely from “There are things” to “We should probably identify them” to “We should probably capture their relationships”

[alilleybrinker]

Thanks! Yeah in particular this was the culmination of an effort to explain OmniBOR without referencing SBOMs, Git, or other related topics. Explaining it as a standalone thing then makes it easier to relate to other things, in my opinion 😄.

[edwarnicke]

Good way to explain things :)

[edwarnicke]

How might we project this sort of messaging into our website?

[alilleybrinker]

Oh that part doesn't really matter to me. I figure OmniBOR Identifier is more specific, as people may have other artifact identifier schemes they're familiar with.

[edwarnicke]

Got it :) I am also liking the Manifest bits... thoughts an Artifact Input Manifest?

[alilleybrinker]

Hmm, there is a nice consistency to have:

• Artifact Identifier
• Artifact Input Manifest
• Artifact Dependency Graph

[edwarnicke]

I also like that they are kind of self describing terms. If I tell someone "OmniBOR Manifest" I don't feel like they'd guess correctly what it is. "Artifact Input Manifest (AIM)" I suspect folks could get close :)

[alilleybrinker]

Yeah, I think I am becoming convinced that these are the right terms!

[alilleybrinker]

Jeremy has raised the question of whether "Artifact Input Manifest" confuses the target of the "input," because the inputs aren't to the artifact, but to a process which produces the artifact. This may need some workshopping.

[yonhan3]

Jeremy has raised the question of whether "Artifact Input Manifest" confuses the target of the "input," because the inputs aren't to the artifact, but to a process which produces the artifact. This may need some workshopping.

How about Build Input Manifest (BIM) instead of Artifact Input Manifest?

[alilleybrinker]

I perhaps like Artifact Build Input Manifest better (if only for symmetry with the other two terms of art also starting with "Artifact"), but I do think that including "Build" is a good direction.

[jsgf]

I don't have really strong problems with "Artifact Input Manifest". My comments were mostly thinking out loud. I feel it's important when making up specific terms like this that 1) every word counts, and 2) a reasonably informed (but not necessarily expert) reader will get roughly the right meaning.

So 1) means that we should consider just "Input Manifest" as a term - does this need more qualification to be clearer? Perhaps not. 2) prompts us to ask that, assuming we do need a word there, is "Artifact" the best one?

Ideas:

• Artifact Input Manifest (current proposal)
• Build Input Manifest (alternative)
• Input Manifest (simplest)
• Action Input Manifest (re "build tool" vs "build action" in (More) General spec comments #36 )

With that list I'm leaning towards "Input Manifest" not needing any other words to make its meaning clear. It also means we can add qualifying words later if we end up having multiple different kinds of input manifest.

[yonhan3]

I am fine with Input Manifest. I like it too since it is the simplest.

[alilleybrinker]

There seems to be general positive feelings about the use of the "Manifest" over other terms we've considered like "Document". The sense is that "Manifest" is both 1) more specific than "Document," and also 2) more consistent with other supply chain and real-world shipping terminology.

[yonhan3]

Yes, I like "Manifest" much better than "Document".

[alilleybrinker]

This is also connected to our ongoing discussion of rewriting the spec introduction: #30

[alilleybrinker]

Given that this new language has been adopted into the spec and into our public communication about OmniBOR, I'm going to close this thread. Of course new ones can be opened up if new angles or points of contention ought to be raised.