docs: core model identity by jakobmoellerdev · Pull Request #771 · open-component-model/ocm-website

jakobmoellerdev · 2026-03-20T09:08:28Z

What this PR does / why we need it

Add two new explanation pages following the Diataxis framework:

Overview > Core Model: accessible intro to OCM's identity model
Concepts > Component Identity: deep technical reference merging
components.md and coordinates.md with descriptor structure details

Delete the thin components.md and coordinates.md pages (content merged),
update all relrefs, and add cross-links from getting-started and tutorials.

Which issue(s) this PR is related to

resolves open-component-model/ocm-project#885

Type of content

Tutorial (getting-started/ or tutorials/)
How-to Guide (how-to/)
Explanation / Concept (concepts/)
Reference (reference/)
Other (infrastructure, config, fixes)

Checklist

I have read and followed the Contributing Guide
All commands/code snippets are tested and can be copy-pasted

Summary by CodeRabbit

Documentation
- Added a new "Component Identity" concept and an "OCM Core Model" overview; removed legacy concept pages and updated guides, tutorials, how‑tos, and related docs to reference the new content (including a new "New to OCM?" tip in the create-component-version guide).
Chores
- Expanded the repository wordlist with new entries (autoscaler, camelcase, filesystems, webshop).

netlify · 2026-03-20T09:08:33Z

✅ Deploy Preview for open-component-model ready!

Name	Link
🔨 Latest commit	`02616dd`
🔍 Latest deploy log	https://app.netlify.com/projects/open-component-model/deploys/69c0f1d607500600087c6e47
😎 Deploy Preview	https://deploy-preview-771--open-component-model.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

coderabbitai · 2026-03-20T09:08:34Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bf0a66a8-61bf-4949-9b90-ea2704039fda

📥 Commits

Reviewing files that changed from the base of the PR and between ea16631 and 02616dd.

📒 Files selected for processing (1)

content/docs/concepts/component-identity.md

✅ Files skipped from review due to trivial changes (1)

content/docs/concepts/component-identity.md

📝 Walkthrough

Walkthrough

Replaced two concept pages with a new "Component Identity" concept, added a new "Core Model" overview, updated cross-references across docs and tutorials to point at the new concept, deleted the legacy concept files, and appended several tokens to the repository wordlist.

Changes

Cohort / File(s)	Summary
New Concept `content/docs/concepts/component-identity.md`	Added a unified concept doc describing component identity, versions, artifact identity, coordinates, component descriptor, CTF, and signing/verification semantics.
Removed Originals `content/docs/concepts/components.md`, `content/docs/concepts/coordinates.md`	Deleted legacy concept pages whose content was merged into `component-identity.md`.
Overview Addition `content/docs/overview/core-model.md`	Added a high-level "OCM Core Model" overview explaining the component envelope, identity/coordinate concepts, descriptor role, and storage/transport examples.
Cross-reference Updates `content/docs/concepts/resolvers.md`, `content/docs/concepts/signing-and-verification-concept.md`, `content/docs/getting-started/create-component-version.md`, `content/docs/how-to/air-gap-transfer.md`, `content/docs/how-to/download-resources-from-component-versions.md`, `content/docs/overview/benefits.md`, `content/docs/overview/how-ocm-works.md`, `content/docs/tutorials/configure-resolvers.md`	Repointed links and navigation entries from the removed `components.md`/`coordinates.md` to the new `component-identity.md`; added a "New to OCM?" tip in the create-component-version guide.
Wordlist `.github/config/wordlist.txt`	Appended new tokens: `autoscaler`, `camelcase`, `filesystems`, and `webshop` (existing other tokens preserved).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

docs: refine credential system documentation #732 — also modifies .github/config/wordlist.txt (overlapping wordlist edits).
chore: Add summaries for section overview pages #734 — also updates .github/config/wordlist.txt (overlapping wordlist edits).
feat(docs): add transfer concept and air-gap transfer guide #744 — touches content/docs/how-to/air-gap-transfer.md and .github/config/wordlist.txt (overlapping docs and wordlist changes).

Suggested labels

area/documentation, kind/chore

Suggested reviewers

morri-son
piotrjanik
frewilhelm

Poem

🐰 I nibble lines and bind them tight,
Merging pages by moonlit light.
New identity, core model spun,
Docs hop forward — work well done.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: core model identity' accurately reflects the main changes: addition of new core model and component identity documentation pages.
Linked Issues check	✅ Passed	The PR successfully addresses all coding/documentation requirements from issue `#885`: created core-model.md overview and component-identity.md concept doc, deleted components.md and coordinates.md, updated all relrefs across the site, and added cross-links to getting-started and tutorials.
Out of Scope Changes check	✅ Passed	All changes are within scope: new documentation pages, deletions of consolidated pages, and link updates across the documentation site. The wordlist.txt expansion is a minor, supporting change for documentation tooling.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

morri-son · 2026-03-20T14:16:44Z

