Add missing brief on ios.state attribute and add policies to require briefs (#2506)

Author: lmolkova

docs/registry/attributes/android.md

@@ -33,7 +33,7 @@ This document defines attributes that represents an occurrence of a lifecycle tr
 
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
-| <a id="android-state" href="#android-state">`android.state`</a> | string | Deprecated. Use `android.app.state` body field instead. | `created`; `background`; `foreground` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Use `android.app.state` body field instead. |
+| <a id="android-state" href="#android-state">`android.state`</a> | string | Deprecated. Use `android.app.state` attribute instead. | `created`; `background`; `foreground` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Use `android.app.state` attribute instead. |
 
 ---
 

docs/registry/attributes/ios.md

@@ -34,7 +34,7 @@ The iOS platform on which the iOS application is running.
 
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
-| <a id="ios-state" href="#ios-state">`ios.state`</a> | string |  [2] | `active`; `inactive`; `background` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by the `ios.app.state` event body field. |
+| <a id="ios-state" href="#ios-state">`ios.state`</a> | string | Deprecated. Use the `ios.app.state` attribute. [2] | `active`; `inactive`; `background` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by the `ios.app.state` attribute. |
 
 **[2] `ios.state`:** The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate), and from which the `OS terminology` column values are derived.
 

docs/system/system-metrics.md

@@ -352,7 +352,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `system.memory.utilization` | Gauge | `1` |  | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
+| `system.memory.utilization` | Gauge | `1` | TODO. | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -427,7 +427,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `system.paging.utilization` | Gauge | `1` |  | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
+| `system.paging.utilization` | Gauge | `1` | TODO. | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -461,7 +461,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `system.paging.faults` | Counter | `{fault}` |  | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
+| `system.paging.faults` | Counter | `{fault}` | TODO. | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -494,7 +494,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `system.paging.operations` | Counter | `{operation}` |  | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
+| `system.paging.operations` | Counter | `{operation}` | TODO. | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -541,7 +541,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `system.disk.io` | Counter | `By` |  | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
+| `system.disk.io` | Counter | `By` | TODO. | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -575,7 +575,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `system.disk.operations` | Counter | `{operation}` |  | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
+| `system.disk.operations` | Counter | `{operation}` | TODO. | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -679,7 +679,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `system.disk.merged` | Counter | `{operation}` |  | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
+| `system.disk.merged` | Counter | `{operation}` | TODO. | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -795,7 +795,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `system.filesystem.utilization` | Gauge | `1` |  | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
+| `system.filesystem.utilization` | Gauge | `1` | TODO. | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -930,7 +930,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `system.network.packets` | Counter | `{packet}` |  | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
+| `system.network.packets` | Counter | `{packet}` | TODO. | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -1004,7 +1004,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `system.network.io` | Counter | `By` |  | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
+| `system.network.io` | Counter | `By` | TODO. | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|
@@ -1038,7 +1038,7 @@ This metric is [recommended][MetricRecommended].
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability | Entity Associations |
 | -------- | --------------- | ----------- | -------------- | --------- | ------ |
