kosli-dev · dangrondahl · Dec 5, 2025 · Dec 5, 2025 · Dec 5, 2025
diff --git a/...mplementation_guide/phase_2/plan_organizational_structure/naming_conventions.md b/...mplementation_guide/phase_2/plan_organizational_structure/naming_conventions.md
diff --git a/...tation_guide/phase_2/plan_organizational_structure/naming_conventions/_index.md b/...tation_guide/phase_2/plan_organizational_structure/naming_conventions/_index.md
@@ -0,0 +1,85 @@
+---
+title: "Naming Conventions"
+bookCollapseSection: true
+weight: 100
+---
+
+# Naming Conventions
+
+Clear and consistent naming makes it easy for everyone to understand what each item in Kosli represents. Good names help you route attestations correctly and quickly find what you need.
+
+Use these conventions for:
+- **Flows** and **Trails**
+- **Attestation Types**
+- **Environments**
+
+## General Guidelines
+
+The general guidelines should be considered best practices for all naming conventions in Kosli. You can adapt them to fit your organization’s needs, but consistency is key. All of our proposed conventions follow these general guidelines:
+
+**Structure**: `<element 1>` `<delimiter>` `<element 2>` `<delimiter>`...`<element N>`
+
+
+1. **Choose Delimiter**: Choose a delimiter that works for your and stick with it consistently.</br>
+For example hyphen `-`, underscore `_`, tilde `~` or dot `.`. </br>
+Avoid mixing delimiters within the same naming scheme.
+2. **Choose case style for elements**: Choose a meaningful case style across elements (e.g., PascalCase, camelCase, snake_case) and use it consistently. Avoid spaces and clashes with delimiters.
+3. **Keep it concise**: Shorter names are easier to read and remember. Aim for concise but descriptive names.
+4. **Avoid special characters**: Stick to alphanumeric characters and underscores/hyphens
+
+{{% hint warning %}}
+Be aware of using underscore `_` as the delimiter, as that conflicts with snake_case for elements.
+{{% /hint %}}
+
+{{% hint info %}}
+The rest of this document uses hyphen `-` as the delimiter in examples, but you can choose any delimiter that fits your needs.
+{{% /hint %}}
+
+### Regular Expression
+
+To help enforce these conventions programmatically, here are sample regular expressions you can use based on your chosen case style.
+
+Adjust the regex if you choose a different delimiter.
+
+{{< tabs "naming-regex" >}}
+{{< tab "snake_case" >}}
+
+**Example**: `element_one`-`element_two`-`element_three`
+
+```bash
+^[a-z][a-z0-9_]*(-[a-z][a-z0-9_]*)*$
+```
+
+{{< /tab >}}
+{{< tab "camelCase" >}}
+
+**Example**: `elementOne`-`elementTwo`-`elementThree`
+
+```bash
+^[a-z][a-zA-Z0-9]*(-[a-z][a-zA-Z0-9]*)*$
+```
+
+{{< /tab >}}
+{{< tab "PascalCase" >}}
+
+**Example**: `ElementOne`-`ElementTwo`-`ElementThree`
+
+```bash
+^[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*$
+```
+{{< /tab >}}
+{{< /tabs >}}
+
+
+{{% hint info %}}
+If you want a specific length limit (e.g., max 50 characters), you can add a lookahead at the start of the regex:
+
+```bash
+^(?=.{1,50}$) # + rest of the regex
+```
+
+You can use online regex testers like [regex101](https://regex101.com/) to validate and test these expressions.
+
+{{% /hint %}}
+
+## Subpages
diff --git a/...e/phase_2/plan_organizational_structure/naming_conventions/attestation_types.md b/...e/phase_2/plan_organizational_structure/naming_conventions/attestation_types.md
@@ -0,0 +1,76 @@
+---
+title: "Attestation Types"
+bookCollapseSection: false
+weight: 300
+---
+
+# Attestation Types
+
+Use clear, descriptive names for custom attestation types to indicate what kind of evidence they represent.
+
+Naming convention relates to `TYPE-NAME` in Kosli CLI command:
+
+```bash
+kosli create attestation-type TYPE-NAME [flags]
+```
+
+See [CLI documentation]({{< ref "client_reference/kosli_create_attestation-type" >}}) for more details.
+
+**Name Convention:** `control objective`-`evidence type`-`[detail]`-`[version]`
+
+- **control objective**: The high-level control or requirement the attestation supports (e.g., control id, code review, security scan, unit test)
+- **evidence type**: The specific type of evidence being attested (e.g. tool-name, test-suite)
+- **detail (Optional)**: Additional context or detail about the attestation (e.g., type, severity-level, environment, etc.)
+- **version (Optional)**: The version of the attestation type or schema. Should follow semantic versioning (e.g., v1, v2)
+
+{{% hint info %}}
+
+- `detail` element may be repeated to add finer granularity if needed.
+- You can skip `detail` and `version` if not needed for your use case.
+- Kosli versions attestation types automatically, so `version` is often unnecessary. However, it can be useful for multiple version running at the same time, for example in shared pipelines.
+{{% /hint %}}
+
+{{< tabs "attestation-type-examples" >}}
+{{< tab "snake_case" >}}
+
+**Examples on `TYPE-NAME`:**
+- `bc1-version_control-v1` (BC1 version control attestation, version 1)
+- `code_review-github-pr` (basic code review attestation)
+- `security_scan-snyk-high` (Custom schema for Snyk scan with high severity detail)
+- `unit_test-junit-detail1-detail2-v2` (Multiple detail blocks with version)
+
+**Regex:**
+
+```bash
+^[a-z][a-z0-9_]*-[a-z][a-z0-9_]*(-[a-z][a-z0-9_]*)*(-v[1-9][0-9]*)?$
+```
+
+{{< /tab >}}
+{{< tab "camelCase" >}}
+**Examples on `TYPE-NAME`:**
+- `bc1-versionControl-v1` (BC1 version control attestation, version 1)
+- `codeReview-github-pr` (basic code review attestation)
+- `securityScan-snyk-high` (Custom schema for Snyk scan with high severity detail)
+- `unitTest-junit-detail1-detail2-v2` (Multiple detail blocks with version)
+
+**Regex:**
+
+```bash
+^[a-z][a-zA-Z0-9]*-[a-z][a-zA-Z0-9]*(-[a-z][a-zA-Z0-9]*)*(-v[1-9][0-9]*)?$
+```
+{{< /tab >}}
+{{< tab "PascalCase" >}}
+
+**Examples on `TYPE-NAME`:**
+- `Bc1-VersionControl-V1` (BC1 version control attestation, version 1)
+- `CodeReview-Github-Pr` (basic code review attestation)
+- `SecurityScan-Snyk-High` (Custom schema for Snyk scan with high severity detail)
+- `UnitTest-Junit-Detail1-Detail2-V2` (Multiple detail blocks with version)
+
+**Regex:**
+
+```bash
+^[A-Z][a-zA-Z0-9]*-[A-Z][a-zA-Z0-9]*(-[A-Z][a-zA-Z0-9]*)*(-V[1-9][0-9]*)?$
+```
+{{< /tab >}}
+{{< /tabs >}}