👍🏻 I like the docs, goo to read, easy to follow. We have some overlaps between core model and component identity doc, but since this is about the main attributes a component have, that's hard to keep completely seperate.

Add two new explanation pages following the Diataxis framework: - Overview > Core Model: accessible intro to OCM's identity model - Concepts > Component Identity: deep technical reference merging components.md and coordinates.md with descriptor structure details Delete the thin components.md and coordinates.md pages (content merged), update all relrefs, and add cross-links from getting-started and tutorials. Closes ocm-project#885 Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

Update references across docs to replace "components.md" with "component-identity.md" following concept merge. Add new terms to wordlist. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

- Replace duplicated field tables (Resources, Sources, References, Labels) with concise prose and links to the component descriptor reference. - Replace duplicated Artifact Types and Access Specifications tables with conceptual summaries and reference links. - Replace card-grid sections with simple "Next Steps" lists in both component-identity.md and core-model.md. - Fix wording: use `extraIdentity` attribute (code-formatted). Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/config/wordlist.txt:
- Around line 514-518: Remove the duplicate and case-variant wordlist entries:
delete the lines containing "autocompletion", "terraform", "Untyped", "URI", and
"versionable" from the wordlist so each word appears only once (note aspell is
configured with ignore-case so case variants like "Untyped"/"untyped" and
"URI"/"uri" are redundant); ensure the remaining canonical entries (e.g.,
"autocompletion" at its earlier occurrence, "terraform" at line ~457, "untyped"
at ~478, "uri" at ~484, and "versionable" at ~495) are preserved.

In `@content/docs/overview/core-model.md`:
- Line 28: Update the sentence that currently reads "A **version** following
[SemVer](https://semver.org/) (e.g., `1.0.0`) — each version is an immutable
snapshot." to explicitly state OCM uses "relaxed SemVer": mention that major and
minor are required, patch is optional (e.g., `v2.1`), and a leading `v` is
allowed (e.g., `v1.0.0`), and either replace or augment the semver.org link with
an internal link to the component-identity.md rules (or add a parenthetical
pointing to content/docs/concepts/component-identity.md) so readers see the
exact relaxed SemVer format used by OCM.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 91dab6d3-042d-4f17-9199-9b4acafd2fe6

📥 Commits

Reviewing files that changed from the base of the PR and between 56ad181 and 4412dff.

📒 Files selected for processing (13)

.github/config/wordlist.txt
content/docs/concepts/component-identity.md
content/docs/concepts/components.md
content/docs/concepts/coordinates.md
content/docs/concepts/resolvers.md
content/docs/concepts/signing-and-verification-concept.md
content/docs/getting-started/create-component-version.md
content/docs/how-to/air-gap-transfer.md
content/docs/how-to/download-resources-from-component-versions.md
content/docs/overview/benefits.md
content/docs/overview/core-model.md
content/docs/overview/how-ocm-works.md
content/docs/tutorials/configure-resolvers.md

💤 Files with no reviewable changes (2)

content/docs/concepts/coordinates.md
content/docs/concepts/components.md

morri-son

lgtm 🚀

- Specify relaxed SemVer versions (e.g., `v2.1`). - Add cross-link to the Component Identity page for detailed rules. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

Skarlso

LGTM, I just have one comment which is interesting to me, but otherwise, feel free to ignore if not relevant. :)

frewilhelm

nice read. Just some nits

- Clarify domain ownership in name examples. - Replace relrefs with direct spec link for artifact types. - Simplify CTF archive description while retaining key details. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

#### What this PR does / why we need it Add two new explanation pages following the Diataxis framework: - Overview > Core Model: accessible intro to OCM's identity model - Concepts > Component Identity: deep technical reference merging components.md and coordinates.md with descriptor structure details Delete the thin components.md and coordinates.md pages (content merged), update all relrefs, and add cross-links from getting-started and tutorials. #### Which issue(s) this PR is related to  resolves open-component-model/ocm-project#885 #### Type of content  - [x] Tutorial (`getting-started/` or `tutorials/`) - [ ] How-to Guide (`how-to/`) - [x] Explanation / Concept (`concepts/`) - [ ] Reference (`reference/`) - [ ] Other (infrastructure, config, fixes) #### Checklist - [x] I have read and followed the [Contributing Guide](https://github.com/open-component-model/ocm-website/blob/main/CONTRIBUTING.md) - [ ] All commands/code snippets are tested and can be copy-pasted  ## Summary by CodeRabbit * **Documentation** * Added a new "Component Identity" concept and an "OCM Core Model" overview; removed legacy concept pages and updated guides, tutorials, how‑tos, and related docs to reference the new content (including a new "New to OCM?" tip in the create-component-version guide). * **Chores** * Expanded the repository wordlist with new entries (autoscaler, camelcase, filesystems, webshop).  --------- Signed-off-by: Jakob Möller <contact@jakob-moeller.com> bf995ba

piotrjanik · 2026-03-23T08:22:01Z

