From d558cb11b483869500e6a22f6f695ce6664d0123 Mon Sep 17 00:00:00 2001 From: Ibrahim Diallo <20114089+thisisibrahimd@users.noreply.github.com> Date: Wed, 2 Sep 2026 19:52:48 -0400 Subject: [PATCH 1/2] feat: generate JSON Schema files for all OpenSLO objects Add internal/cmd/jsonschema generator using invopop/jsonschema with Go comment extraction. Produces 16 schema files across v1alpha, v1, and v2alpha versions. Custom JSONSchema() methods handle tricky types: - DurationShorthand: string with pattern ^[0-9]+[mhdwMQY]$ - Label (v1): oneOf string/array - Union types (SLOAlertPolicy, AlertPolicyCondition, AlertPolicyNotificationTarget): inline oneOf schemas Wire into Makefile via generate/jsonschema target. --- Makefile | 9 +- docs/jsonschema/v1/alert-condition.json | 130 +++++++ .../v1/alert-notification-target.json | 93 +++++ docs/jsonschema/v1/alert-policy.json | 182 ++++++++++ docs/jsonschema/v1/data-source.json | 95 +++++ docs/jsonschema/v1/service.json | 87 +++++ docs/jsonschema/v1/sli.json | 153 ++++++++ docs/jsonschema/v1/slo.json | 331 ++++++++++++++++++ docs/jsonschema/v1alpha/service.json | 55 +++ docs/jsonschema/v1alpha/slo.json | 210 +++++++++++ docs/jsonschema/v2alpha/alert-condition.json | 114 ++++++ .../v2alpha/alert-notification-target.json | 76 ++++ docs/jsonschema/v2alpha/alert-policy.json | 165 +++++++++ docs/jsonschema/v2alpha/data-source.json | 78 +++++ docs/jsonschema/v2alpha/service.json | 70 ++++ docs/jsonschema/v2alpha/sli.json | 138 ++++++++ docs/jsonschema/v2alpha/slo.json | 316 +++++++++++++++++ go.mod | 5 + go.sum | 18 + go.work.sum | 4 +- internal/cmd/jsonschema/main.go | 124 +++++++ pkg/openslo/v1/jsonschema.go | 113 ++++++ pkg/openslo/v1alpha/jsonschema.go | 5 + pkg/openslo/v2alpha/jsonschema.go | 102 ++++++ 24 files changed, 2669 insertions(+), 4 deletions(-) create mode 100644 docs/jsonschema/v1/alert-condition.json create mode 100644 docs/jsonschema/v1/alert-notification-target.json create mode 100644 docs/jsonschema/v1/alert-policy.json create mode 100644 docs/jsonschema/v1/data-source.json create mode 100644 docs/jsonschema/v1/service.json create mode 100644 docs/jsonschema/v1/sli.json create mode 100644 docs/jsonschema/v1/slo.json create mode 100644 docs/jsonschema/v1alpha/service.json create mode 100644 docs/jsonschema/v1alpha/slo.json create mode 100644 docs/jsonschema/v2alpha/alert-condition.json create mode 100644 docs/jsonschema/v2alpha/alert-notification-target.json create mode 100644 docs/jsonschema/v2alpha/alert-policy.json create mode 100644 docs/jsonschema/v2alpha/data-source.json create mode 100644 docs/jsonschema/v2alpha/service.json create mode 100644 docs/jsonschema/v2alpha/sli.json create mode 100644 docs/jsonschema/v2alpha/slo.json create mode 100644 internal/cmd/jsonschema/main.go create mode 100644 pkg/openslo/v1/jsonschema.go create mode 100644 pkg/openslo/v1alpha/jsonschema.go create mode 100644 pkg/openslo/v2alpha/jsonschema.go diff --git a/Makefile b/Makefile index 998365c..8fd2603 100644 --- a/Makefile +++ b/Makefile @@ -73,9 +73,9 @@ check/vulns: $(call _print_step,Running govulncheck) $(GO_ENV) govulncheck $(GO_PACKAGES) -.PHONY: generate generate/go generate/govydoc +.PHONY: generate generate/go generate/govydoc generate/jsonschema ## Auto generate files. -generate: generate/go generate/govydoc +generate: generate/go generate/govydoc generate/jsonschema ## Generate Golang code. generate/go: @@ -87,6 +87,11 @@ generate/govydoc: $(call _print_step,Generating object docs) $(GO_ENV) go run ./internal/cmd/objectdoc/main.go > ./docs/manifest.json +## Generate JSON Schema files for all OpenSLO objects. +generate/jsonschema: + $(call _print_step,Generating JSON Schema files) + $(GO_ENV) go run ./internal/cmd/jsonschema/main.go ./docs/jsonschema + .PHONY: format format/go ## Format files. format: format/go diff --git a/docs/jsonschema/v1/alert-condition.json b/docs/jsonschema/v1/alert-condition.json new file mode 100644 index 0000000..eeaf47b --- /dev/null +++ b/docs/jsonschema/v1/alert-condition.json @@ -0,0 +1,130 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v1/alert-condition.json", + "$anchor": "AlertCondition", + "$defs": { + "AlertConditionSpec": { + "$anchor": "AlertConditionSpec", + "properties": { + "severity": { + "type": "string" + }, + "condition": { + "$ref": "#/$defs/AlertConditionType" + }, + "description": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "severity", + "condition" + ] + }, + "AlertConditionType": { + "$anchor": "AlertConditionType", + "properties": { + "kind": { + "type": "string" + }, + "op": { + "type": "string" + }, + "threshold": { + "type": "number" + }, + "lookbackWindow": { + "$ref": "#/$defs/DurationShorthand" + }, + "alertAfter": { + "$ref": "#/$defs/DurationShorthand" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "kind", + "op", + "threshold", + "lookbackWindow" + ] + }, + "Annotations": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "DurationShorthand": { + "type": "string", + "pattern": "^[0-9]+[mhdwMQY]$", + "description": "A shorthand representation of time duration, e.g. '1m', '10d', '2w'." + }, + "Label": { + "oneOf": [ + { + "type": "string" + }, + { + "items": { + "type": "string" + }, + "type": "array" + } + ], + "description": "A label value that can be either a single string or an array of strings." + }, + "Labels": { + "additionalProperties": { + "$ref": "#/$defs/Label" + }, + "type": "object" + }, + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "displayName": { + "type": "string" + }, + "labels": { + "$ref": "#/$defs/Labels" + }, + "annotations": { + "$ref": "#/$defs/Annotations" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/AlertConditionSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/docs/jsonschema/v1/alert-notification-target.json b/docs/jsonschema/v1/alert-notification-target.json new file mode 100644 index 0000000..e9aafc8 --- /dev/null +++ b/docs/jsonschema/v1/alert-notification-target.json @@ -0,0 +1,93 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v1/alert-notification-target.json", + "$anchor": "AlertNotificationTarget", + "$defs": { + "AlertNotificationTargetSpec": { + "$anchor": "AlertNotificationTargetSpec", + "properties": { + "description": { + "type": "string" + }, + "target": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "target" + ] + }, + "Annotations": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "Label": { + "oneOf": [ + { + "type": "string" + }, + { + "items": { + "type": "string" + }, + "type": "array" + } + ], + "description": "A label value that can be either a single string or an array of strings." + }, + "Labels": { + "additionalProperties": { + "$ref": "#/$defs/Label" + }, + "type": "object" + }, + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "displayName": { + "type": "string" + }, + "labels": { + "$ref": "#/$defs/Labels" + }, + "annotations": { + "$ref": "#/$defs/Annotations" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/AlertNotificationTargetSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/docs/jsonschema/v1/alert-policy.json b/docs/jsonschema/v1/alert-policy.json new file mode 100644 index 0000000..20b1527 --- /dev/null +++ b/docs/jsonschema/v1/alert-policy.json @@ -0,0 +1,182 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v1/alert-policy.json", + "$anchor": "AlertPolicy", + "$defs": { + "AlertPolicyCondition": { + "oneOf": [ + { + "properties": { + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/AlertConditionSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "kind", + "metadata", + "spec" + ] + }, + { + "properties": { + "conditionRef": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "conditionRef" + ] + } + ], + "description": "An alert condition that can be provided inline or as a reference." + }, + "AlertPolicyNotificationTarget": { + "oneOf": [ + { + "properties": { + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/AlertNotificationTargetSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "kind", + "metadata", + "spec" + ] + }, + { + "properties": { + "targetRef": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "targetRef" + ] + } + ], + "description": "A notification target that can be provided inline or as a reference." + }, + "AlertPolicySpec": { + "$anchor": "AlertPolicySpec", + "properties": { + "description": { + "type": "string" + }, + "alertWhenNoData": { + "type": "boolean" + }, + "alertWhenBreaching": { + "type": "boolean" + }, + "alertWhenResolved": { + "type": "boolean" + }, + "conditions": { + "items": { + "$ref": "#/$defs/AlertPolicyCondition" + }, + "type": "array" + }, + "notificationTargets": { + "items": { + "$ref": "#/$defs/AlertPolicyNotificationTarget" + }, + "type": "array" + } + }, + "additionalProperties": false, + "type": "object" + }, + "Annotations": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "Label": { + "oneOf": [ + { + "type": "string" + }, + { + "items": { + "type": "string" + }, + "type": "array" + } + ], + "description": "A label value that can be either a single string or an array of strings." + }, + "Labels": { + "additionalProperties": { + "$ref": "#/$defs/Label" + }, + "type": "object" + }, + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "displayName": { + "type": "string" + }, + "labels": { + "$ref": "#/$defs/Labels" + }, + "annotations": { + "$ref": "#/$defs/Annotations" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/AlertPolicySpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/docs/jsonschema/v1/data-source.json b/docs/jsonschema/v1/data-source.json new file mode 100644 index 0000000..1ab790e --- /dev/null +++ b/docs/jsonschema/v1/data-source.json @@ -0,0 +1,95 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v1/data-source.json", + "$anchor": "DataSource", + "$defs": { + "Annotations": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "DataSourceSpec": { + "$anchor": "DataSourceSpec", + "properties": { + "description": { + "type": "string" + }, + "type": { + "type": "string" + }, + "connectionDetails": true + }, + "additionalProperties": false, + "type": "object", + "required": [ + "type", + "connectionDetails" + ] + }, + "Label": { + "oneOf": [ + { + "type": "string" + }, + { + "items": { + "type": "string" + }, + "type": "array" + } + ], + "description": "A label value that can be either a single string or an array of strings." + }, + "Labels": { + "additionalProperties": { + "$ref": "#/$defs/Label" + }, + "type": "object" + }, + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "displayName": { + "type": "string" + }, + "labels": { + "$ref": "#/$defs/Labels" + }, + "annotations": { + "$ref": "#/$defs/Annotations" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/DataSourceSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/docs/jsonschema/v1/service.json b/docs/jsonschema/v1/service.json new file mode 100644 index 0000000..20fb0fb --- /dev/null +++ b/docs/jsonschema/v1/service.json @@ -0,0 +1,87 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v1/service.json", + "$anchor": "Service", + "$defs": { + "Annotations": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "Label": { + "oneOf": [ + { + "type": "string" + }, + { + "items": { + "type": "string" + }, + "type": "array" + } + ], + "description": "A label value that can be either a single string or an array of strings." + }, + "Labels": { + "additionalProperties": { + "$ref": "#/$defs/Label" + }, + "type": "object" + }, + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "displayName": { + "type": "string" + }, + "labels": { + "$ref": "#/$defs/Labels" + }, + "annotations": { + "$ref": "#/$defs/Annotations" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + }, + "ServiceSpec": { + "$anchor": "ServiceSpec", + "properties": { + "description": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object" + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/ServiceSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/docs/jsonschema/v1/sli.json b/docs/jsonschema/v1/sli.json new file mode 100644 index 0000000..85af2ac --- /dev/null +++ b/docs/jsonschema/v1/sli.json @@ -0,0 +1,153 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v1/sli.json", + "$anchor": "SLI", + "$defs": { + "Annotations": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "Label": { + "oneOf": [ + { + "type": "string" + }, + { + "items": { + "type": "string" + }, + "type": "array" + } + ], + "description": "A label value that can be either a single string or an array of strings." + }, + "Labels": { + "additionalProperties": { + "$ref": "#/$defs/Label" + }, + "type": "object" + }, + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "displayName": { + "type": "string" + }, + "labels": { + "$ref": "#/$defs/Labels" + }, + "annotations": { + "$ref": "#/$defs/Annotations" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + }, + "SLIMetricSource": { + "$anchor": "SLIMetricSource", + "properties": { + "metricSourceRef": { + "type": "string" + }, + "type": { + "type": "string" + }, + "spec": { + "type": "object" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "spec" + ] + }, + "SLIMetricSpec": { + "$anchor": "SLIMetricSpec", + "properties": { + "metricSource": { + "$ref": "#/$defs/SLIMetricSource" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "metricSource" + ] + }, + "SLIRatioMetric": { + "$anchor": "SLIRatioMetric", + "properties": { + "counter": { + "type": "boolean" + }, + "good": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "bad": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "total": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "rawType": { + "type": "string" + }, + "raw": { + "$ref": "#/$defs/SLIMetricSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "counter" + ] + }, + "SLISpec": { + "$anchor": "SLISpec", + "properties": { + "description": { + "type": "string" + }, + "thresholdMetric": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "ratioMetric": { + "$ref": "#/$defs/SLIRatioMetric" + } + }, + "additionalProperties": false, + "type": "object" + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/SLISpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/docs/jsonschema/v1/slo.json b/docs/jsonschema/v1/slo.json new file mode 100644 index 0000000..727064d --- /dev/null +++ b/docs/jsonschema/v1/slo.json @@ -0,0 +1,331 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v1/slo.json", + "$anchor": "SLO", + "$defs": { + "Annotations": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "DurationShorthand": { + "type": "string", + "pattern": "^[0-9]+[mhdwMQY]$", + "description": "A shorthand representation of time duration, e.g. '1m', '10d', '2w'." + }, + "Label": { + "oneOf": [ + { + "type": "string" + }, + { + "items": { + "type": "string" + }, + "type": "array" + } + ], + "description": "A label value that can be either a single string or an array of strings." + }, + "Labels": { + "additionalProperties": { + "$ref": "#/$defs/Label" + }, + "type": "object" + }, + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "displayName": { + "type": "string" + }, + "labels": { + "$ref": "#/$defs/Labels" + }, + "annotations": { + "$ref": "#/$defs/Annotations" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + }, + "SLIMetricSource": { + "$anchor": "SLIMetricSource", + "properties": { + "metricSourceRef": { + "type": "string" + }, + "type": { + "type": "string" + }, + "spec": { + "type": "object" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "spec" + ] + }, + "SLIMetricSpec": { + "$anchor": "SLIMetricSpec", + "properties": { + "metricSource": { + "$ref": "#/$defs/SLIMetricSource" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "metricSource" + ] + }, + "SLIRatioMetric": { + "$anchor": "SLIRatioMetric", + "properties": { + "counter": { + "type": "boolean" + }, + "good": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "bad": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "total": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "rawType": { + "type": "string" + }, + "raw": { + "$ref": "#/$defs/SLIMetricSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "counter" + ] + }, + "SLISpec": { + "$anchor": "SLISpec", + "properties": { + "description": { + "type": "string" + }, + "thresholdMetric": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "ratioMetric": { + "$ref": "#/$defs/SLIRatioMetric" + } + }, + "additionalProperties": false, + "type": "object" + }, + "SLOAlertPolicy": { + "oneOf": [ + { + "properties": { + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/AlertPolicySpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "kind", + "metadata", + "spec" + ] + }, + { + "properties": { + "alertPolicyRef": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "alertPolicyRef" + ] + } + ], + "description": "An alert policy that can be provided inline or as a reference." + }, + "SLOCalendar": { + "$anchor": "SLOCalendar", + "properties": { + "startTime": { + "type": "string" + }, + "timeZone": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "startTime", + "timeZone" + ] + }, + "SLOIndicatorInline": { + "$anchor": "SLOIndicatorInline", + "properties": { + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/SLISpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "metadata", + "spec" + ] + }, + "SLOObjective": { + "$anchor": "SLOObjective", + "properties": { + "displayName": { + "type": "string" + }, + "op": { + "type": "string" + }, + "value": { + "type": "number" + }, + "target": { + "type": "number" + }, + "targetPercent": { + "type": "number" + }, + "timeSliceTarget": { + "type": "number" + }, + "timeSliceWindow": { + "$ref": "#/$defs/DurationShorthand" + }, + "indicator": { + "$ref": "#/$defs/SLOIndicatorInline" + }, + "indicatorRef": { + "type": "string" + }, + "compositeWeight": { + "type": "number" + } + }, + "additionalProperties": false, + "type": "object" + }, + "SLOSpec": { + "$anchor": "SLOSpec", + "properties": { + "description": { + "type": "string" + }, + "service": { + "type": "string" + }, + "indicator": { + "$ref": "#/$defs/SLOIndicatorInline" + }, + "indicatorRef": { + "type": "string" + }, + "budgetingMethod": { + "type": "string" + }, + "timeWindow": { + "items": { + "$ref": "#/$defs/SLOTimeWindow" + }, + "type": "array" + }, + "objectives": { + "items": { + "$ref": "#/$defs/SLOObjective" + }, + "type": "array" + }, + "alertPolicies": { + "items": { + "$ref": "#/$defs/SLOAlertPolicy" + }, + "type": "array" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "service", + "budgetingMethod", + "objectives" + ] + }, + "SLOTimeWindow": { + "$anchor": "SLOTimeWindow", + "properties": { + "duration": { + "$ref": "#/$defs/DurationShorthand" + }, + "isRolling": { + "type": "boolean" + }, + "calendar": { + "$ref": "#/$defs/SLOCalendar" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "duration", + "isRolling" + ] + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/SLOSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/docs/jsonschema/v1alpha/service.json b/docs/jsonschema/v1alpha/service.json new file mode 100644 index 0000000..d01549d --- /dev/null +++ b/docs/jsonschema/v1alpha/service.json @@ -0,0 +1,55 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v1alpha/service.json", + "$anchor": "Service", + "$defs": { + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "displayName": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + }, + "ServiceSpec": { + "$anchor": "ServiceSpec", + "properties": { + "description": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object" + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/ServiceSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/docs/jsonschema/v1alpha/slo.json b/docs/jsonschema/v1alpha/slo.json new file mode 100644 index 0000000..7da197f --- /dev/null +++ b/docs/jsonschema/v1alpha/slo.json @@ -0,0 +1,210 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v1alpha/slo.json", + "$anchor": "SLO", + "$defs": { + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "displayName": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + }, + "SLOCalendar": { + "$anchor": "SLOCalendar", + "properties": { + "startTime": { + "type": "string" + }, + "timeZone": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "startTime", + "timeZone" + ] + }, + "SLOIndicator": { + "$anchor": "SLOIndicator", + "properties": { + "thresholdMetric": { + "$ref": "#/$defs/SLOMetricSourceSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "thresholdMetric" + ] + }, + "SLOMetricSourceSpec": { + "$anchor": "SLOMetricSourceSpec", + "properties": { + "source": { + "type": "string" + }, + "queryType": { + "type": "string" + }, + "query": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "source", + "queryType", + "query" + ] + }, + "SLOObjective": { + "$anchor": "SLOObjective", + "properties": { + "displayName": { + "type": "string" + }, + "value": { + "type": "number" + }, + "ratioMetrics": { + "$ref": "#/$defs/SLORatioMetrics" + }, + "target": { + "type": "number" + }, + "timeSliceTarget": { + "type": "number" + }, + "op": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "displayName", + "value", + "ratioMetrics", + "target" + ] + }, + "SLORatioMetrics": { + "$anchor": "SLORatioMetrics", + "properties": { + "good": { + "$ref": "#/$defs/SLOMetricSourceSpec" + }, + "total": { + "$ref": "#/$defs/SLOMetricSourceSpec" + }, + "incremental": { + "type": "boolean" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "good", + "total", + "incremental" + ] + }, + "SLOSpec": { + "$anchor": "SLOSpec", + "properties": { + "timeWindows": { + "items": { + "$ref": "#/$defs/SLOTimeWindow" + }, + "type": "array" + }, + "budgetingMethod": { + "type": "string" + }, + "description": { + "type": "string" + }, + "indicator": { + "$ref": "#/$defs/SLOIndicator" + }, + "service": { + "type": "string" + }, + "objectives": { + "items": { + "$ref": "#/$defs/SLOObjective" + }, + "type": "array" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "timeWindows", + "budgetingMethod", + "indicator", + "service", + "objectives" + ] + }, + "SLOTimeWindow": { + "$anchor": "SLOTimeWindow", + "properties": { + "unit": { + "type": "string" + }, + "count": { + "type": "integer" + }, + "isRolling": { + "type": "boolean" + }, + "calendar": { + "$ref": "#/$defs/SLOCalendar" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "unit", + "count", + "isRolling" + ] + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/SLOSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/docs/jsonschema/v2alpha/alert-condition.json b/docs/jsonschema/v2alpha/alert-condition.json new file mode 100644 index 0000000..f0de5cf --- /dev/null +++ b/docs/jsonschema/v2alpha/alert-condition.json @@ -0,0 +1,114 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v2alpha/alert-condition.json", + "$anchor": "AlertCondition", + "$defs": { + "AlertConditionSpec": { + "$anchor": "AlertConditionSpec", + "properties": { + "severity": { + "type": "string" + }, + "condition": { + "$ref": "#/$defs/AlertConditionType" + }, + "description": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "severity", + "condition" + ] + }, + "AlertConditionType": { + "$anchor": "AlertConditionType", + "properties": { + "kind": { + "type": "string" + }, + "op": { + "type": "string" + }, + "threshold": { + "type": "number" + }, + "lookbackWindow": { + "$ref": "#/$defs/DurationShorthand" + }, + "alertAfter": { + "$ref": "#/$defs/DurationShorthand" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "kind", + "op", + "threshold", + "lookbackWindow", + "alertAfter" + ] + }, + "Annotations": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "DurationShorthand": { + "type": "string", + "pattern": "^[0-9]+[mhdwMQY]$", + "description": "A shorthand representation of time duration, e.g. '1m', '10d', '2w'." + }, + "Labels": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "labels": { + "$ref": "#/$defs/Labels" + }, + "annotations": { + "$ref": "#/$defs/Annotations" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/AlertConditionSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/docs/jsonschema/v2alpha/alert-notification-target.json b/docs/jsonschema/v2alpha/alert-notification-target.json new file mode 100644 index 0000000..ab23345 --- /dev/null +++ b/docs/jsonschema/v2alpha/alert-notification-target.json @@ -0,0 +1,76 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v2alpha/alert-notification-target.json", + "$anchor": "AlertNotificationTarget", + "$defs": { + "AlertNotificationTargetSpec": { + "$anchor": "AlertNotificationTargetSpec", + "properties": { + "description": { + "type": "string" + }, + "target": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "target" + ] + }, + "Annotations": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "Labels": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "labels": { + "$ref": "#/$defs/Labels" + }, + "annotations": { + "$ref": "#/$defs/Annotations" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/AlertNotificationTargetSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/docs/jsonschema/v2alpha/alert-policy.json b/docs/jsonschema/v2alpha/alert-policy.json new file mode 100644 index 0000000..7436437 --- /dev/null +++ b/docs/jsonschema/v2alpha/alert-policy.json @@ -0,0 +1,165 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v2alpha/alert-policy.json", + "$anchor": "AlertPolicy", + "$defs": { + "AlertPolicyCondition": { + "oneOf": [ + { + "properties": { + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/AlertConditionSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "kind", + "metadata", + "spec" + ] + }, + { + "properties": { + "conditionRef": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "conditionRef" + ] + } + ], + "description": "An alert condition that can be provided inline or as a reference." + }, + "AlertPolicyNotificationTarget": { + "oneOf": [ + { + "properties": { + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/AlertNotificationTargetSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "kind", + "metadata", + "spec" + ] + }, + { + "properties": { + "targetRef": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "targetRef" + ] + } + ], + "description": "A notification target that can be provided inline or as a reference." + }, + "AlertPolicySpec": { + "$anchor": "AlertPolicySpec", + "properties": { + "description": { + "type": "string" + }, + "alertWhenNoData": { + "type": "boolean" + }, + "alertWhenBreaching": { + "type": "boolean" + }, + "alertWhenResolved": { + "type": "boolean" + }, + "conditions": { + "items": { + "$ref": "#/$defs/AlertPolicyCondition" + }, + "type": "array" + }, + "notificationTargets": { + "items": { + "$ref": "#/$defs/AlertPolicyNotificationTarget" + }, + "type": "array" + } + }, + "additionalProperties": false, + "type": "object" + }, + "Annotations": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "Labels": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "labels": { + "$ref": "#/$defs/Labels" + }, + "annotations": { + "$ref": "#/$defs/Annotations" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/AlertPolicySpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/docs/jsonschema/v2alpha/data-source.json b/docs/jsonschema/v2alpha/data-source.json new file mode 100644 index 0000000..23643f5 --- /dev/null +++ b/docs/jsonschema/v2alpha/data-source.json @@ -0,0 +1,78 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v2alpha/data-source.json", + "$anchor": "DataSource", + "$defs": { + "Annotations": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "DataSourceSpec": { + "$anchor": "DataSourceSpec", + "properties": { + "description": { + "type": "string" + }, + "type": { + "type": "string" + }, + "connectionDetails": true + }, + "additionalProperties": false, + "type": "object", + "required": [ + "type", + "connectionDetails" + ] + }, + "Labels": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "labels": { + "$ref": "#/$defs/Labels" + }, + "annotations": { + "$ref": "#/$defs/Annotations" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/DataSourceSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/docs/jsonschema/v2alpha/service.json b/docs/jsonschema/v2alpha/service.json new file mode 100644 index 0000000..c139fa1 --- /dev/null +++ b/docs/jsonschema/v2alpha/service.json @@ -0,0 +1,70 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v2alpha/service.json", + "$anchor": "Service", + "$defs": { + "Annotations": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "Labels": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "labels": { + "$ref": "#/$defs/Labels" + }, + "annotations": { + "$ref": "#/$defs/Annotations" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + }, + "ServiceSpec": { + "$anchor": "ServiceSpec", + "properties": { + "description": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object" + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/ServiceSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/docs/jsonschema/v2alpha/sli.json b/docs/jsonschema/v2alpha/sli.json new file mode 100644 index 0000000..9cc297c --- /dev/null +++ b/docs/jsonschema/v2alpha/sli.json @@ -0,0 +1,138 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v2alpha/sli.json", + "$anchor": "SLI", + "$defs": { + "Annotations": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "DataSourceSpec": { + "$anchor": "DataSourceSpec", + "properties": { + "description": { + "type": "string" + }, + "type": { + "type": "string" + }, + "connectionDetails": true + }, + "additionalProperties": false, + "type": "object", + "required": [ + "type", + "connectionDetails" + ] + }, + "Labels": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "labels": { + "$ref": "#/$defs/Labels" + }, + "annotations": { + "$ref": "#/$defs/Annotations" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + }, + "SLIMetricSpec": { + "$anchor": "SLIMetricSpec", + "properties": { + "dataSourceRef": { + "type": "string" + }, + "dataSourceSpec": { + "$ref": "#/$defs/DataSourceSpec" + }, + "spec": { + "type": "object" + } + }, + "additionalProperties": false, + "type": "object" + }, + "SLIRatioMetric": { + "$anchor": "SLIRatioMetric", + "properties": { + "counter": { + "type": "boolean" + }, + "good": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "bad": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "total": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "rawType": { + "type": "string" + }, + "raw": { + "$ref": "#/$defs/SLIMetricSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "counter" + ] + }, + "SLISpec": { + "$anchor": "SLISpec", + "properties": { + "description": { + "type": "string" + }, + "thresholdMetric": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "ratioMetric": { + "$ref": "#/$defs/SLIRatioMetric" + } + }, + "additionalProperties": false, + "type": "object" + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/SLISpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/docs/jsonschema/v2alpha/slo.json b/docs/jsonschema/v2alpha/slo.json new file mode 100644 index 0000000..3ad32ba --- /dev/null +++ b/docs/jsonschema/v2alpha/slo.json @@ -0,0 +1,316 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://openslo.com/schemas/v2alpha/slo.json", + "$anchor": "SLO", + "$defs": { + "Annotations": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "DataSourceSpec": { + "$anchor": "DataSourceSpec", + "properties": { + "description": { + "type": "string" + }, + "type": { + "type": "string" + }, + "connectionDetails": true + }, + "additionalProperties": false, + "type": "object", + "required": [ + "type", + "connectionDetails" + ] + }, + "DurationShorthand": { + "type": "string", + "pattern": "^[0-9]+[mhdwMQY]$", + "description": "A shorthand representation of time duration, e.g. '1m', '10d', '2w'." + }, + "Labels": { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + "Metadata": { + "$anchor": "Metadata", + "properties": { + "name": { + "type": "string" + }, + "labels": { + "$ref": "#/$defs/Labels" + }, + "annotations": { + "$ref": "#/$defs/Annotations" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ] + }, + "SLIMetricSpec": { + "$anchor": "SLIMetricSpec", + "properties": { + "dataSourceRef": { + "type": "string" + }, + "dataSourceSpec": { + "$ref": "#/$defs/DataSourceSpec" + }, + "spec": { + "type": "object" + } + }, + "additionalProperties": false, + "type": "object" + }, + "SLIRatioMetric": { + "$anchor": "SLIRatioMetric", + "properties": { + "counter": { + "type": "boolean" + }, + "good": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "bad": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "total": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "rawType": { + "type": "string" + }, + "raw": { + "$ref": "#/$defs/SLIMetricSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "counter" + ] + }, + "SLISpec": { + "$anchor": "SLISpec", + "properties": { + "description": { + "type": "string" + }, + "thresholdMetric": { + "$ref": "#/$defs/SLIMetricSpec" + }, + "ratioMetric": { + "$ref": "#/$defs/SLIRatioMetric" + } + }, + "additionalProperties": false, + "type": "object" + }, + "SLOAlertPolicy": { + "oneOf": [ + { + "properties": { + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/AlertPolicySpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "kind", + "metadata", + "spec" + ] + }, + { + "properties": { + "alertPolicyRef": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "alertPolicyRef" + ] + } + ], + "description": "An alert policy that can be provided inline or as a reference." + }, + "SLOCalendar": { + "$anchor": "SLOCalendar", + "properties": { + "startTime": { + "type": "string" + }, + "timeZone": { + "type": "string" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "startTime", + "timeZone" + ] + }, + "SLOObjective": { + "$anchor": "SLOObjective", + "properties": { + "displayName": { + "type": "string" + }, + "op": { + "type": "string" + }, + "value": { + "type": "number" + }, + "target": { + "type": "number" + }, + "targetPercent": { + "type": "number" + }, + "timeSliceTarget": { + "type": "number" + }, + "timeSliceWindow": { + "$ref": "#/$defs/DurationShorthand" + }, + "sli": { + "$ref": "#/$defs/SLOSLIInline" + }, + "sliRef": { + "type": "string" + }, + "compositeWeight": { + "type": "number" + } + }, + "additionalProperties": false, + "type": "object" + }, + "SLOSLIInline": { + "$anchor": "SLOSLIInline", + "properties": { + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/SLISpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "metadata", + "spec" + ] + }, + "SLOSpec": { + "$anchor": "SLOSpec", + "properties": { + "description": { + "type": "string" + }, + "serviceRef": { + "type": "string" + }, + "sli": { + "$ref": "#/$defs/SLOSLIInline" + }, + "sliRef": { + "type": "string" + }, + "budgetingMethod": { + "type": "string" + }, + "timeWindow": { + "items": { + "$ref": "#/$defs/SLOTimeWindow" + }, + "type": "array" + }, + "objectives": { + "items": { + "$ref": "#/$defs/SLOObjective" + }, + "type": "array" + }, + "alertPolicies": { + "items": { + "$ref": "#/$defs/SLOAlertPolicy" + }, + "type": "array" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "serviceRef", + "budgetingMethod", + "objectives" + ] + }, + "SLOTimeWindow": { + "$anchor": "SLOTimeWindow", + "properties": { + "duration": { + "$ref": "#/$defs/DurationShorthand" + }, + "isRolling": { + "type": "boolean" + }, + "calendar": { + "$ref": "#/$defs/SLOCalendar" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "duration", + "isRolling" + ] + } + }, + "properties": { + "apiVersion": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "metadata": { + "$ref": "#/$defs/Metadata" + }, + "spec": { + "$ref": "#/$defs/SLOSpec" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "apiVersion", + "kind", + "metadata", + "spec" + ] +} \ No newline at end of file diff --git a/go.mod b/go.mod index 2fbae0d..cf6806a 100644 --- a/go.mod +++ b/go.mod @@ -3,12 +3,17 @@ module github.com/OpenSLO/go-sdk go 1.26 require ( + github.com/invopop/jsonschema v0.14.0 github.com/nobl9/govy v0.29.0 + github.com/pb33f/ordered-map/v2 v2.3.1 sigs.k8s.io/yaml v1.6.0 ) require ( + github.com/bahlo/generic-list-go v0.2.0 // indirect + github.com/buger/jsonparser v1.1.2 // indirect go.yaml.in/yaml/v2 v2.4.2 // indirect + go.yaml.in/yaml/v4 v4.0.0-rc.2 // indirect golang.org/x/mod v0.39.0 // indirect golang.org/x/sync v0.22.0 // indirect golang.org/x/text v0.41.0 // indirect diff --git a/go.sum b/go.sum index 87ce67a..4f22ee2 100644 --- a/go.sum +++ b/go.sum @@ -1,11 +1,27 @@ +github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPnH1Wvgk= +github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg= +github.com/buger/jsonparser v1.1.2 h1:frqHqw7otoVbk5M8LlE/L7HTnIq2v9RX6EJ48i9AxJk= +github.com/buger/jsonparser v1.1.2/go.mod h1:6RYKKt7H4d4+iWqouImQ9R2FZql3VbhNgx27UK13J/0= +github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c= +github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI= github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY= +github.com/invopop/jsonschema v0.14.0 h1:MHQqLhvpNUZfw+hM3AZDYK7jxO8FZoQeQM77g8iyZjg= +github.com/invopop/jsonschema v0.14.0/go.mod h1:ygm6C2EaVNMBDPpaPlnOA2pFAxBnxGjFlMZABxm9n2I= github.com/nobl9/govy v0.29.0 h1:djB8Tx6mYDYNhfrmuKsdMNuSQTCkZcLB3S87ygtZZhA= github.com/nobl9/govy v0.29.0/go.mod h1:OdNFJceDL4MqQoQf9Z55yhHDTPs/4tDxmCw/Q7qzay8= +github.com/pb33f/ordered-map/v2 v2.3.1 h1:5319HDO0aw4DA4gzi+zv4FXU9UlSs3xGZ40wcP1nBjY= +github.com/pb33f/ordered-map/v2 v2.3.1/go.mod h1:qxFQgd0PkVUtOMCkTapqotNgzRhMPL7VvaHKbd1HnmQ= +github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM= +github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= +github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U= +github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U= go.yaml.in/yaml/v2 v2.4.2 h1:DzmwEr2rDGHl7lsFgAHxmNz/1NlQ7xLIrlN2h5d1eGI= go.yaml.in/yaml/v2 v2.4.2/go.mod h1:081UH+NErpNdqlCXm3TtEran0rJZGxAYx9hb/ELlsPU= go.yaml.in/yaml/v3 v3.0.3 h1:bXOww4E/J3f66rav3pX3m8w6jDE4knZjGOw8b5Y6iNE= go.yaml.in/yaml/v3 v3.0.3/go.mod h1:tBHosrYAkRZjRAOREWbDnBXUf08JOwYq++0QNwQiWzI= +go.yaml.in/yaml/v4 v4.0.0-rc.2 h1:/FrI8D64VSr4HtGIlUtlFMGsm7H7pWTbj6vOLVZcA6s= +go.yaml.in/yaml/v4 v4.0.0-rc.2/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0= golang.org/x/mod v0.39.0 h1:UF5zwQdCRRUpHfyPwr7d4UrGiVeldIsogtzWVnczL74= golang.org/x/mod v0.39.0/go.mod h1:bvIbwjQ0HUFFf5AKukeeYQG4ZBUG9yxQbR9aEweIwYY= golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek= @@ -16,5 +32,7 @@ golang.org/x/tools v0.49.0 h1:3NI7VXzL9+1WZD52Dx2ttoPwD5DWrFGpl9mFZDlmisI= golang.org/x/tools v0.49.0/go.mod h1:SJNXV9DBKT0UbdttsQjbfJlAE/q+y36++zo3uL3N0Oo= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= +gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= sigs.k8s.io/yaml v1.6.0 h1:G8fkbMSAFqgEFgh4b1wmtzDnioxFCUgTZhlbj5P9QYs= sigs.k8s.io/yaml v1.6.0/go.mod h1:796bPqUfzR/0jLAl6XjHl3Ck7MiyVv8dbTdyT3/pMf4= diff --git a/go.work.sum b/go.work.sum index 7639051..2ec4f1b 100644 --- a/go.work.sum +++ b/go.work.sum @@ -42,6 +42,7 @@ golang.org/x/net v0.40.0/go.mod h1:y0hY0exeL2Pku80/zKK7tpntoX23cqL3Oa6njdgRtds= golang.org/x/net v0.41.0/go.mod h1:B/K4NNqkfmg07DQYrbwvSluqCJOOXwUjeb/5lOisjbA= golang.org/x/net v0.42.0/go.mod h1:FF1RA5d3u7nAYA4z2TkclSCKh68eSXtiFwcWQpPXdt8= golang.org/x/net v0.57.0/go.mod h1:KpXc8iv+r3XplLAG/f7Jsf9RPszJzdR0f58q9vGOuEU= +golang.org/x/net v0.58.0/go.mod h1:YwCddHnFlT7eLQqVprV19OnhLGtc5xOKgE0RyqgfWAU= golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM= @@ -51,8 +52,6 @@ golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk= golang.org/x/sync v0.14.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA= golang.org/x/sync v0.15.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA= golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0= -golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek= -golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0= golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY= golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs= golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= @@ -70,6 +69,7 @@ golang.org/x/telemetry v0.0.0-20240228155512-f48c80bd79b2/go.mod h1:TeRTkGYfJXct golang.org/x/telemetry v0.0.0-20240521205824-bda55230c457/go.mod h1:pRgIJT+bRLFKnoM1ldnzKoxTIn14Yxz928LQRYYgIN0= golang.org/x/telemetry v0.0.0-20250710130107-8d8967aff50b/go.mod h1:4ZwOYna0/zsOKwuR5X/m0QFOJpSZvAxFfkQT+Erd9D4= golang.org/x/telemetry v0.0.0-20260708182218-49f421fb7959/go.mod h1:LV7u5Oco+Z/g6XI7PqN+EUUUGGkEcmB1uj2ceI0fOVg= +golang.org/x/telemetry v0.0.0-20260811182544-a038080d80e5/go.mod h1:LVehoXe41cL5SCVQilsV7Gg6BNG+Js6P9PhSbYTIUkQ= golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo= golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8= golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k= diff --git a/internal/cmd/jsonschema/main.go b/internal/cmd/jsonschema/main.go new file mode 100644 index 0000000..93fcab2 --- /dev/null +++ b/internal/cmd/jsonschema/main.go @@ -0,0 +1,124 @@ +package main + +import ( + "encoding/json" + "fmt" + "os" + "path/filepath" + + "github.com/invopop/jsonschema" + + v1 "github.com/OpenSLO/go-sdk/pkg/openslo/v1" + "github.com/OpenSLO/go-sdk/pkg/openslo/v1alpha" + v2alpha "github.com/OpenSLO/go-sdk/pkg/openslo/v2alpha" +) + +type objectGenerator struct { + versionDir string + generate func() any +} + +func main() { + outDir := "docs/jsonschema" + if len(os.Args) > 1 { + outDir = os.Args[1] + } + + generators := []objectGenerator{ + // v1alpha + {"v1alpha", func() any { return &v1alpha.Service{} }}, + {"v1alpha", func() any { return &v1alpha.SLO{} }}, + // v1 + {"v1", func() any { return &v1.Service{} }}, + {"v1", func() any { return &v1.SLO{} }}, + {"v1", func() any { return &v1.SLI{} }}, + {"v1", func() any { return &v1.DataSource{} }}, + {"v1", func() any { return &v1.AlertPolicy{} }}, + {"v1", func() any { return &v1.AlertCondition{} }}, + {"v1", func() any { return &v1.AlertNotificationTarget{} }}, + // v2alpha + {"v2alpha", func() any { return &v2alpha.Service{} }}, + {"v2alpha", func() any { return &v2alpha.SLO{} }}, + {"v2alpha", func() any { return &v2alpha.SLI{} }}, + {"v2alpha", func() any { return &v2alpha.DataSource{} }}, + {"v2alpha", func() any { return &v2alpha.AlertPolicy{} }}, + {"v2alpha", func() any { return &v2alpha.AlertCondition{} }}, + {"v2alpha", func() any { return &v2alpha.AlertNotificationTarget{} }}, + } + + r := &jsonschema.Reflector{ + ExpandedStruct: true, + AssignAnchor: true, + } + if err := r.AddGoComments("github.com/OpenSLO/go-sdk", "./pkg"); err != nil { + fmt.Fprintf(os.Stderr, "warning: failed to add Go comments: %v\n", err) + } + + for _, gen := range generators { + obj := gen.generate() + schema := r.Reflect(obj) + + // Set $id for the schema + kind := getKind(obj) + schema.ID = jsonschema.ID(fmt.Sprintf("https://openslo.com/schemas/%s/%s.json", gen.versionDir, kind)) + + data, err := json.MarshalIndent(schema, "", " ") + if err != nil { + fmt.Fprintf(os.Stderr, "failed to marshal schema for %s/%s: %v\n", gen.versionDir, kind, err) + os.Exit(1) + } + + dir := filepath.Join(outDir, gen.versionDir) + if err := os.MkdirAll(dir, 0o755); err != nil { + fmt.Fprintf(os.Stderr, "failed to create directory %s: %v\n", dir, err) + os.Exit(1) + } + + path := filepath.Join(dir, kind+".json") + if err := os.WriteFile(path, data, 0o644); err != nil { + fmt.Fprintf(os.Stderr, "failed to write %s: %v\n", path, err) + os.Exit(1) + } + + fmt.Printf("Generated %s\n", path) + } +} + +func getKind(obj any) string { + switch obj.(type) { + case *v1alpha.Service: + return "service" + case *v1alpha.SLO: + return "slo" + case *v1.Service: + return "service" + case *v1.SLO: + return "slo" + case *v1.SLI: + return "sli" + case *v1.DataSource: + return "data-source" + case *v1.AlertPolicy: + return "alert-policy" + case *v1.AlertCondition: + return "alert-condition" + case *v1.AlertNotificationTarget: + return "alert-notification-target" + case *v2alpha.Service: + return "service" + case *v2alpha.SLO: + return "slo" + case *v2alpha.SLI: + return "sli" + case *v2alpha.DataSource: + return "data-source" + case *v2alpha.AlertPolicy: + return "alert-policy" + case *v2alpha.AlertCondition: + return "alert-condition" + case *v2alpha.AlertNotificationTarget: + return "alert-notification-target" + default: + return "unknown" + } +} diff --git a/pkg/openslo/v1/jsonschema.go b/pkg/openslo/v1/jsonschema.go new file mode 100644 index 0000000..78d6374 --- /dev/null +++ b/pkg/openslo/v1/jsonschema.go @@ -0,0 +1,113 @@ +package v1 + +import ( + "github.com/invopop/jsonschema" + orderedmap "github.com/pb33f/ordered-map/v2" +) + +// JSONSchema returns a custom JSON Schema for DurationShorthand. +func (DurationShorthand) JSONSchema() *jsonschema.Schema { + return &jsonschema.Schema{ + Type: "string", + Description: "A shorthand representation of time duration, e.g. '1m', '10d', '2w'.", + Pattern: `^[0-9]+[mhdwMQY]$`, + } +} + +// JSONSchema returns a custom JSON Schema for Label. +func (Label) JSONSchema() *jsonschema.Schema { + return &jsonschema.Schema{ + Description: "A label value that can be either a single string or an array of strings.", + OneOf: []*jsonschema.Schema{ + {Type: "string"}, + {Type: "array", Items: &jsonschema.Schema{Type: "string"}}, + }, + } +} + +// JSONSchema returns a custom JSON Schema for SLOAlertPolicy. +func (SLOAlertPolicy) JSONSchema() *jsonschema.Schema { + inlineProps := orderedmap.New[string, *jsonschema.Schema]() + inlineProps.Set("kind", &jsonschema.Schema{Type: "string"}) + inlineProps.Set("metadata", &jsonschema.Schema{Ref: "#/$defs/Metadata"}) + inlineProps.Set("spec", &jsonschema.Schema{Ref: "#/$defs/AlertPolicySpec"}) + + refProps := orderedmap.New[string, *jsonschema.Schema]() + refProps.Set("alertPolicyRef", &jsonschema.Schema{Type: "string"}) + + return &jsonschema.Schema{ + Description: "An alert policy that can be provided inline or as a reference.", + OneOf: []*jsonschema.Schema{ + { + Type: "object", + Properties: inlineProps, + Required: []string{"kind", "metadata", "spec"}, + AdditionalProperties: jsonschema.FalseSchema, + }, + { + Type: "object", + Properties: refProps, + Required: []string{"alertPolicyRef"}, + AdditionalProperties: jsonschema.FalseSchema, + }, + }, + } +} + +// JSONSchema returns a custom JSON Schema for AlertPolicyCondition. +func (AlertPolicyCondition) JSONSchema() *jsonschema.Schema { + inlineProps := orderedmap.New[string, *jsonschema.Schema]() + inlineProps.Set("kind", &jsonschema.Schema{Type: "string"}) + inlineProps.Set("metadata", &jsonschema.Schema{Ref: "#/$defs/Metadata"}) + inlineProps.Set("spec", &jsonschema.Schema{Ref: "#/$defs/AlertConditionSpec"}) + + refProps := orderedmap.New[string, *jsonschema.Schema]() + refProps.Set("conditionRef", &jsonschema.Schema{Type: "string"}) + + return &jsonschema.Schema{ + Description: "An alert condition that can be provided inline or as a reference.", + OneOf: []*jsonschema.Schema{ + { + Type: "object", + Properties: inlineProps, + Required: []string{"kind", "metadata", "spec"}, + AdditionalProperties: jsonschema.FalseSchema, + }, + { + Type: "object", + Properties: refProps, + Required: []string{"conditionRef"}, + AdditionalProperties: jsonschema.FalseSchema, + }, + }, + } +} + +// JSONSchema returns a custom JSON Schema for AlertPolicyNotificationTarget. +func (AlertPolicyNotificationTarget) JSONSchema() *jsonschema.Schema { + inlineProps := orderedmap.New[string, *jsonschema.Schema]() + inlineProps.Set("kind", &jsonschema.Schema{Type: "string"}) + inlineProps.Set("metadata", &jsonschema.Schema{Ref: "#/$defs/Metadata"}) + inlineProps.Set("spec", &jsonschema.Schema{Ref: "#/$defs/AlertNotificationTargetSpec"}) + + refProps := orderedmap.New[string, *jsonschema.Schema]() + refProps.Set("targetRef", &jsonschema.Schema{Type: "string"}) + + return &jsonschema.Schema{ + Description: "A notification target that can be provided inline or as a reference.", + OneOf: []*jsonschema.Schema{ + { + Type: "object", + Properties: inlineProps, + Required: []string{"kind", "metadata", "spec"}, + AdditionalProperties: jsonschema.FalseSchema, + }, + { + Type: "object", + Properties: refProps, + Required: []string{"targetRef"}, + AdditionalProperties: jsonschema.FalseSchema, + }, + }, + } +} diff --git a/pkg/openslo/v1alpha/jsonschema.go b/pkg/openslo/v1alpha/jsonschema.go new file mode 100644 index 0000000..42d69c9 --- /dev/null +++ b/pkg/openslo/v1alpha/jsonschema.go @@ -0,0 +1,5 @@ +package v1alpha + +// v1alpha has no custom JSONSchema types. +// All structs are fully described by their json tags and Go comments, +// which are extracted by the jsonschema generator via AddGoComments. diff --git a/pkg/openslo/v2alpha/jsonschema.go b/pkg/openslo/v2alpha/jsonschema.go new file mode 100644 index 0000000..f527ec5 --- /dev/null +++ b/pkg/openslo/v2alpha/jsonschema.go @@ -0,0 +1,102 @@ +package v2alpha + +import ( + "github.com/invopop/jsonschema" + orderedmap "github.com/pb33f/ordered-map/v2" +) + +// JSONSchema returns a custom JSON Schema for DurationShorthand. +func (DurationShorthand) JSONSchema() *jsonschema.Schema { + return &jsonschema.Schema{ + Type: "string", + Description: "A shorthand representation of time duration, e.g. '1m', '10d', '2w'.", + Pattern: `^[0-9]+[mhdwMQY]$`, + } +} + +// JSONSchema returns a custom JSON Schema for SLOAlertPolicy. +func (SLOAlertPolicy) JSONSchema() *jsonschema.Schema { + inlineProps := orderedmap.New[string, *jsonschema.Schema]() + inlineProps.Set("kind", &jsonschema.Schema{Type: "string"}) + inlineProps.Set("metadata", &jsonschema.Schema{Ref: "#/$defs/Metadata"}) + inlineProps.Set("spec", &jsonschema.Schema{Ref: "#/$defs/AlertPolicySpec"}) + + refProps := orderedmap.New[string, *jsonschema.Schema]() + refProps.Set("alertPolicyRef", &jsonschema.Schema{Type: "string"}) + + return &jsonschema.Schema{ + Description: "An alert policy that can be provided inline or as a reference.", + OneOf: []*jsonschema.Schema{ + { + Type: "object", + Properties: inlineProps, + Required: []string{"kind", "metadata", "spec"}, + AdditionalProperties: jsonschema.FalseSchema, + }, + { + Type: "object", + Properties: refProps, + Required: []string{"alertPolicyRef"}, + AdditionalProperties: jsonschema.FalseSchema, + }, + }, + } +} + +// JSONSchema returns a custom JSON Schema for AlertPolicyCondition. +func (AlertPolicyCondition) JSONSchema() *jsonschema.Schema { + inlineProps := orderedmap.New[string, *jsonschema.Schema]() + inlineProps.Set("kind", &jsonschema.Schema{Type: "string"}) + inlineProps.Set("metadata", &jsonschema.Schema{Ref: "#/$defs/Metadata"}) + inlineProps.Set("spec", &jsonschema.Schema{Ref: "#/$defs/AlertConditionSpec"}) + + refProps := orderedmap.New[string, *jsonschema.Schema]() + refProps.Set("conditionRef", &jsonschema.Schema{Type: "string"}) + + return &jsonschema.Schema{ + Description: "An alert condition that can be provided inline or as a reference.", + OneOf: []*jsonschema.Schema{ + { + Type: "object", + Properties: inlineProps, + Required: []string{"kind", "metadata", "spec"}, + AdditionalProperties: jsonschema.FalseSchema, + }, + { + Type: "object", + Properties: refProps, + Required: []string{"conditionRef"}, + AdditionalProperties: jsonschema.FalseSchema, + }, + }, + } +} + +// JSONSchema returns a custom JSON Schema for AlertPolicyNotificationTarget. +func (AlertPolicyNotificationTarget) JSONSchema() *jsonschema.Schema { + inlineProps := orderedmap.New[string, *jsonschema.Schema]() + inlineProps.Set("kind", &jsonschema.Schema{Type: "string"}) + inlineProps.Set("metadata", &jsonschema.Schema{Ref: "#/$defs/Metadata"}) + inlineProps.Set("spec", &jsonschema.Schema{Ref: "#/$defs/AlertNotificationTargetSpec"}) + + refProps := orderedmap.New[string, *jsonschema.Schema]() + refProps.Set("targetRef", &jsonschema.Schema{Type: "string"}) + + return &jsonschema.Schema{ + Description: "A notification target that can be provided inline or as a reference.", + OneOf: []*jsonschema.Schema{ + { + Type: "object", + Properties: inlineProps, + Required: []string{"kind", "metadata", "spec"}, + AdditionalProperties: jsonschema.FalseSchema, + }, + { + Type: "object", + Properties: refProps, + Required: []string{"targetRef"}, + AdditionalProperties: jsonschema.FalseSchema, + }, + }, + } +} From 9f4477de5448f7d35aaf75dba9d3905214776df3 Mon Sep 17 00:00:00 2001 From: Ibrahim Diallo <20114089+thisisibrahimd@users.noreply.github.com> Date: Sun, 20 Sep 2026 09:57:37 -0400 Subject: [PATCH 2/2] feat: leverage new go comments on types and fields --- docs/jsonschema/v1/alert-condition.json | 54 ++++-- .../v1/alert-notification-target.json | 33 ++-- docs/jsonschema/v1/alert-policy.json | 45 +++-- docs/jsonschema/v1/data-source.json | 37 ++-- docs/jsonschema/v1/service.json | 30 ++-- docs/jsonschema/v1/sli.json | 69 +++++--- docs/jsonschema/v1/slo.json | 153 ++++++++++------ docs/jsonschema/v1alpha/service.json | 18 +- docs/jsonschema/v1alpha/slo.json | 109 ++++++++---- docs/jsonschema/v2alpha/alert-condition.json | 48 ++++-- .../v2alpha/alert-notification-target.json | 30 ++-- docs/jsonschema/v2alpha/alert-policy.json | 42 +++-- docs/jsonschema/v2alpha/data-source.json | 34 ++-- docs/jsonschema/v2alpha/service.json | 27 ++- docs/jsonschema/v2alpha/sli.json | 79 ++++++--- docs/jsonschema/v2alpha/slo.json | 163 ++++++++++++------ 16 files changed, 648 insertions(+), 323 deletions(-) diff --git a/docs/jsonschema/v1/alert-condition.json b/docs/jsonschema/v1/alert-condition.json index eeaf47b..82be220 100644 --- a/docs/jsonschema/v1/alert-condition.json +++ b/docs/jsonschema/v1/alert-condition.json @@ -7,13 +7,16 @@ "$anchor": "AlertConditionSpec", "properties": { "severity": { - "type": "string" + "type": "string", + "description": "Severity is an implementation-defined classification such as \"sev1\" or \"page\"." }, "condition": { - "$ref": "#/$defs/AlertConditionType" + "$ref": "#/$defs/AlertConditionType", + "description": "Condition defines the burn-rate comparison used to determine whether this alert condition is breaching." }, "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the alert condition." } }, "additionalProperties": false, @@ -21,25 +24,31 @@ "required": [ "severity", "condition" - ] + ], + "description": "AlertConditionSpec defines an alert's severity and burn-rate condition." }, "AlertConditionType": { "$anchor": "AlertConditionType", "properties": { "kind": { - "type": "string" + "type": "string", + "description": "Kind selects the condition calculation.\nOpenSLO defaults Kind to [AlertConditionKindBurnRate].\nThis SDK does not apply that default." }, "op": { - "type": "string" + "type": "string", + "description": "Operator compares the calculated burn rate with Threshold." }, "threshold": { - "type": "number" + "type": "number", + "description": "Threshold sets the numeric burn-rate boundary." }, "lookbackWindow": { - "$ref": "#/$defs/DurationShorthand" + "$ref": "#/$defs/DurationShorthand", + "description": "LookbackWindow sets the period for burn-rate calculation." }, "alertAfter": { - "$ref": "#/$defs/DurationShorthand" + "$ref": "#/$defs/DurationShorthand", + "description": "AlertAfter sets how long the burn-rate comparison must remain true before the condition becomes breaching.\nAn [AlertPolicy] controls whether that state triggers an alert.\nOpenSLO treats an omitted value as \"0m\".\nThis SDK leaves it unset." } }, "additionalProperties": false, @@ -49,13 +58,15 @@ "op", "threshold", "lookbackWindow" - ] + ], + "description": "AlertConditionType defines a comparison against an SLO's burn rate." }, "Annotations": { "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Annotations maps metadata keys to implementation- or system-specific values." }, "DurationShorthand": { "type": "string", @@ -80,29 +91,35 @@ "additionalProperties": { "$ref": "#/$defs/Label" }, - "type": "object" + "type": "object", + "description": "Labels maps each metadata key to a set of values." }, "Metadata": { "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name identifies the object." }, "displayName": { - "type": "string" + "type": "string", + "description": "DisplayName is the object's human-readable name." }, "labels": { - "$ref": "#/$defs/Labels" + "$ref": "#/$defs/Labels", + "description": "Labels contains metadata associated with the object." }, "annotations": { - "$ref": "#/$defs/Annotations" + "$ref": "#/$defs/Annotations", + "description": "Annotations contains implementation- or system-specific metadata." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata identifies and describes an OpenSLO v1 object." } }, "properties": { @@ -126,5 +143,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "AlertCondition defines a burn-rate condition for an SLO." } \ No newline at end of file diff --git a/docs/jsonschema/v1/alert-notification-target.json b/docs/jsonschema/v1/alert-notification-target.json index e9aafc8..9a31782 100644 --- a/docs/jsonschema/v1/alert-notification-target.json +++ b/docs/jsonschema/v1/alert-notification-target.json @@ -7,23 +7,27 @@ "$anchor": "AlertNotificationTargetSpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the notification target." }, "target": { - "type": "string" + "type": "string", + "description": "Target specifies the notification destination in the format required by the consuming implementation.\nExamples include email, Slack, a webhook, and Opsgenie." } }, "additionalProperties": false, "type": "object", "required": [ "target" - ] + ], + "description": "AlertNotificationTargetSpec defines an implementation-specific notification destination." }, "Annotations": { "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Annotations maps metadata keys to implementation- or system-specific values." }, "Label": { "oneOf": [ @@ -43,29 +47,35 @@ "additionalProperties": { "$ref": "#/$defs/Label" }, - "type": "object" + "type": "object", + "description": "Labels maps each metadata key to a set of values." }, "Metadata": { "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name identifies the object." }, "displayName": { - "type": "string" + "type": "string", + "description": "DisplayName is the object's human-readable name." }, "labels": { - "$ref": "#/$defs/Labels" + "$ref": "#/$defs/Labels", + "description": "Labels contains metadata associated with the object." }, "annotations": { - "$ref": "#/$defs/Annotations" + "$ref": "#/$defs/Annotations", + "description": "Annotations contains implementation- or system-specific metadata." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata identifies and describes an OpenSLO v1 object." } }, "properties": { @@ -89,5 +99,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "AlertNotificationTarget identifies a destination for SLO alert notifications." } \ No newline at end of file diff --git a/docs/jsonschema/v1/alert-policy.json b/docs/jsonschema/v1/alert-policy.json index 20b1527..eb3b648 100644 --- a/docs/jsonschema/v1/alert-policy.json +++ b/docs/jsonschema/v1/alert-policy.json @@ -81,38 +81,46 @@ "$anchor": "AlertPolicySpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the alert policy." }, "alertWhenNoData": { - "type": "boolean" + "type": "boolean", + "description": "AlertWhenNoData reports whether to trigger an alert when the associated [SLO] has no burn-rate value." }, "alertWhenBreaching": { - "type": "boolean" + "type": "boolean", + "description": "AlertWhenBreaching reports whether to trigger an alert when the condition is breaching." }, "alertWhenResolved": { - "type": "boolean" + "type": "boolean", + "description": "AlertWhenResolved reports whether to trigger an alert when the condition resolves." }, "conditions": { "items": { "$ref": "#/$defs/AlertPolicyCondition" }, - "type": "array" + "type": "array", + "description": "Conditions contains alert conditions specified inline or by reference." }, "notificationTargets": { "items": { "$ref": "#/$defs/AlertPolicyNotificationTarget" }, - "type": "array" + "type": "array", + "description": "NotificationTargets contains notification destinations.\nSpecify each destination inline or by reference." } }, "additionalProperties": false, - "type": "object" + "type": "object", + "description": "AlertPolicySpec defines which condition states trigger an SLO alert and where the consuming system delivers the resulting notifications." }, "Annotations": { "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Annotations maps metadata keys to implementation- or system-specific values." }, "Label": { "oneOf": [ @@ -132,29 +140,35 @@ "additionalProperties": { "$ref": "#/$defs/Label" }, - "type": "object" + "type": "object", + "description": "Labels maps each metadata key to a set of values." }, "Metadata": { "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name identifies the object." }, "displayName": { - "type": "string" + "type": "string", + "description": "DisplayName is the object's human-readable name." }, "labels": { - "$ref": "#/$defs/Labels" + "$ref": "#/$defs/Labels", + "description": "Labels contains metadata associated with the object." }, "annotations": { - "$ref": "#/$defs/Annotations" + "$ref": "#/$defs/Annotations", + "description": "Annotations contains implementation- or system-specific metadata." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata identifies and describes an OpenSLO v1 object." } }, "properties": { @@ -178,5 +192,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "AlertPolicy defines which alert-condition states trigger an SLO alert." } \ No newline at end of file diff --git a/docs/jsonschema/v1/data-source.json b/docs/jsonschema/v1/data-source.json index 1ab790e..13b563b 100644 --- a/docs/jsonschema/v1/data-source.json +++ b/docs/jsonschema/v1/data-source.json @@ -7,25 +7,31 @@ "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Annotations maps metadata keys to implementation- or system-specific values." }, "DataSourceSpec": { "$anchor": "DataSourceSpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the data source." }, "type": { - "type": "string" + "type": "string", + "description": "Type identifies the implementation-defined metric source type, such as Prometheus or Datadog." }, - "connectionDetails": true + "connectionDetails": { + "description": "ConnectionDetails contains implementation-defined connection data encoded as JSON.\nThe metric-source implementation defines its fields, which can include endpoints or authentication settings." + } }, "additionalProperties": false, "type": "object", "required": [ "type", "connectionDetails" - ] + ], + "description": "DataSourceSpec defines reusable, source-specific connection configuration." }, "Label": { "oneOf": [ @@ -45,29 +51,35 @@ "additionalProperties": { "$ref": "#/$defs/Label" }, - "type": "object" + "type": "object", + "description": "Labels maps each metadata key to a set of values." }, "Metadata": { "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name identifies the object." }, "displayName": { - "type": "string" + "type": "string", + "description": "DisplayName is the object's human-readable name." }, "labels": { - "$ref": "#/$defs/Labels" + "$ref": "#/$defs/Labels", + "description": "Labels contains metadata associated with the object." }, "annotations": { - "$ref": "#/$defs/Annotations" + "$ref": "#/$defs/Annotations", + "description": "Annotations contains implementation- or system-specific metadata." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata identifies and describes an OpenSLO v1 object." } }, "properties": { @@ -91,5 +103,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "DataSource represents reusable connection details for a metric source." } \ No newline at end of file diff --git a/docs/jsonschema/v1/service.json b/docs/jsonschema/v1/service.json index 20fb0fb..e44cd97 100644 --- a/docs/jsonschema/v1/service.json +++ b/docs/jsonschema/v1/service.json @@ -7,7 +7,8 @@ "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Annotations maps metadata keys to implementation- or system-specific values." }, "Label": { "oneOf": [ @@ -27,39 +28,47 @@ "additionalProperties": { "$ref": "#/$defs/Label" }, - "type": "object" + "type": "object", + "description": "Labels maps each metadata key to a set of values." }, "Metadata": { "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name identifies the object." }, "displayName": { - "type": "string" + "type": "string", + "description": "DisplayName is the object's human-readable name." }, "labels": { - "$ref": "#/$defs/Labels" + "$ref": "#/$defs/Labels", + "description": "Labels contains metadata associated with the object." }, "annotations": { - "$ref": "#/$defs/Annotations" + "$ref": "#/$defs/Annotations", + "description": "Annotations contains implementation- or system-specific metadata." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata identifies and describes an OpenSLO v1 object." }, "ServiceSpec": { "$anchor": "ServiceSpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the service." } }, "additionalProperties": false, - "type": "object" + "type": "object", + "description": "ServiceSpec contains the descriptive properties of a Service." } }, "properties": { @@ -83,5 +92,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "Service identifies a high-level group of SLO objects." } \ No newline at end of file diff --git a/docs/jsonschema/v1/sli.json b/docs/jsonschema/v1/sli.json index 85af2ac..c71a608 100644 --- a/docs/jsonschema/v1/sli.json +++ b/docs/jsonschema/v1/sli.json @@ -7,7 +7,8 @@ "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Annotations maps metadata keys to implementation- or system-specific values." }, "Label": { "oneOf": [ @@ -27,48 +28,58 @@ "additionalProperties": { "$ref": "#/$defs/Label" }, - "type": "object" + "type": "object", + "description": "Labels maps each metadata key to a set of values." }, "Metadata": { "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name identifies the object." }, "displayName": { - "type": "string" + "type": "string", + "description": "DisplayName is the object's human-readable name." }, "labels": { - "$ref": "#/$defs/Labels" + "$ref": "#/$defs/Labels", + "description": "Labels contains metadata associated with the object." }, "annotations": { - "$ref": "#/$defs/Annotations" + "$ref": "#/$defs/Annotations", + "description": "Annotations contains implementation- or system-specific metadata." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata identifies and describes an OpenSLO v1 object." }, "SLIMetricSource": { "$anchor": "SLIMetricSource", "properties": { "metricSourceRef": { - "type": "string" + "type": "string", + "description": "MetricSourceRef names an existing [DataSource]." }, "type": { - "type": "string" + "type": "string", + "description": "Type identifies the implementation-defined metric-source type.\nWhen [SLIMetricSource.MetricSourceRef] is set, OpenSLO infers Type from the referenced [DataSource]." }, "spec": { - "type": "object" + "type": "object", + "description": "Spec contains source-specific query or metric-retrieval configuration." } }, "additionalProperties": false, "type": "object", "required": [ "spec" - ] + ], + "description": "SLIMetricSource identifies a metrics backend and supplies the configuration needed to retrieve a metric." }, "SLIMetricSpec": { "$anchor": "SLIMetricSpec", @@ -81,51 +92,62 @@ "type": "object", "required": [ "metricSource" - ] + ], + "description": "SLIMetricSpec defines one query used to read metric data for an SLI." }, "SLIRatioMetric": { "$anchor": "SLIRatioMetric", "properties": { "counter": { - "type": "boolean" + "type": "boolean", + "description": "Counter reports whether the queried good, bad, and total metrics are monotonically increasing.\nIt has no effect when Raw is used." }, "good": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Good supplies the numerator for a good-over-total ratio." }, "bad": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Bad supplies the number subtracted from Total for a failure-based ratio." }, "total": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Total supplies the denominator for a Good- or Bad-based ratio." }, "rawType": { - "type": "string" + "type": "string", + "description": "RawType selects whether Raw is interpreted as a success or failure ratio when Raw is used." }, "raw": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Raw defines a query for a precomputed success or failure ratio." } }, "additionalProperties": false, "type": "object", "required": [ "counter" - ] + ], + "description": "SLIRatioMetric defines an indicator from good divided by total or (total minus bad) divided by total." }, "SLISpec": { "$anchor": "SLISpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the SLI." }, "thresholdMetric": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "ThresholdMetric defines a query that returns raw values.\n[SLOObjective.Operator] compares each value with [SLOObjective.Value]." }, "ratioMetric": { "$ref": "#/$defs/SLIRatioMetric" } }, "additionalProperties": false, - "type": "object" + "type": "object", + "description": "SLISpec defines the query or queries used to calculate an SLI." } }, "properties": { @@ -149,5 +171,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "SLI defines a derived reliability indicator and the queries used to calculate it for an SLO." } \ No newline at end of file diff --git a/docs/jsonschema/v1/slo.json b/docs/jsonschema/v1/slo.json index 727064d..6b95554 100644 --- a/docs/jsonschema/v1/slo.json +++ b/docs/jsonschema/v1/slo.json @@ -7,7 +7,8 @@ "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Annotations maps metadata keys to implementation- or system-specific values." }, "DurationShorthand": { "type": "string", @@ -32,48 +33,58 @@ "additionalProperties": { "$ref": "#/$defs/Label" }, - "type": "object" + "type": "object", + "description": "Labels maps each metadata key to a set of values." }, "Metadata": { "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name identifies the object." }, "displayName": { - "type": "string" + "type": "string", + "description": "DisplayName is the object's human-readable name." }, "labels": { - "$ref": "#/$defs/Labels" + "$ref": "#/$defs/Labels", + "description": "Labels contains metadata associated with the object." }, "annotations": { - "$ref": "#/$defs/Annotations" + "$ref": "#/$defs/Annotations", + "description": "Annotations contains implementation- or system-specific metadata." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata identifies and describes an OpenSLO v1 object." }, "SLIMetricSource": { "$anchor": "SLIMetricSource", "properties": { "metricSourceRef": { - "type": "string" + "type": "string", + "description": "MetricSourceRef names an existing [DataSource]." }, "type": { - "type": "string" + "type": "string", + "description": "Type identifies the implementation-defined metric-source type.\nWhen [SLIMetricSource.MetricSourceRef] is set, OpenSLO infers Type from the referenced [DataSource]." }, "spec": { - "type": "object" + "type": "object", + "description": "Spec contains source-specific query or metric-retrieval configuration." } }, "additionalProperties": false, "type": "object", "required": [ "spec" - ] + ], + "description": "SLIMetricSource identifies a metrics backend and supplies the configuration needed to retrieve a metric." }, "SLIMetricSpec": { "$anchor": "SLIMetricSpec", @@ -86,51 +97,62 @@ "type": "object", "required": [ "metricSource" - ] + ], + "description": "SLIMetricSpec defines one query used to read metric data for an SLI." }, "SLIRatioMetric": { "$anchor": "SLIRatioMetric", "properties": { "counter": { - "type": "boolean" + "type": "boolean", + "description": "Counter reports whether the queried good, bad, and total metrics are monotonically increasing.\nIt has no effect when Raw is used." }, "good": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Good supplies the numerator for a good-over-total ratio." }, "bad": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Bad supplies the number subtracted from Total for a failure-based ratio." }, "total": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Total supplies the denominator for a Good- or Bad-based ratio." }, "rawType": { - "type": "string" + "type": "string", + "description": "RawType selects whether Raw is interpreted as a success or failure ratio when Raw is used." }, "raw": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Raw defines a query for a precomputed success or failure ratio." } }, "additionalProperties": false, "type": "object", "required": [ "counter" - ] + ], + "description": "SLIRatioMetric defines an indicator from good divided by total or (total minus bad) divided by total." }, "SLISpec": { "$anchor": "SLISpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the SLI." }, "thresholdMetric": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "ThresholdMetric defines a query that returns raw values.\n[SLOObjective.Operator] compares each value with [SLOObjective.Value]." }, "ratioMetric": { "$ref": "#/$defs/SLIRatioMetric" } }, "additionalProperties": false, - "type": "object" + "type": "object", + "description": "SLISpec defines the query or queries used to calculate an SLI." }, "SLOAlertPolicy": { "oneOf": [ @@ -173,10 +195,12 @@ "$anchor": "SLOCalendar", "properties": { "startTime": { - "type": "string" + "type": "string", + "description": "StartTime anchors the first calendar window." }, "timeZone": { - "type": "string" + "type": "string", + "description": "TimeZone controls the interpretation of StartTime and later boundaries." } }, "additionalProperties": false, @@ -184,7 +208,8 @@ "required": [ "startTime", "timeZone" - ] + ], + "description": "SLOCalendar anchors a calendar-aligned SLOTimeWindow in a time zone." }, "SLOIndicatorInline": { "$anchor": "SLOIndicatorInline", @@ -201,80 +226,100 @@ "required": [ "metadata", "spec" - ] + ], + "description": "SLOIndicatorInline embeds an SLI in an SLOSpec or SLOObjective." }, "SLOObjective": { "$anchor": "SLOObjective", "properties": { "displayName": { - "type": "string" + "type": "string", + "description": "DisplayName is the objective's human-readable name." }, "op": { - "type": "string" + "type": "string", + "description": "Operator compares threshold-metric samples with Value." }, "value": { - "type": "number" + "type": "number", + "description": "Value sets the threshold for metric sample comparisons.\nIt is distinct from the success target expressed by Target or TargetPercent." }, "target": { - "type": "number" + "type": "number", + "description": "Target expresses the success target as a fraction." }, "targetPercent": { - "type": "number" + "type": "number", + "description": "TargetPercent expresses the success target as a percentage." }, "timeSliceTarget": { - "type": "number" + "type": "number", + "description": "TimeSliceTarget classifies a slice as good when BudgetingMethod is [SLOBudgetingMethodTimeslices]." }, "timeSliceWindow": { - "$ref": "#/$defs/DurationShorthand" + "$ref": "#/$defs/DurationShorthand", + "description": "TimeSliceWindow sets the slice size and query interval.\nIt applies to [SLOBudgetingMethodTimeslices] and [SLOBudgetingMethodRatioTimeslices].\nThis Go model supports [DurationShorthand] only.\nOpenSLO also permits a number, which it interprets as minutes." }, "indicator": { - "$ref": "#/$defs/SLOIndicatorInline" + "$ref": "#/$defs/SLOIndicatorInline", + "description": "Indicator defines this objective's SLI inline for a composite SLO." }, "indicatorRef": { - "type": "string" + "type": "string", + "description": "IndicatorRef names this objective's [SLI] for a composite SLO." }, "compositeWeight": { - "type": "number" + "type": "number", + "description": "CompositeWeight scales this objective's contribution to a composite SLO.\nOpenSLO defaults it to 1, but this SDK preserves an omitted value as nil." } }, "additionalProperties": false, - "type": "object" + "type": "object", + "description": "SLOObjective defines a success target and, when applicable, a threshold comparison or composite-specific indicator." }, "SLOSpec": { "$anchor": "SLOSpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the SLO." }, "service": { - "type": "string" + "type": "string", + "description": "Service names the associated service.\nConsumers define how to resolve the name to a [Service]." }, "indicator": { - "$ref": "#/$defs/SLOIndicatorInline" + "$ref": "#/$defs/SLOIndicatorInline", + "description": "Indicator defines a standard SLO's SLI inline.\nComposite SLOs place indicators on individual Objectives." }, "indicatorRef": { - "type": "string" + "type": "string", + "description": "IndicatorRef names an existing [SLI] for a standard SLO.\nComposite SLOs place indicator references on individual Objectives." }, "budgetingMethod": { - "type": "string" + "type": "string", + "description": "BudgetingMethod applies the selected error-budget calculation to every objective." }, "timeWindow": { "items": { "$ref": "#/$defs/SLOTimeWindow" }, - "type": "array" + "type": "array", + "description": "TimeWindow defines the period over which the SLO is evaluated." }, "objectives": { "items": { "$ref": "#/$defs/SLOObjective" }, - "type": "array" + "type": "array", + "description": "Objectives contains the SLO's target definitions." }, "alertPolicies": { "items": { "$ref": "#/$defs/SLOAlertPolicy" }, - "type": "array" + "type": "array", + "description": "AlertPolicies contains inline alert policies or references to existing [AlertPolicy] objects." } }, "additionalProperties": false, @@ -283,19 +328,23 @@ "service", "budgetingMethod", "objectives" - ] + ], + "description": "SLOSpec defines the service association, indicator placement, budgeting method, evaluation window, objectives, and alert policies of an SLO." }, "SLOTimeWindow": { "$anchor": "SLOTimeWindow", "properties": { "duration": { - "$ref": "#/$defs/DurationShorthand" + "$ref": "#/$defs/DurationShorthand", + "description": "Duration is the length of the evaluation window." }, "isRolling": { - "type": "boolean" + "type": "boolean", + "description": "IsRolling selects a rolling window when true and a calendar-aligned window when false." }, "calendar": { - "$ref": "#/$defs/SLOCalendar" + "$ref": "#/$defs/SLOCalendar", + "description": "Calendar defines the alignment of a calendar window." } }, "additionalProperties": false, @@ -303,7 +352,8 @@ "required": [ "duration", "isRolling" - ] + ], + "description": "SLOTimeWindow defines one rolling or calendar-aligned evaluation window." } }, "properties": { @@ -327,5 +377,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "SLO represents a target value or range for a service level measured by an SLI." } \ No newline at end of file diff --git a/docs/jsonschema/v1alpha/service.json b/docs/jsonschema/v1alpha/service.json index d01549d..37deabe 100644 --- a/docs/jsonschema/v1alpha/service.json +++ b/docs/jsonschema/v1alpha/service.json @@ -7,27 +7,32 @@ "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the object identifier used by references." }, "displayName": { - "type": "string" + "type": "string", + "description": "DisplayName is a human-readable name." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata identifies an OpenSLO v1alpha object." }, "ServiceSpec": { "$anchor": "ServiceSpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the service." } }, "additionalProperties": false, - "type": "object" + "type": "object", + "description": "ServiceSpec contains the descriptive properties of a Service." } }, "properties": { @@ -51,5 +56,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "Service is the legacy v1alpha Service representation supported by this SDK." } \ No newline at end of file diff --git a/docs/jsonschema/v1alpha/slo.json b/docs/jsonschema/v1alpha/slo.json index 7da197f..09915c6 100644 --- a/docs/jsonschema/v1alpha/slo.json +++ b/docs/jsonschema/v1alpha/slo.json @@ -7,26 +7,31 @@ "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name is the object identifier used by references." }, "displayName": { - "type": "string" + "type": "string", + "description": "DisplayName is a human-readable name." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata identifies an OpenSLO v1alpha object." }, "SLOCalendar": { "$anchor": "SLOCalendar", "properties": { "startTime": { - "type": "string" + "type": "string", + "description": "StartTime anchors the first calendar window." }, "timeZone": { - "type": "string" + "type": "string", + "description": "TimeZone controls the interpretation of StartTime and later boundaries." } }, "additionalProperties": false, @@ -34,32 +39,38 @@ "required": [ "startTime", "timeZone" - ] + ], + "description": "SLOCalendar anchors a calendar-aligned SLOTimeWindow." }, "SLOIndicator": { "$anchor": "SLOIndicator", "properties": { "thresholdMetric": { - "$ref": "#/$defs/SLOMetricSourceSpec" + "$ref": "#/$defs/SLOMetricSourceSpec", + "description": "ThresholdMetric retrieves raw metric values.\nEach objective compares them with its [Operator] and Value." } }, "additionalProperties": false, "type": "object", "required": [ "thresholdMetric" - ] + ], + "description": "SLOIndicator defines the threshold-metric form of a v1alpha service level indicator." }, "SLOMetricSourceSpec": { "$anchor": "SLOMetricSourceSpec", "properties": { "source": { - "type": "string" + "type": "string", + "description": "Source identifies the metric data source." }, "queryType": { - "type": "string" + "type": "string", + "description": "QueryType identifies the query language or query form." }, "query": { - "type": "string" + "type": "string", + "description": "Query is the provider-specific expression that retrieves the metric." } }, "additionalProperties": false, @@ -68,50 +79,60 @@ "source", "queryType", "query" - ] + ], + "description": "SLOMetricSourceSpec describes a provider-specific metric query." }, "SLOObjective": { "$anchor": "SLOObjective", "properties": { "displayName": { - "type": "string" + "type": "string", + "description": "DisplayName is a human-readable objective name." }, "value": { - "type": "number" + "type": "number", + "description": "Value is the metric threshold used by [Operator]." }, "ratioMetrics": { - "$ref": "#/$defs/SLORatioMetrics" + "$ref": "#/$defs/SLORatioMetrics", + "description": "RatioMetrics supplies a good-events-to-total-events indicator." }, "target": { - "type": "number" + "type": "number", + "description": "BudgetTarget is the desired fraction of good events or time slices." }, "timeSliceTarget": { - "type": "number" + "type": "number", + "description": "TimeSliceTarget is the minimum success ratio that makes a time slice good.\nIt is used by the Timeslices budgeting method." }, "op": { - "type": "string" + "type": "string", + "description": "Operator compares values returned by the threshold metric with Value." } }, "additionalProperties": false, "type": "object", "required": [ "displayName", - "value", "ratioMetrics", "target" - ] + ], + "description": "SLOObjective defines a reliability target and, for the ratio form, its metric queries." }, "SLORatioMetrics": { "$anchor": "SLORatioMetrics", "properties": { "good": { - "$ref": "#/$defs/SLOMetricSourceSpec" + "$ref": "#/$defs/SLOMetricSourceSpec", + "description": "Good retrieves the numerator: events considered successful." }, "total": { - "$ref": "#/$defs/SLOMetricSourceSpec" + "$ref": "#/$defs/SLOMetricSourceSpec", + "description": "Total retrieves the denominator: all considered events." }, "incremental": { - "type": "boolean" + "type": "boolean", + "description": "Incremental reports whether the queried metrics are monotonically increasing counters\nrather than values that can rise or fall." } }, "additionalProperties": false, @@ -120,7 +141,8 @@ "good", "total", "incremental" - ] + ], + "description": "SLORatioMetrics defines an indicator as the ratio of good events to total events." }, "SLOSpec": { "$anchor": "SLOSpec", @@ -129,25 +151,31 @@ "items": { "$ref": "#/$defs/SLOTimeWindow" }, - "type": "array" + "type": "array", + "description": "TimeWindows defines the period over which the SLO is evaluated." }, "budgetingMethod": { - "type": "string" + "type": "string", + "description": "BudgetingMethod applies the selected error-budget calculation to every objective." }, "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the SLO." }, "indicator": { - "$ref": "#/$defs/SLOIndicator" + "$ref": "#/$defs/SLOIndicator", + "description": "Indicator defines the threshold-metric form of the SLO." }, "service": { - "type": "string" + "type": "string", + "description": "Service is the metadata name of the [Service] whose reliability the SLO measures." }, "objectives": { "items": { "$ref": "#/$defs/SLOObjective" }, - "type": "array" + "type": "array", + "description": "Objectives contains reliability targets.\nFor the ratio form, each objective's [SLOObjective.RatioMetrics] defines the SLI metric queries." } }, "additionalProperties": false, @@ -158,22 +186,27 @@ "indicator", "service", "objectives" - ] + ], + "description": "SLOSpec defines the service, indicator, objectives, time window, and error-budget calculation for an SLO." }, "SLOTimeWindow": { "$anchor": "SLOTimeWindow", "properties": { "unit": { - "type": "string" + "type": "string", + "description": "Unit combines with Count to set the window length." }, "count": { - "type": "integer" + "type": "integer", + "description": "Count sets how many Units form the window." }, "isRolling": { - "type": "boolean" + "type": "boolean", + "description": "IsRolling selects a continuously advancing window when true and a calendar-aligned window when false." }, "calendar": { - "$ref": "#/$defs/SLOCalendar" + "$ref": "#/$defs/SLOCalendar", + "description": "Calendar defines the alignment of a calendar window." } }, "additionalProperties": false, @@ -182,7 +215,8 @@ "unit", "count", "isRolling" - ] + ], + "description": "SLOTimeWindow defines the period over which an SLO is evaluated." } }, "properties": { @@ -206,5 +240,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "SLO is the legacy v1alpha SLO representation supported by this SDK." } \ No newline at end of file diff --git a/docs/jsonschema/v2alpha/alert-condition.json b/docs/jsonschema/v2alpha/alert-condition.json index f0de5cf..31c0981 100644 --- a/docs/jsonschema/v2alpha/alert-condition.json +++ b/docs/jsonschema/v2alpha/alert-condition.json @@ -7,13 +7,15 @@ "$anchor": "AlertConditionSpec", "properties": { "severity": { - "type": "string" + "type": "string", + "description": "Severity is a consumer-defined alert classification." }, "condition": { "$ref": "#/$defs/AlertConditionType" }, "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the alert condition." } }, "additionalProperties": false, @@ -21,25 +23,31 @@ "required": [ "severity", "condition" - ] + ], + "description": "AlertConditionSpec defines an alert's severity and breach condition." }, "AlertConditionType": { "$anchor": "AlertConditionType", "properties": { "kind": { - "type": "string" + "type": "string", + "description": "Kind selects the condition algorithm." }, "op": { - "type": "string" + "type": "string", + "description": "Operator compares the calculated burn rate with Threshold." }, "threshold": { - "type": "number" + "type": "number", + "description": "Threshold sets the numeric burn-rate boundary." }, "lookbackWindow": { - "$ref": "#/$defs/DurationShorthand" + "$ref": "#/$defs/DurationShorthand", + "description": "LookbackWindow sets the period for burn-rate calculation." }, "alertAfter": { - "$ref": "#/$defs/DurationShorthand" + "$ref": "#/$defs/DurationShorthand", + "description": "AlertAfter sets how long the burn-rate comparison must remain true before the condition becomes breaching." } }, "additionalProperties": false, @@ -50,13 +58,15 @@ "threshold", "lookbackWindow", "alertAfter" - ] + ], + "description": "AlertConditionType defines a burn-rate comparison over a lookback window." }, "Annotations": { "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Annotations maps annotation keys to arbitrary string values." }, "DurationShorthand": { "type": "string", @@ -67,26 +77,31 @@ "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Labels maps label keys to one string value each." }, "Metadata": { "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name identifies the object when other OpenSLO objects refer to it." }, "labels": { - "$ref": "#/$defs/Labels" + "$ref": "#/$defs/Labels", + "description": "Labels classifies the object with Kubernetes-style, single-valued labels." }, "annotations": { - "$ref": "#/$defs/Annotations" + "$ref": "#/$defs/Annotations", + "description": "Annotations attaches non-identifying metadata to the object." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata is the Kubernetes-style identifying metadata used by v2alpha objects." } }, "properties": { @@ -110,5 +125,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "AlertCondition defines when an SLO alert condition is breaching." } \ No newline at end of file diff --git a/docs/jsonschema/v2alpha/alert-notification-target.json b/docs/jsonschema/v2alpha/alert-notification-target.json index ab23345..6da9ba6 100644 --- a/docs/jsonschema/v2alpha/alert-notification-target.json +++ b/docs/jsonschema/v2alpha/alert-notification-target.json @@ -7,48 +7,57 @@ "$anchor": "AlertNotificationTargetSpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the target." }, "target": { - "type": "string" + "type": "string", + "description": "Target specifies the notification destination in the format that the consuming implementation requires.\nExamples include \"email\", \"slack\", \"web-hook\", and \"Opsgenie\"." } }, "additionalProperties": false, "type": "object", "required": [ "target" - ] + ], + "description": "AlertNotificationTargetSpec identifies a notification destination." }, "Annotations": { "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Annotations maps annotation keys to arbitrary string values." }, "Labels": { "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Labels maps label keys to one string value each." }, "Metadata": { "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name identifies the object when other OpenSLO objects refer to it." }, "labels": { - "$ref": "#/$defs/Labels" + "$ref": "#/$defs/Labels", + "description": "Labels classifies the object with Kubernetes-style, single-valued labels." }, "annotations": { - "$ref": "#/$defs/Annotations" + "$ref": "#/$defs/Annotations", + "description": "Annotations attaches non-identifying metadata to the object." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata is the Kubernetes-style identifying metadata used by v2alpha objects." } }, "properties": { @@ -72,5 +81,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "AlertNotificationTarget represents a destination for alert delivery." } \ No newline at end of file diff --git a/docs/jsonschema/v2alpha/alert-policy.json b/docs/jsonschema/v2alpha/alert-policy.json index 7436437..5dcb98a 100644 --- a/docs/jsonschema/v2alpha/alert-policy.json +++ b/docs/jsonschema/v2alpha/alert-policy.json @@ -81,63 +81,76 @@ "$anchor": "AlertPolicySpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the alert policy." }, "alertWhenNoData": { - "type": "boolean" + "type": "boolean", + "description": "AlertWhenNoData controls whether a missing burn-rate value triggers an alert." }, "alertWhenBreaching": { - "type": "boolean" + "type": "boolean", + "description": "AlertWhenBreaching controls whether a breaching condition triggers an alert." }, "alertWhenResolved": { - "type": "boolean" + "type": "boolean", + "description": "AlertWhenResolved controls whether a resolved condition triggers an alert." }, "conditions": { "items": { "$ref": "#/$defs/AlertPolicyCondition" }, - "type": "array" + "type": "array", + "description": "Conditions contains alert conditions specified inline or by reference." }, "notificationTargets": { "items": { "$ref": "#/$defs/AlertPolicyNotificationTarget" }, - "type": "array" + "type": "array", + "description": "NotificationTargets contains delivery destinations.\nSpecify each destination inline or by reference." } }, "additionalProperties": false, - "type": "object" + "type": "object", + "description": "AlertPolicySpec defines the trigger states, condition, and notification destinations for an AlertPolicy." }, "Annotations": { "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Annotations maps annotation keys to arbitrary string values." }, "Labels": { "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Labels maps label keys to one string value each." }, "Metadata": { "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name identifies the object when other OpenSLO objects refer to it." }, "labels": { - "$ref": "#/$defs/Labels" + "$ref": "#/$defs/Labels", + "description": "Labels classifies the object with Kubernetes-style, single-valued labels." }, "annotations": { - "$ref": "#/$defs/Annotations" + "$ref": "#/$defs/Annotations", + "description": "Annotations attaches non-identifying metadata to the object." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata is the Kubernetes-style identifying metadata used by v2alpha objects." } }, "properties": { @@ -161,5 +174,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "AlertPolicy defines which alert-condition states trigger an SLO alert." } \ No newline at end of file diff --git a/docs/jsonschema/v2alpha/data-source.json b/docs/jsonschema/v2alpha/data-source.json index 23643f5..fc18147 100644 --- a/docs/jsonschema/v2alpha/data-source.json +++ b/docs/jsonschema/v2alpha/data-source.json @@ -7,50 +7,61 @@ "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Annotations maps annotation keys to arbitrary string values." }, "DataSourceSpec": { "$anchor": "DataSourceSpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the data source." }, "type": { - "type": "string" + "type": "string", + "description": "Type identifies the metric-source type, such as Prometheus or Datadog.\nThe consuming implementation defines the accepted values." }, - "connectionDetails": true + "connectionDetails": { + "description": "ConnectionDetails contains implementation-defined connection data encoded as JSON,\nsuch as endpoints or authentication settings." + } }, "additionalProperties": false, "type": "object", "required": [ "type", "connectionDetails" - ] + ], + "description": "DataSourceSpec defines a metric-source type and its implementation-defined connection data." }, "Labels": { "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Labels maps label keys to one string value each." }, "Metadata": { "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name identifies the object when other OpenSLO objects refer to it." }, "labels": { - "$ref": "#/$defs/Labels" + "$ref": "#/$defs/Labels", + "description": "Labels classifies the object with Kubernetes-style, single-valued labels." }, "annotations": { - "$ref": "#/$defs/Annotations" + "$ref": "#/$defs/Annotations", + "description": "Annotations attaches non-identifying metadata to the object." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata is the Kubernetes-style identifying metadata used by v2alpha objects." } }, "properties": { @@ -74,5 +85,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "DataSource represents reusable connection details for a metric source." } \ No newline at end of file diff --git a/docs/jsonschema/v2alpha/service.json b/docs/jsonschema/v2alpha/service.json index c139fa1..6653c1a 100644 --- a/docs/jsonschema/v2alpha/service.json +++ b/docs/jsonschema/v2alpha/service.json @@ -7,42 +7,50 @@ "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Annotations maps annotation keys to arbitrary string values." }, "Labels": { "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Labels maps label keys to one string value each." }, "Metadata": { "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name identifies the object when other OpenSLO objects refer to it." }, "labels": { - "$ref": "#/$defs/Labels" + "$ref": "#/$defs/Labels", + "description": "Labels classifies the object with Kubernetes-style, single-valued labels." }, "annotations": { - "$ref": "#/$defs/Annotations" + "$ref": "#/$defs/Annotations", + "description": "Annotations attaches non-identifying metadata to the object." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata is the Kubernetes-style identifying metadata used by v2alpha objects." }, "ServiceSpec": { "$anchor": "ServiceSpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the service." } }, "additionalProperties": false, - "type": "object" + "type": "object", + "description": "ServiceSpec defines the descriptive attributes of a Service." } }, "properties": { @@ -66,5 +74,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "Service identifies a high-level group for SLOs." } \ No newline at end of file diff --git a/docs/jsonschema/v2alpha/sli.json b/docs/jsonschema/v2alpha/sli.json index 9cc297c..48e88f5 100644 --- a/docs/jsonschema/v2alpha/sli.json +++ b/docs/jsonschema/v2alpha/sli.json @@ -7,110 +7,136 @@ "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Annotations maps annotation keys to arbitrary string values." }, "DataSourceSpec": { "$anchor": "DataSourceSpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the data source." }, "type": { - "type": "string" + "type": "string", + "description": "Type identifies the metric-source type, such as Prometheus or Datadog.\nThe consuming implementation defines the accepted values." }, - "connectionDetails": true + "connectionDetails": { + "description": "ConnectionDetails contains implementation-defined connection data encoded as JSON,\nsuch as endpoints or authentication settings." + } }, "additionalProperties": false, "type": "object", "required": [ "type", "connectionDetails" - ] + ], + "description": "DataSourceSpec defines a metric-source type and its implementation-defined connection data." }, "Labels": { "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Labels maps label keys to one string value each." }, "Metadata": { "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name identifies the object when other OpenSLO objects refer to it." }, "labels": { - "$ref": "#/$defs/Labels" + "$ref": "#/$defs/Labels", + "description": "Labels classifies the object with Kubernetes-style, single-valued labels." }, "annotations": { - "$ref": "#/$defs/Annotations" + "$ref": "#/$defs/Annotations", + "description": "Annotations attaches non-identifying metadata to the object." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata is the Kubernetes-style identifying metadata used by v2alpha objects." }, "SLIMetricSpec": { "$anchor": "SLIMetricSpec", "properties": { "dataSourceRef": { - "type": "string" + "type": "string", + "description": "DataSourceRef names an existing [DataSource]." }, "dataSourceSpec": { - "$ref": "#/$defs/DataSourceSpec" + "$ref": "#/$defs/DataSourceSpec", + "description": "DataSourceSpec embeds the complete data-source connection configuration." }, "spec": { - "type": "object" + "type": "object", + "description": "Spec contains implementation-defined query configuration at the same level as the data-source selection." } }, "additionalProperties": false, - "type": "object" + "type": "object", + "description": "SLIMetricSpec supplies an implementation-defined query in the v2alpha flattened layout." }, "SLIRatioMetric": { "$anchor": "SLIRatioMetric", "properties": { "counter": { - "type": "boolean" + "type": "boolean", + "description": "Counter reports whether the good, bad, and total metrics are monotonically increasing counters.\nIt has no effect when Raw is used." }, "good": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Good is the success-count numerator used with Total." }, "bad": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Bad is the failure-count input used with Total to derive successes." }, "total": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Total is the denominator paired with Good or Bad." }, "rawType": { - "type": "string" + "type": "string", + "description": "RawType identifies whether Raw contains a success or failure ratio when Raw is used." }, "raw": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Raw supplies an already computed ratio." } }, "additionalProperties": false, "type": "object", "required": [ "counter" - ] + ], + "description": "SLIRatioMetric defines an indicator as SLIRatioMetric.Good divided by SLIRatioMetric.Total, (SLIRatioMetric.Total minus SLIRatioMetric.Bad) divided by SLIRatioMetric.Total, or SLIRatioMetric.Raw." }, "SLISpec": { "$anchor": "SLISpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the indicator." }, "thresholdMetric": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "ThresholdMetric defines a query that returns raw values.\n[SLOObjective.Operator] compares each value with [SLOObjective.Value]." }, "ratioMetric": { - "$ref": "#/$defs/SLIRatioMetric" + "$ref": "#/$defs/SLIRatioMetric", + "description": "RatioMetric defines component queries or a precomputed ratio for an SLO objective." } }, "additionalProperties": false, - "type": "object" + "type": "object", + "description": "SLISpec defines the query or queries used to calculate an SLI." } }, "properties": { @@ -134,5 +160,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "SLI defines a derived reliability indicator calculated from one or more metric queries against data sources." } \ No newline at end of file diff --git a/docs/jsonschema/v2alpha/slo.json b/docs/jsonschema/v2alpha/slo.json index 3ad32ba..4011488 100644 --- a/docs/jsonschema/v2alpha/slo.json +++ b/docs/jsonschema/v2alpha/slo.json @@ -7,25 +7,31 @@ "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Annotations maps annotation keys to arbitrary string values." }, "DataSourceSpec": { "$anchor": "DataSourceSpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the data source." }, "type": { - "type": "string" + "type": "string", + "description": "Type identifies the metric-source type, such as Prometheus or Datadog.\nThe consuming implementation defines the accepted values." }, - "connectionDetails": true + "connectionDetails": { + "description": "ConnectionDetails contains implementation-defined connection data encoded as JSON,\nsuch as endpoints or authentication settings." + } }, "additionalProperties": false, "type": "object", "required": [ "type", "connectionDetails" - ] + ], + "description": "DataSourceSpec defines a metric-source type and its implementation-defined connection data." }, "DurationShorthand": { "type": "string", @@ -36,86 +42,106 @@ "additionalProperties": { "type": "string" }, - "type": "object" + "type": "object", + "description": "Labels maps label keys to one string value each." }, "Metadata": { "$anchor": "Metadata", "properties": { "name": { - "type": "string" + "type": "string", + "description": "Name identifies the object when other OpenSLO objects refer to it." }, "labels": { - "$ref": "#/$defs/Labels" + "$ref": "#/$defs/Labels", + "description": "Labels classifies the object with Kubernetes-style, single-valued labels." }, "annotations": { - "$ref": "#/$defs/Annotations" + "$ref": "#/$defs/Annotations", + "description": "Annotations attaches non-identifying metadata to the object." } }, "additionalProperties": false, "type": "object", "required": [ "name" - ] + ], + "description": "Metadata is the Kubernetes-style identifying metadata used by v2alpha objects." }, "SLIMetricSpec": { "$anchor": "SLIMetricSpec", "properties": { "dataSourceRef": { - "type": "string" + "type": "string", + "description": "DataSourceRef names an existing [DataSource]." }, "dataSourceSpec": { - "$ref": "#/$defs/DataSourceSpec" + "$ref": "#/$defs/DataSourceSpec", + "description": "DataSourceSpec embeds the complete data-source connection configuration." }, "spec": { - "type": "object" + "type": "object", + "description": "Spec contains implementation-defined query configuration at the same level as the data-source selection." } }, "additionalProperties": false, - "type": "object" + "type": "object", + "description": "SLIMetricSpec supplies an implementation-defined query in the v2alpha flattened layout." }, "SLIRatioMetric": { "$anchor": "SLIRatioMetric", "properties": { "counter": { - "type": "boolean" + "type": "boolean", + "description": "Counter reports whether the good, bad, and total metrics are monotonically increasing counters.\nIt has no effect when Raw is used." }, "good": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Good is the success-count numerator used with Total." }, "bad": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Bad is the failure-count input used with Total to derive successes." }, "total": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Total is the denominator paired with Good or Bad." }, "rawType": { - "type": "string" + "type": "string", + "description": "RawType identifies whether Raw contains a success or failure ratio when Raw is used." }, "raw": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "Raw supplies an already computed ratio." } }, "additionalProperties": false, "type": "object", "required": [ "counter" - ] + ], + "description": "SLIRatioMetric defines an indicator as SLIRatioMetric.Good divided by SLIRatioMetric.Total, (SLIRatioMetric.Total minus SLIRatioMetric.Bad) divided by SLIRatioMetric.Total, or SLIRatioMetric.Raw." }, "SLISpec": { "$anchor": "SLISpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the indicator." }, "thresholdMetric": { - "$ref": "#/$defs/SLIMetricSpec" + "$ref": "#/$defs/SLIMetricSpec", + "description": "ThresholdMetric defines a query that returns raw values.\n[SLOObjective.Operator] compares each value with [SLOObjective.Value]." }, "ratioMetric": { - "$ref": "#/$defs/SLIRatioMetric" + "$ref": "#/$defs/SLIRatioMetric", + "description": "RatioMetric defines component queries or a precomputed ratio for an SLO objective." } }, "additionalProperties": false, - "type": "object" + "type": "object", + "description": "SLISpec defines the query or queries used to calculate an SLI." }, "SLOAlertPolicy": { "oneOf": [ @@ -158,10 +184,12 @@ "$anchor": "SLOCalendar", "properties": { "startTime": { - "type": "string" + "type": "string", + "description": "StartTime is the local date and time when calendar alignment starts." }, "timeZone": { - "type": "string" + "type": "string", + "description": "TimeZone determines how StartTime maps to an instant." } }, "additionalProperties": false, @@ -169,44 +197,56 @@ "required": [ "startTime", "timeZone" - ] + ], + "description": "SLOCalendar defines the starting wall-clock time and time zone for a calendar-aligned SLOTimeWindow." }, "SLOObjective": { "$anchor": "SLOObjective", "properties": { "displayName": { - "type": "string" + "type": "string", + "description": "DisplayName is a human-readable name for this objective.\nIt is not part of the enclosing object's [Metadata]." }, "op": { - "type": "string" + "type": "string", + "description": "Operator compares a threshold metric with Value." }, "value": { - "type": "number" + "type": "number", + "description": "Value is the comparison threshold for a threshold metric." }, "target": { - "type": "number" + "type": "number", + "description": "Target is the desired success proportion.\nFor example, 0.995 means 99.5 percent." }, "targetPercent": { - "type": "number" + "type": "number", + "description": "TargetPercent is the desired success percentage." }, "timeSliceTarget": { - "type": "number" + "type": "number", + "description": "TimeSliceTarget sets the per-slice success threshold for Timeslices." }, "timeSliceWindow": { - "$ref": "#/$defs/DurationShorthand" + "$ref": "#/$defs/DurationShorthand", + "description": "TimeSliceWindow sets the size of each slice for Timeslices and RatioTimeslices.\nOpenSLO also accepts a number interpreted as minutes.\nThis SDK represents only duration shorthand." }, "sli": { - "$ref": "#/$defs/SLOSLIInline" + "$ref": "#/$defs/SLOSLIInline", + "description": "SLI embeds this objective's service level indicator for a composite SLO." }, "sliRef": { - "type": "string" + "type": "string", + "description": "SLIRef names this objective's existing [SLI] for a composite SLO." }, "compositeWeight": { - "type": "number" + "type": "number", + "description": "CompositeWeight scales this objective's contribution to a composite SLO.\nThe living v2alpha proposal defaults it to 1, but this SDK preserves an omitted value as nil." } }, "additionalProperties": false, - "type": "object" + "type": "object", + "description": "SLOObjective defines one error-budget target and, for a threshold SLI, its metric comparison." }, "SLOSLIInline": { "$anchor": "SLOSLIInline", @@ -223,43 +263,52 @@ "required": [ "metadata", "spec" - ] + ], + "description": "SLOSLIInline embeds an SLI definition in an SLO or one of its objectives." }, "SLOSpec": { "$anchor": "SLOSpec", "properties": { "description": { - "type": "string" + "type": "string", + "description": "Description summarizes the SLO." }, "serviceRef": { - "type": "string" + "type": "string", + "description": "ServiceRef names the service associated with this SLO.\nThe SDK serializes the field as \"serviceRef\".\nThe living v2alpha proposal calls it \"service\"." }, "sli": { - "$ref": "#/$defs/SLOSLIInline" + "$ref": "#/$defs/SLOSLIInline", + "description": "SLI embeds the service level indicator for a standard SLO." }, "sliRef": { - "type": "string" + "type": "string", + "description": "SLIRef names an existing [SLI] for a standard SLO." }, "budgetingMethod": { - "type": "string" + "type": "string", + "description": "BudgetingMethod applies the selected error-budget calculation to every objective." }, "timeWindow": { "items": { "$ref": "#/$defs/SLOTimeWindow" }, - "type": "array" + "type": "array", + "description": "TimeWindow defines the period over which the SLO is evaluated." }, "objectives": { "items": { "$ref": "#/$defs/SLOObjective" }, - "type": "array" + "type": "array", + "description": "Objectives contains the SLO's budget targets and metric thresholds." }, "alertPolicies": { "items": { "$ref": "#/$defs/SLOAlertPolicy" }, - "type": "array" + "type": "array", + "description": "AlertPolicies contains inline alert policies or references to existing [AlertPolicy] objects." } }, "additionalProperties": false, @@ -268,19 +317,23 @@ "serviceRef", "budgetingMethod", "objectives" - ] + ], + "description": "SLOSpec defines an SLO's service, SLI, time window, budgeting method, objectives, and alert policies." }, "SLOTimeWindow": { "$anchor": "SLOTimeWindow", "properties": { "duration": { - "$ref": "#/$defs/DurationShorthand" + "$ref": "#/$defs/DurationShorthand", + "description": "Duration is the length of the evaluation window." }, "isRolling": { - "type": "boolean" + "type": "boolean", + "description": "IsRolling selects a rolling window when true and a calendar-aligned window when false." }, "calendar": { - "$ref": "#/$defs/SLOCalendar" + "$ref": "#/$defs/SLOCalendar", + "description": "Calendar defines the alignment of a calendar window." } }, "additionalProperties": false, @@ -288,7 +341,8 @@ "required": [ "duration", "isRolling" - ] + ], + "description": "SLOTimeWindow describes one rolling or calendar-aligned evaluation window." } }, "properties": { @@ -312,5 +366,6 @@ "kind", "metadata", "spec" - ] + ], + "description": "SLO defines a target for an SLI over a time window." } \ No newline at end of file