docs: update Terraform reference: custom_attestation_type summary attribute - #372
docs: update Terraform reference: custom_attestation_type summary attribute#372mintlify[bot] wants to merge 1 commit into
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
|
Claude finished @mintlify[bot]'s task in 2m 19s —— View job Doc review —
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
| - `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. |
There was a problem hiding this comment.
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".
| - `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. |
| # 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" | ||
| ] | ||
| } |
There was a problem hiding this comment.
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.
dangrondahl
changed the title
Summary
Documents the new
summaryattribute onkosli_custom_attestation_typereleased in terraform-provider-kosli v0.9.3.Changes
terraform-reference/resources/custom_attestation_type.mdx: addedsummaryto the security scan example, added a new file-basedcode-qualityexample, and added thesummaryoptional attribute to the schema list.terraform-reference/data-sources/custom_attestation_type.mdx: addedsummaryto the reuse example and outputs, and added thesummaryread-only attribute to the schema list.Context
v0.9.3 (tagged 2026-08-18) adds an optional
summaryJSON attribute (array of ordered, labelled jq expressions) that Kosli renders as rows on the attestation detail page, with URL values rendered as links.