+
+## Components and Component Versions
+
+A **component** is a logical unit of software — a frontend, a database, an autoscaler, or an entire application. Components group a set of semantically related **component versions**.


Sounds like CV is always composed of frontend and backend or just complete application.

this is correct.

jakobmoellerdev changed the title ~~Docs/core model identity~~ feat: docs/core model identity Mar 20, 2026

jakobmoellerdev changed the title ~~feat: docs/core model identity~~ docs: core model identity Mar 20, 2026

jakobmoellerdev force-pushed the docs/core-model-identity branch 3 times, most recently from f1b46a9 to 54bb945 Compare March 20, 2026 11:52

morri-son reviewed Mar 20, 2026

View reviewed changes

Comment thread content/docs/overview/core-model.md Outdated

morri-son reviewed Mar 20, 2026

View reviewed changes

Comment thread content/docs/concepts/component-identity.md Outdated

morri-son reviewed Mar 20, 2026

View reviewed changes

Comment thread content/docs/concepts/component-identity.md Outdated

morri-son reviewed Mar 20, 2026

View reviewed changes

Comment thread content/docs/concepts/component-identity.md Outdated

morri-son reviewed Mar 20, 2026

View reviewed changes

Comment thread content/docs/concepts/component-identity.md Outdated

morri-son reviewed Mar 20, 2026

View reviewed changes

Comment thread content/docs/concepts/component-identity.md Outdated

jakobmoellerdev added 3 commits March 20, 2026 16:27

docs: update relrefs to reflect "component identity" page refactor

1b4ebb6

Update references across docs to replace "components.md" with "component-identity.md" following concept merge. Add new terms to wordlist. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

fix: add 'webshop' to spellcheck wordlist

8d245d9

Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

jakobmoellerdev force-pushed the docs/core-model-identity branch 2 times, most recently from d47b92d to 4412dff Compare March 20, 2026 16:19

jakobmoellerdev marked this pull request as ready for review March 20, 2026 16:22

jakobmoellerdev requested a review from a team as a code owner March 20, 2026 16:22

coderabbitai Bot reviewed Mar 20, 2026

View reviewed changes

Comment thread .github/config/wordlist.txt Outdated

Comment thread content/docs/overview/core-model.md Outdated

jakobmoellerdev force-pushed the docs/core-model-identity branch from 4412dff to 52b1148 Compare March 20, 2026 16:27

morri-son previously approved these changes Mar 20, 2026

View reviewed changes

docs: clarify version format in core model overview

ea16631

- Specify relaxed SemVer versions (e.g., `v2.1`). - Add cross-link to the Component Identity page for detailed rules. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

jakobmoellerdev dismissed morri-son’s stale review via ea16631 March 23, 2026 07:11

Skarlso reviewed Mar 23, 2026

View reviewed changes

Comment thread content/docs/concepts/component-identity.md Outdated

Skarlso previously approved these changes Mar 23, 2026

View reviewed changes

frewilhelm reviewed Mar 23, 2026

View reviewed changes

Comment thread content/docs/concepts/component-identity.md Outdated

Comment thread content/docs/concepts/component-identity.md Outdated

docs: refine examples and links in component identity

02616dd

- Clarify domain ownership in name examples. - Replace relrefs with direct spec link for artifact types. - Simplify CTF archive description while retaining key details. Signed-off-by: Jakob Möller <contact@jakob-moeller.com>

jakobmoellerdev dismissed Skarlso’s stale review via 02616dd March 23, 2026 07:54

frewilhelm approved these changes Mar 23, 2026

View reviewed changes

jakobmoellerdev merged commit bf995ba into open-component-model:main Mar 23, 2026
10 checks passed

piotrjanik reviewed Mar 23, 2026

View reviewed changes

This was referenced Mar 23, 2026

feat: typescript/preact based schema renderer #769

Merged

chore: change types to k8s-style Upper Camel Case #785

Closed

chore: add kubernetes deployer concept doc #778

Merged

coderabbitai Bot mentioned this pull request Apr 10, 2026

chore: add governance page and person card component #796

Merged

7 tasks


		## Components and Component Versions

		A component is a logical unit of software — a frontend, a database, an autoscaler, or an entire application. Components group a set of semantically related component versions.

Conversation

jakobmoellerdev commented Mar 20, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this PR does / why we need it

Which issue(s) this PR is related to

Type of content

Checklist

Summary by CodeRabbit

Uh oh!

netlify Bot commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for open-component-model ready!

Uh oh!

coderabbitai Bot commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Suggested reviewers

Poem

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

morri-son commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

morri-son left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Skarlso left a comment

Choose a reason for hiding this comment

Uh oh!

frewilhelm left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

piotrjanik Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

jakobmoellerdev Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jakobmoellerdev commented Mar 20, 2026 •

edited by coderabbitai Bot

Loading

netlify Bot commented Mar 20, 2026 •

edited

Loading

coderabbitai Bot commented Mar 20, 2026 •

edited

Loading

morri-son commented Mar 20, 2026 •

edited

Loading