-| `system.network.connection.count` | UpDownCounter | `{connection}` |  | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
+| `system.network.connection.count` | UpDownCounter | `{connection}` | TODO. | ![Development](https://img.shields.io/badge/-development-blue) | [`host`](/docs/registry/entities/host.md#host) |
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|

model/android/deprecated/registry-deprecated.yaml

@@ -7,10 +7,10 @@ groups:
     attributes:
       - id: android.state
         stability: development
-        brief: Deprecated. Use `android.app.state` body field instead.
+        brief: Deprecated. Use `android.app.state` attribute instead.
         deprecated:
           reason: uncategorized
-          note: Use `android.app.state` body field instead.
+          note: Use `android.app.state` attribute instead.
         type:
           members:
             - id: created

model/ios/deprecated/registry-deprecated.yaml

@@ -7,10 +7,12 @@ groups:
     attributes:
       - id: ios.state
         stability: development
+        brief: >
+          Deprecated. Use the `ios.app.state` attribute.
         deprecated:
           reason: uncategorized
           note:
-            Replaced by the `ios.app.state` event body field.
+            Replaced by the `ios.app.state` attribute.
         note: >
           The iOS lifecycle states are defined in the [UIApplicationDelegate documentation](https://developer.apple.com/documentation/uikit/uiapplicationdelegate),
           and from which the `OS terminology` column values are derived.

model/system/metrics.yaml

@@ -149,7 +149,7 @@ groups:
       code_generation:
         metric_value_type: double
     stability: development
-    brief: ""
+    brief: TODO.
     instrument: gauge
     unit: "1"
     attributes:
@@ -183,7 +183,7 @@ groups:
       code_generation:
         metric_value_type: double
     stability: development
-    brief: ""
+    brief: TODO.
     instrument: gauge
     unit: "1"
     attributes:
@@ -201,7 +201,7 @@ groups:
       code_generation:
         metric_value_type: int
     stability: development
-    brief: ""
+    brief: TODO.
     instrument: counter
     unit: "{fault}"
     attributes:
@@ -216,7 +216,7 @@ groups:
     annotations:
       code_generation:
         metric_value_type: int
-    brief: ""
+    brief: TODO.
     instrument: counter
     unit: "{operation}"
     attributes:
@@ -233,7 +233,7 @@ groups:
       code_generation:
         metric_value_type: int
     stability: development
-    brief: ""
+    brief: TODO.
     instrument: counter
     unit: "By"
     attributes:
@@ -249,7 +249,7 @@ groups:
       code_generation:
         metric_value_type: int
     stability: development
-    brief: ""
+    brief: TODO.
     instrument: counter
     unit: "{operation}"
     attributes:
@@ -308,7 +308,7 @@ groups:
       code_generation:
         metric_value_type: int
     stability: development
-    brief: ""
+    brief: TODO.
     instrument: counter
     unit: "{operation}"
     attributes:
@@ -364,7 +364,7 @@ groups:
       code_generation:
         metric_value_type: double
     stability: development
-    brief: ""
+    brief: TODO.
     instrument: gauge
     unit: "1"
     attributes:
@@ -428,7 +428,7 @@ groups:
       code_generation:
         metric_value_type: int
     stability: development
-    brief: ""
+    brief: TODO.
     instrument: counter
     unit: "{packet}"
     attributes:
@@ -466,7 +466,7 @@ groups:
       code_generation:
         metric_value_type: int
     stability: development
-    brief: ""
+    brief: TODO.
     instrument: counter
     unit: "By"
     attributes:
@@ -482,7 +482,7 @@ groups:
       code_generation:
         metric_value_type: int
     stability: development
-    brief: ""
+    brief: TODO.
     instrument: updowncounter
     unit: "{connection}"
     attributes:

policies/yaml_schema.rego

@@ -168,6 +168,24 @@ deny contains yaml_schema_violation(description, group.id, "") if {
     description := sprintf("Group id '%s' is invalid. Span group 'id' must follow 'span.*.%s' pattern", [group.id, kind])
 }
 
+# brief is required on attributes
+deny contains yaml_schema_violation(description, group.id, attr.id) if {
+    group := input.groups[_]
+    attr := group.attributes[_]
+    property_or_null(attr, "brief") == null
+
+    description := sprintf("Attribute id '%s' in group '%s' is invalid. Attributes must have a brief.", [attr.id, group.id])
+}
+
+# brief is required on groups (except attribute groups)
+deny contains yaml_schema_violation(description, group.id, "") if {
+    group := input.groups[_]
+    group.type != "attribute_group"
+    property_or_null(group, "brief") == null
+
+    description := sprintf("Group id '%s' is invalid. Groups must have a brief.", [group.id])
+}
+
 yaml_schema_violation(description, group, attr) = violation if {
     violation := {
         "id": description,
@@ -185,3 +203,8 @@ name_regex := "^[a-z][a-z0-9]*([._][a-z0-9]+)*$"
 has_namespace_regex := "^[a-z0-9_]+\\.([a-z0-9._]+)+$"
 
 invalid_name_helper := "must consist of lowercase alphanumeric characters separated by '_' and '.'"
+
+property_or_null(obj, property) := obj[property] if {
+    obj[property]
+    obj[property] != ""
+} else := null

policies_test/metric_brief_format_test.rego

@@ -26,25 +26,6 @@ test_metric_brief_without_period if {
     ]}
 }
 
-test_metric_without_brief if {
-    # Should pass: metric without brief is ignored (handled by other policies)
-    count(before_resolution.deny) == 0 with input as {"groups": [
-        {"id": "metric.test", "type": "metric", "stability": "development"}
-    ]}
-}
-
-test_metric_with_empty_brief if {
-    # Should pass: metric with empty brief is allowed
-    count(before_resolution.deny) == 0 with input as {"groups": [
-        {"id": "metric.test", "type": "metric", "brief": "", "stability": "development"}
-    ]}
-
-    # Should pass: metric with whitespace-only brief is treated as empty and allowed
-    count(before_resolution.deny) == 0 with input as {"groups": [
-        {"id": "metric.test2", "type": "metric", "brief": "   ", "stability": "development"}
-    ]}
-}
-
 test_non_metric_groups_ignored if {
     # Should pass: non-metric groups are ignored
     count(before_resolution.deny) == 0 with input as {"groups": [