feat: Update spec to reflect Artifact ID changes #81
Conversation
alilleybrinker
added
c-spec
alilleybrinker
requested review from
dpp,
fkautz,
jsgf,
AevaOnline,
ashleygwilliams and
edwarnicke
Over an extensive number of OmniBOR Working Group meetings, we've discussed a number of changes to the OmniBOR specification, specifically around the design of Artifact IDs, which had not yet been reflected in the spec. This change now incorporates those changes, plus several others, which I will attempt to delineate below. - Reduce supported hash algorithms for Artifact IDs to explicitly exclude SHA-1, and thus only support SHA-256, while reserving the right in the future to extend the list if, for example, SHA-256 is found to be broken. - Eliminating use of the term "Input Manifest Identifier," which I believe muddies the conceptual picture of OmniBOR as being about only two relevant objects: Artifact IDs and Input Manifests. - Brings all annexes into the main document. - Assigns numbers to all sections and subsections to make referencing specific parts of the specification easier. - Many formatting and grammatical corrections, including more consistent use and capitalization of terminology, many fixes to Markdown formatting, adjustments to (outside of code blocks) ensure we remain within an 80-character column limit, and more. - Updates to the filesystem storage definition to reflect use of a target index and a renaming of the "objects/" folder to "manifests/" - Updates to the Input Manifest format to no longer include a "blob " prefix, and _without_ use of the "input type" concept I had experimented with in the Rust implementation. After discussion with the WG I have concluded that this additional piece of metadata in the input format is a mistake. - Removal of the specification for the OmniBOR metadata fields. These may be returned in the future if we deem them truly necessary, but I have removed them here as I believe from our discussions that they are quite underbaked and indicative of some scope creep we would do well to avoid. - Clarification of rules around ELF embedding and text file embedding. - Removal of specification of the Artifact Dependency Graph beyond the introduction. The Artifact Dependency Graph is a key conceptual part of OmniBOR, as the ability to construct it is the fruit of our labor in defining Artifact IDs and Input Manifests as they are defined. That said, it is not necessary to specify here beyond the conceptual, and attempting to do so is likely to bog us down in extra complexity we can otherwise avoid. One notable item I did _not_ pursue in this set of changes, per discussion with the Working Group, is to change the textual representation of Artifact IDs from `gitoid` URI scheme to a new `artifactid` URI scheme. I still think such a change could be worthwhile, but also that it would warrant more discussion than it has received so far, and should not block progress on the other changes. Altogether, my goal here is to bring the spec more up to date with the discussions happening in the Working Group, and more generally to make it easier for others to understand and build on OmniBOR by solidifying more of the foundations of the project. Signed-off-by: Andrew Lilley Brinker <alilleybrinker@gmail.com>
alilleybrinker
force-pushed
the
alilleybrinker/structure
branch
from
2134c7e to
09ec42a
Compare
|
Meeting feedback: split out removal of ADG wording and SHA-1 exclusion into a separate PR. |
| whose inputs they describe. | ||
| can be identified by their own Artifact Identifier. The Artifact ID for the | ||
| manifest can be embedded directly into executable files, or can be provided | ||
| in a separate file alongside the artifact whose inputs they describe. |
There was a problem hiding this comment.
I have a slight concern that removing the IMID as a concept itself introduces confusion. Given an artifact... one would like a simple way to distinguish conversationally between the artifact id of the artifact, and the artifact id of the input manifest of the artifact. Artifact ID and Input Manifest ID (IMID) filled that role. We introduced the concept because we had confusion downstream by communities like SPDX as to whether the artifact id field for an artifact should be the artifact id of the artifact or the artifact id of the artifacts input manifest.
There was a problem hiding this comment.
Possible idea: "Input Manifest ID" -> "Input Manifest AID"
"AID" being a shorthand for "Artifact ID". This would be a new shorthand, but hopefully makes it clearer that we're discussing the Artifact ID of the Input Manifest, and not some new type of ID.
|
|
||
| Two artifacts are equivalent if and only if their binary representations are | ||
| equal. This can be expressed in pseudocode with the following expression: | ||
| `[]byte(artifact1) == []byte(artifact2)` | ||
| equal. |
There was a problem hiding this comment.
bytewise identical. This rewrite reads a bit too much like "two artifacts are equivalent of they are equal".
There was a problem hiding this comment.
I can reintroduce the byte-equivalence language, but without the Go-ish pseudocode.
There was a problem hiding this comment.
For all n less than the length in bytes of the artifact artifact1[n] == artifact2[n] as bytes.
| - Node.js | ||
| - Python interpreter | ||
| - __Code Generators__ | ||
|
|
There was a problem hiding this comment.
Could we work patch into here?
There was a problem hiding this comment.
Looks like the use of colons is also inconsistent, I ought to fix that.
|
|
||
| This index file may then be used to improve the performance and reliability of | ||
| operations related to Input Manifests. | ||
|
|
There was a problem hiding this comment.
Did I miss something here about how to persist these targets in a way we can look them up easily?
There was a problem hiding this comment.
Based on discussion I am inclined to remove this section for now while we gather more experience and figure out what makes more sense.
|
Update from yesterday's WG meeting: I'll be going through and addressing Ed's comments, including backing out some less-baked sections of the edits, which will have issues opened for them. |
Rendered Changes
Closes #74, #70, #59, #60, #53
Over an extensive number of OmniBOR Working Group meetings, we've discussed a number of changes to the OmniBOR specification, specifically around the design of Artifact IDs, which had not yet been reflected in the spec. This change now incorporates those changes, plus several others, which I will attempt to delineate below.
One notable item I did not pursue in this set of changes, per discussion with the Working Group, is to change the textual representation of Artifact IDs from
gitoidURI scheme to a newartifactidURI scheme. I still think such a change could be worthwhile, but also that it would warrant more discussion than it has received so far, and should not block progress on the other changes.Altogether, my goal here is to bring the spec more up to date with the discussions happening in the Working Group, and more generally to make it easier for others to understand and build on OmniBOR by solidifying more of the foundations of the project.