Skip to content

docs: update Terraform reference: custom_attestation_type summary attribute #372

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.

Sign up for GitHub

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

Merged
dangrondahl merged 1 commit into from
Aug 25, 2026
Merged

docs: update Terraform reference: custom_attestation_type summary attribute #372

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions terraform-reference/data-sources/custom_attestation_type.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,9 @@ resource "kosli_custom_attestation_type" "security_strict" {
name = "security-scan-strict"
description = "Stricter security requirements"

# Reuse the schema from the existing type
schema = data.kosli_custom_attestation_type.security.schema
# Reuse the schema and summary rows from the existing type
schema = data.kosli_custom_attestation_type.security.schema
summary = data.kosli_custom_attestation_type.security.summary

# Apply stricter validation rules
jq_rules = [
Expand All @@ -55,6 +56,11 @@ output "security_scan_rules" {
value = data.kosli_custom_attestation_type.security.jq_rules
}

output "security_scan_summary" {
description = "Summary rows shown on the attestation detail page, as a JSON array"
value = data.kosli_custom_attestation_type.security.summary
}

output "security_scan_archived" {
description = "Whether the security scan attestation type is archived"
value = data.kosli_custom_attestation_type.security.archived
Expand All @@ -79,3 +85,4 @@ The `archived` attribute indicates whether an attestation type has been deleted/
- `description` (String) A description of what this attestation type validates.
- `jq_rules` (List of String) List of jq expressions that define evaluation rules. All rules must evaluate to `true` for compliance.
- `schema` (String) JSON Schema that defines the structure of attestation data.
- `summary` (String) JSON array of ordered, labelled jq expressions rendered as rows on the attestation detail page in Kosli. Each element is an object with a `name` and an `expression`. Null when the type defines no summary.
Comment thread
mbevc1 marked this conversation as resolved.
26 changes: 26 additions & 0 deletions terraform-reference/resources/custom_attestation_type.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ resource "kosli_custom_attestation_type" "security_scan" {
medium_vulnerabilities = { type = "integer" }
scan_date = { type = "string" }
scanner_version = { type = "string" }
report_url = { type = "string" }
}
required = ["critical_vulnerabilities", "high_vulnerabilities", "scan_date"]
})
Expand All @@ -45,6 +46,15 @@ resource "kosli_custom_attestation_type" "security_scan" {
".critical_vulnerabilities == 0",
".high_vulnerabilities < 5"
]

# Ordered, labelled values shown on the attestation detail page in Kosli.
Comment thread
mbevc1 marked this conversation as resolved.
# A value that is a valid URL renders as a clickable link.
summary = jsonencode([
{ name = "Critical", expression = ".critical_vulnerabilities" },
{ name = "High", expression = ".high_vulnerabilities" },
{ name = "Scanner", expression = ".scanner_version" },
{ name = "Report", expression = ".report_url" },
])
}

# Code coverage attestation type
Expand Down Expand Up @@ -77,6 +87,21 @@ resource "kosli_custom_attestation_type" "code_coverage" {
]
}

# Attestation type whose schema and summary are kept in standalone JSON files,
# so the same definitions can be shared with other tooling
resource "kosli_custom_attestation_type" "code_quality" {
name = "code-quality"
description = "Validates code quality metrics"

schema = file("${path.module}/schemas/code-quality.json")
summary = file("${path.module}/summaries/code-quality.json")

jq_rules = [
".line_coverage >= 80",
".lint_errors == 0"
]
}
Comment on lines +90 to +103

@claude claude Bot Aug 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Improvement — this example points at files whose contents are never shown. A reader can't tell what belongs in summaries/code-quality.json (a bare JSON array of {name, expression}? wrapped in an object?). The schema case is covered by the ### Schema example block below; there's no equivalent for summary, so the file() path is the one form of the attribute with no worked example on the page.

Two smaller things: the resource is named code_quality but its jq_rules reference .line_coverage, duplicating code_coverage directly above it — and .lint_errors appears with no schema to explain it.

Suggest either dropping this example (the file() pattern is already stated in the attribute list) or pairing it with the JSON file contents in the proposed ## Summary rows section.


# Age verification attestation type with only jq rules (no schema)
resource "kosli_custom_attestation_type" "age_verification" {
name = "age-verification"
Expand Down Expand Up @@ -161,3 +186,4 @@ terraform import kosli_custom_attestation_type.security_scan security-scan
- `description` (String) Description of the custom attestation type. Explains what this attestation type validates.
- `jq_rules` (List of String) List of jq evaluation rules. Each rule is a jq expression that must evaluate to true for the attestation to be considered compliant. Example: `[".coverage >= 80"]`. If omitted, no evaluation is performed.
- `schema` (String) JSON Schema definition that defines the structure of attestation data. Can be provided inline using heredoc syntax or loaded from a file using `file()`. If omitted, no schema validation is performed. Semantic equality is used for comparison, so formatting differences are ignored.
- `summary` (String) JSON array of ordered, labelled jq expressions rendered as rows on the attestation detail page in Kosli. Each element is an object with a `name` (the row label) and an `expression` (a jq expression evaluated against the attestation data); values that are valid URLs render as links. Can be provided inline using `jsonencode()`/heredoc syntax or loaded from a file using `file()`, so the same JSON can be kept in one place and shared with other tooling. Example: `jsonencode([{ name = "Coverage", expression = ".coverage" }])`. If omitted, the attestation detail page falls back to showing the jq evaluation results as a pass/fail checklist; removing it from a type that had one clears the summary. Semantic JSON equality is used when reading the value back from Kosli, so your formatting is preserved rather than being rewritten to the API's compact form.

@claude claude Bot Aug 24, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Improvement — this entry is doing too much work. It's six sentences and ~3× longer than any neighbouring bullet, and it's the only place several behaviors are documented (URL rendering, the fallback, file() loading, semantic equality). The page's pattern for exactly this is a dedicated section: ## Schema validation and ## JQ rules both explain their attribute in prose with an example, and the schema list stays terse.

Suggest adding a ## Summary rows section after ## JQ rules carrying the prose plus a JSON example, and trimming this bullet to match its neighbors. Also fixes "labelled" → "labeled".

Suggested change
- `summary` (String) JSON array of ordered, labelled jq expressions rendered as rows on the attestation detail page in Kosli. Each element is an object with a `name` (the row label) and an `expression` (a jq expression evaluated against the attestation data); values that are valid URLs render as links. Can be provided inline using `jsonencode()`/heredoc syntax or loaded from a file using `file()`, so the same JSON can be kept in one place and shared with other tooling. Example: `jsonencode([{ name = "Coverage", expression = ".coverage" }])`. If omitted, the attestation detail page falls back to showing the jq evaluation results as a pass/fail checklist; removing it from a type that had one clears the summary. Semantic JSON equality is used when reading the value back from Kosli, so your formatting is preserved rather than being rewritten to the API's compact form.
- `summary` (String) JSON array of ordered, labeled jq expressions that Kosli renders as rows on the attestation detail page. Can be provided inline using `jsonencode()`/heredoc syntax or loaded from a file using `file()`. Example: `jsonencode([{ name = "Coverage", expression = ".coverage" }])`. If omitted, the detail page falls back to the jq evaluation results checklist. Semantic equality is used for comparison, so formatting differences are ignored.

Loading