Skip to content

Align markdown docs with OpenAPI specfication - #260

Open
oej wants to merge 11 commits into
CycloneDX:mainfrom
oej:doc-update
Open

oej wants to merge 11 commits into
CycloneDX:mainfrom
oej:doc-update

Conversation

@oej

@oej oej commented Aug 26, 2026

Copy link
Copy Markdown
Collaborator
  • Remove duplicate text
  • Move text that's ended up in the wrong doc

@oej
oej requested a review from madpah as a code owner August 26, 2026 10:24
@oej oej added the Prio 1 label Aug 26, 2026
oej added a commit to oej/transparency-exchange-api that referenced this pull request Aug 31, 2026
this means that this PR will have to go in after CycloneDX#260
Signed-off-by: Olle E. Johansson <oej@edvina.net>
@taleodor

taleodor commented Sep 4, 2026

Copy link
Copy Markdown
Contributor

Some inconsistencies in this PR:

  • The datecreatedDate rename on the collection hits the schema only. Both spec examples still say date, and the collection markdown's JSON example does too, while its field list now says createdDate. Openapi require changes #264 makes the identical rename, so the two PRs conflict on the same hunk.
  • The moved release documentation uses distributionType throughout its prose and JSON examples, while the new "key attributes" list correctly says distributionId, which is the schema property. The examples lack the required distributionId, so they fail the schema the PR aligns with. The artifact section of the collection doc has the same split.
  • The pre-release text was moved into the product-release doc verbatim from the component doc, so the product-release page now explains pre-releases in terms of "creating the Component with a new UUID". The release doc gets a different, divergent description of the same flag.
  • Spec examples switch to tei://, but the component doc's new sentence still says "TEI URNs", and the product-release markdown example still uses a third form, tei:vendor:product@2.24.3.
  • The date-time description now claims RFC 9557, while the pattern on the next line only admits YYYY-MM-DDTHH:MM:SSZ. The description and the regex disagree.
  • Moved checksum examples use SHA_256 and SHA_512 with underscores. The enum is hyphenated, so those examples fail validation. Pre-existing, but the PR copies them forward as the aligned version.
  • The discovery example ends with an encoded newline, %0A, which is an invalid value regardless of the URN-versus-URL decision.

Overlap with #262

This PR rewrites the artifact-format url / signatureUrl descriptions in the spec and the matching mediaType / url / signatureUrl bullets in tea-collection.md, which are exactly the lines #262 changes (mediaType required; url and signatureUrl always external and optional, with the server's download endpoints used when absent). Here url is left unmarked next to signatureUrl (optional), which reads as required, so it's a semantic disagreement as well as a merge conflict. Suggest rebasing this on #262 once it lands and taking those bullets from there, so the docs end up consistent with the download endpoints.

oej added a commit to oej/transparency-exchange-api that referenced this pull request Sep 12, 2026
this means that this PR will have to go in after CycloneDX#260
Signed-off-by: Olle E. Johansson <oej@edvina.net>
oej added a commit to oej/transparency-exchange-api that referenced this pull request Sep 15, 2026
this means that this PR will have to go in after CycloneDX#260
Signed-off-by: Olle E. Johansson <oej@edvina.net>
oej added 8 commits September 15, 2026 15:37
Signed-off-by: Olle E. Johansson <oej@edvina.net>
Signed-off-by: Olle E. Johansson <oej@edvina.net>
Signed-off-by: Olle E. Johansson <oej@edvina.net>
Signed-off-by: Olle E. Johansson <oej@edvina.net>
- add release distribution object

Signed-off-by: Olle E. Johansson <oej@edvina.net>
Signed-off-by: Olle E. Johansson <oej@edvina.net>
Signed-off-by: Olle E. Johansson <oej@edvina.net>
Signed-off-by: Olle E. Johansson <oej@edvina.net>
@oej

oej commented Sep 15, 2026

Copy link
Copy Markdown
Collaborator Author

Fixed some comments, waiting for #262 for another review

oej added 3 commits September 15, 2026 15:50
Signed-off-by: Olle E. Johansson <oej@edvina.net>
Signed-off-by: Olle E. Johansson <oej@edvina.net>
Signed-off-by: Olle E. Johansson <oej@edvina.net>
oej added a commit to oej/transparency-exchange-api that referenced this pull request Sep 16, 2026
this means that this PR will have to go in after CycloneDX#260
Signed-off-by: Olle E. Johansson <oej@edvina.net>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants