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.

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

feat: Update spec to reflect Artifact ID changes #81

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

alilleybrinker
Copy link
Member

@alilleybrinker alilleybrinker commented Sep 27, 2024

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.

  • 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.

@alilleybrinker alilleybrinker added c-spec Category: Improvements or additions to the OmniBOR specification t-enhancement Type: New feature or request labels Sep 27, 2024
@alilleybrinker alilleybrinker self-assigned this Sep 27, 2024
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 <[email protected]>
@alilleybrinker
Copy link
Member Author

Meeting feedback: split out removal of ADG wording and SHA-1 exclusion into a separate PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
c-spec Category: Improvements or additions to the OmniBOR specification t-enhancement Type: New feature or request
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Define "Mandatory Hashes" and permit additional hashes for Artifact Identifier construction.
1 participant