Skip to content

Commit 27a7b1f

Browse files
jack-bergjack-berg
authored
Move modeling rules to CONTRIBUTING.md (#170)
1 parent c8014d6 commit 27a7b1f

File tree

2 files changed

+220
-218
lines changed

2 files changed

+220
-218
lines changed

‎CONTRIBUTING.md‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,226 @@ Read OpenTelemetry project [contributing
44
guide](https://github.com/open-telemetry/community/blob/main/CONTRIBUTING.md)
55
for general information about the project.
66

7+
## Schema modeling rules
8+
9+
The following rules are enforced when modeling the configuration schema.
10+
11+
These rules must be enforced when making changes to the schema; however, changes to the rules are permitted. In other words, the [stability definition](./README.md#stability-definition) does not apply to the rules: so long as the stability definition is not violated for existing properties, the modeling rules guiding new properties may change.
12+
13+
### Which JSON schema version?
14+
15+
The schema is modeled using JSON schema [draft 2020-12](https://json-schema.org/draft/2020-12).
16+
17+
This is reflected in top level schema documents by setting `"$schema": "https://json-schema.org/draft/2020-12/schema"`.
18+
19+
### What properties are part of schema?
20+
21+
Only properties which are described in [opentelemetry-specification](https://github.com/open-telemetry/opentelemetry-specification) or [semantic-conventions](https://github.com/open-telemetry/semantic-conventions) are modeled in the schema. However, it's acceptable to allow additional properties specific to a particular language or implementation, and not covered by the schema. Model these by setting `"additionalProperties": true` (see [JSON schema additionalProperties](https://json-schema.org/understanding-json-schema/reference/object#additionalproperties)). Types should set `"additionalProperties": false` by default unless requested by an opentelemetry component [maintainer](https://github.com/open-telemetry/community/blob/main/community-membership.md#maintainer) which supports additional options.
22+
23+
### Property naming
24+
25+
To remove redundant information from the configuration file, prefixes for data produced by each of the providers will be removed from configuration options. For example, under the `meter_provider` configuration, metric readers are identified by the word `readers` rather than by `metric_readers`. Similarly, the prefix `span_` will be dropped for tracer provider configuration, and `logrecord` for logger provider.
26+
27+
### Property name case
28+
29+
Properties defined in the schema should be lower [snake case](https://en.wikipedia.org/wiki/Snake_case).
30+
31+
### Properties which pattern matching
32+
33+
When a property requires pattern matching, use wildcard `*` (match any number of any character, including none) and `?` (match any single character) instead of regex. If a single property with wildcards is likely to be insufficient to model the configuration requirements, accept `included` and `excluded` properties, each with an array of strings with wildcard entries. The wildcard entries should be joined with a logical OR. If `included` is not specified, assume that all entries are included. Apply `excluded` after applying `included`. Examples:
34+
35+
* Given `excluded: ["a*"]`: Match all except values starting with `a`.
36+
* Given `included: ["a*", "b*"]`, `excluded: ["ab*"]`: Match any value starting with `a` or `b`, excluding values starting with `ab`.
37+
* Given `included: ["a", "b"]`, `excluded: ["a"]`: Match values equal to `b`.
38+
39+
### Data modeling and environment variable substitution
40+
41+
Properties should be modeled using the most appropriate data structures and types to represent the information. This may result in a schema which doesn't support env var substitution for the [standard env vars](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md) where a type mismatch occurs. For example, the `OTEL_RESOURCE_ATTRIBUTES` env var is modeled as a string, consisting of a comma separated list of key-value pairs, which is not the natural way to model a mapping of key-value pairs in JSON schema.
42+
43+
In instances where there is a type mismatch between the JSON schema and equivalent standard env var, an alternative version of the property may be provided to resolve the mismatch. For example, resource attributes are configured at `.resource.attributes`, but `.resource.attributes_list` is available with a format matching that of `OTEL_RESOURCE_ATTRIBUTES`. Alternative properties are reserved for cases where there is a demonstrated need for platforms to be able to participate in configuration and there is no reasonable alternative.
44+
45+
### Name-value pairs
46+
47+
When a type requires a configurable list of name-value pairs (i.e. resource attributes, HTTP headers), model using an array of objects, each with `name` and `value` properties. While an array of name-value objects is slightly more verbose than an object where each key-value is an entry, the latter is preferred because:
48+
49+
* Avoids user input as keys, which ensures conformity with the [snake_case properties](#property-name-case) rule.
50+
* Allows both the names and the values to be targets for [env var substitution]. For example:
51+
52+
```yaml
53+
tracer_provider:
54+
processors:
55+
- batch:
56+
exporter:
57+
otlp:
58+
headers:
59+
- name: ${AUTHORIZATION_HEADER_NAME:-api-key}
60+
value: ${AUTHORIZATION_HEADER_VALUE}
61+
```
62+
63+
### Required and null properties
64+
65+
JSON schema has two related but subtly different concepts involved in indicating the requirement level of properties and values:
66+
67+
* [`type` of `null`](https://json-schema.org/understanding-json-schema/reference/null): When a property includes a type of `null` along with other allowed types (i.e. `"type": ["string", "null"]`), it indicates that even if the property key is present, the value may be omitted. This is useful in a variety of situations:
68+
* When modeling properties with primitive types which are candidates for [env var substitution][], since allowing `null` means that the configuration is valid even if the referenced env var is undefined.
69+
* When modeling objects which do not require any properties. In these cases, either no properties are required, or there are no properties and the presence of the property key expresses the desired state.
70+
* [required](https://json-schema.org/understanding-json-schema/reference/object#required): When a property is `required`, the key must be included in the object or the configuration is invalid. Properties should be required when there is no well default semantic (i.e. it's not clear what the behavior is when the property is absent).
71+
72+
For example:
73+
74+
```
75+
tracer_provider:
76+
processors:
77+
- simple:
78+
exporter:
79+
console:
80+
limits:
81+
attribute_value_length_limit: ${OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT}
82+
```
83+
84+
* `tracer_provider` is not required. When omitted, a noop tracer provider is used.
85+
* `tracer_provider`'s type is `object`. There's no sensible tracer provider which does not minimally set one entry in `processors`.
86+
* `exporter` is required. A simple processor without an exporter is invalid.
87+
* `exporter`'s type is `object`. Setting `exporter` to `null` or any non-object value is invalid.
88+
* `console`'s type is `["object", "null"]`. The console exporter has no properties, and we should not force the user to set an empty object (i.e `console: {}`).
89+
* `limits` is not required. When omitted, default span limits are used.
90+
* `limits`'s type is `object`. If a user includes the `limits` property, they must set at least one property. Settings `limits` to `null` is invalid.
91+
* `attributes_value_length_limit` is not required. If omitted, no attribute length limits are applied.
92+
* `attributes_value_length_limit`'s type is `["integer", "null]`. If null (i.e. because the `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` env var is unset), no attribute length limits are applied.
93+
94+
If a property is _not_ required, it should include a [comment](./CONTRIBUTING.md#description-generation) describing the semantics when it is omitted.
95+
96+
If a property `type` includes `null`, it must include a [comment](./CONTRIBUTING.md#description-generation) describing the semantics when the value is `null`. It's common for properties with primitive types to allow `null`. `object` types allow `null` if no properties are required and the presence of the property key is meaningful.
97+
98+
### Polymorphic types
99+
100+
JSON schema's [schema composition](https://json-schema.org/understanding-json-schema/reference/combining) keywords (`allOf`, `anyOf`, `oneOf`) offer a tempting mechanism for object-oriented style inheritance and polymorphic patterns. However, JSON schema code generation tools may struggle or not support these keywords. Therefore, these keywords should be used judiciously, and should not be used to extend `object` types.
101+
102+
For example:
103+
104+
```json
105+
{
106+
"Shape": {
107+
"title": "Shape",
108+
"type": "object",
109+
"properties": {
110+
"sides": { "type": "integer"}
111+
}
112+
},
113+
"Square": {
114+
"title": "Square",
115+
"type": "object",
116+
"allOf": [{"$ref": "#/$defs/Shape"}],
117+
"properties": {
118+
"side_length": {"type": "integer"}
119+
}
120+
}
121+
}
122+
```
123+
124+
`allOf` is used in the `Square` type to extend the parent `Shape` type, such that `Square` has properties `sides` and `side_length`. Avoid this type of use.
125+
126+
Another example:
127+
128+
```json
129+
{
130+
"AttributeNameValue": {
131+
"title": "AttributeNameValue",
132+
"type": "object",
133+
"properties": {
134+
"name": {
135+
"type": "string"
136+
},
137+
"value": {
138+
"oneOf": [
139+
{"type": "string"},
140+
{"type": "number"},
141+
{"type": "boolean"},
142+
{"type": "null"},
143+
{"type": "array", "items": {"type": "string"}},
144+
{"type": "array", "items": {"type": "boolean"}},
145+
{"type": "array", "items": {"type": "number"}}
146+
]
147+
},
148+
"type": {
149+
"$ref": "#/$defs/AttributeType"
150+
}
151+
},
152+
"required": [
153+
"name", "value"
154+
]
155+
},
156+
"AttributeType": {
157+
"type": ["string", "null"],
158+
"enum": [
159+
null,
160+
"string",
161+
"bool",
162+
"int",
163+
"double",
164+
"string_array",
165+
"bool_array",
166+
"int_array",
167+
"double_array"
168+
]
169+
}
170+
}
171+
```
172+
173+
`oneOf` is used to specify that the `value` property matches the [standard attribute](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/common#standard-attribute) definition, and is either a primitive or array of primitives. This type of use is acceptable but should be used judiciously.
174+
175+
### Annotations - title and description
176+
177+
The JSON schema [`title` and `description` annotations](https://json-schema.org/understanding-json-schema/reference/annotations) are keywords which are not involved in validation. Instead, they act as a mechanism to help schemas be self-documenting, and may be used by code generation tools.
178+
179+
Despite these potential benefits, these keywords should be omitted:
180+
181+
* The titles of `object` and `enum` types produced by code generation tools should be defined using key values in [$defs](https://json-schema.org/understanding-json-schema/structuring#defs). Setting the `title` keyword introduces multiple sources of truth and possible conflict.
182+
* As described in [description generation](./CONTRIBUTING.md#description-generation), we use a different mechanism to describe the semantics of types and properties. Setting the `description` keyword introduces multiple sources of truth and possible conflict.
183+
184+
## Schemas and subschemas
185+
186+
In JSON Schema, a [schema](https://json-schema.org/learn/glossary#schema) is a document, and a [subschema](https://json-schema.org/learn/glossary#subschema) is contained in surrounding parent schema. Subschemas can be nested in various ways:
187+
188+
A property can directly describe a complex set of requirements including nested structures:
189+
190+
```json
191+
{
192+
"properties": {
193+
"shape": {
194+
"type": "object",
195+
"properties": {
196+
"color": { "type": "string" },
197+
"sides": { "type": "int" }
198+
}
199+
}
200+
}
201+
}
202+
```
203+
204+
Or a property can reference a subschema residing in a schema document's [$defs](https://json-schema.org/understanding-json-schema/structuring#defs):
205+
206+
```json
207+
{
208+
"properties": {
209+
"shape": {
210+
"$ref": "#/$defs/Shape"
211+
}
212+
},
213+
"$defs": {
214+
"Shape": {
215+
"type": "object",
216+
"properties": {
217+
"color": { "type": "string" },
218+
"sides": { "type": "int" }
219+
}
220+
}
221+
}
222+
}
223+
```
224+
225+
In order to promote stylistic consistency and allow for reuse of concepts, `object` and `enum` types should be defined in either as a top level schema document or as a subschema in a schema document's `$defs`.
226+
7227
## Consistency Checks
8228

9229
This repository has various checks to ensure the schema changes are valid. Before using:

0 commit comments

Comments
 (0)