Skip to main content
Schemas are the source of truth for your service’s configuration options. They define available options, their types, default values, and descriptions.

​
Schema structure

Every schema must be a valid JSON file located at sentry-options/schemas/{namespace}/schema.json.

​
Required fields

schema.json
{
  "version": "1.0",
  "type": "object",
  "properties": {
    // Your option definitions here
  }
}
FieldRequiredDescription
versionYesSemver string (e.g., "1.0")
typeYesMust be "object"
propertiesYesMap of option definitions

​
Property fields

Each property in properties defines a single option: 
"option-name": {
  "type": "string",
  "default": "hello",
  "description": "A friendly greeting message"
}
FieldRequiredDescription
typeYesOne of: string, integer, number, boolean, array
defaultYesDefault value (must match declared type)
descriptionYesHuman-readable description
itemsFor arraysObject specifying array element type

​
Supported types

​
Primitive types

"system.url-prefix": {
  "type": "string",
  "default": "https://sentry.io",
  "description": "Base URL for the Sentry instance"
}

​
Array types

Arrays require an items field specifying the element type: 
"feature.enabled_slugs": {
  "type": "array",
  "items": {"type": "string"},
  "default": ["getsentry"],
  "description": "Which orgs to enable the feature for"
}
Supported array element types: string, integer, number, boolean. Nested arrays and objects are not yet supported.

​
Type validation

The system enforces strict type validation:

​
Number handling

  • Schema says integer → Rejects 5.5, accepts 5
  • Schema says number → Accepts both 5 and 5.5

​
Strict validation rules

The following will cause validation errors:
  • Unknown keys in values files (catches typos)
  • Type mismatches between schema and values
  • null values (use defaults instead)
Example error scenarios:
values.yaml (❌ Will fail)
options:
  # Unknown option (typo)
  feature.enbaled: true  # Should be "enabled"
  
  # Type mismatch
  feature.rate_limit: "100"  # Schema expects integer, got string
  
  # Null value
  feature.enabled: null  # Use schema default instead

​
Complete example

Here’s a real-world schema from the test suite:
sentry-options/schemas/sentry-options-testing/schema.json
{
  "version": "0.1",
  "type": "object",
  "properties": {
    "example-option": {
      "type": "string",
      "default": "",
      "description": "An example string option"
    },
    "float-option": {
      "type": "number",
      "default": 0.0,
      "description": "An example float option"
    },
    "int-option": {
      "type": "integer",
      "default": 0,
      "description": "An example integer option"
    },
    "bool-option": {
      "type": "boolean",
      "default": false,
      "description": "An example boolean option"
    },
    "string-option": {
      "type": "string",
      "default": "default",
      "description": "An example string option with a default value"
    },
    "demo-option": {
      "type": "string",
      "default": "hello everyone",
      "description": "A string option to demo to dev-infra"
    }
  }
}

​
Schema evolution rules

CI automatically enforces these rules when you modify schemas:
ChangeAllowedRationale
Add new options✅Backward compatible (clients use defaults)
Add new namespaces✅Backward compatible (isolated)
Remove options❌Breaking change (services may depend on it)
Remove namespaces❌Breaking change (services may depend on it)
Change option types❌Breaking change (client code expects specific type)
Change default values❌Behavior change (could break existing logic)
The validate-schema GitHub Action will fail PRs that violate these rules. If you need to make a breaking change, contact DevInfra for migration strategy.

​
Removing options safely

When you need to remove an option:
  1. Remove all code using the option from your service
  2. Remove the option from values files in sentry-options-automator
  3. Create a PR to remove the option from your schema
  4. The CI will verify the option is not used anywhere

​
Changing defaults

To change a default value:
  1. Add the desired value to all targets in sentry-options-automator
  2. Deploy the ConfigMaps
  3. Now all instances use the new value (overriding the old default)
  4. The schema default becomes irrelevant

​
Additional properties

The system automatically injects "additionalProperties": false to reject unknown options in values files. This helps catch typos early.

​
Namespace naming

Namespace directories must follow the naming convention {repo} or {repo}-*.
For example, in the seer repository: ✅ Valid namespaces:
  • seer
  • seer-autofix
  • seer-grouping
❌ Invalid namespaces:
  • autofix (missing repo prefix)
  • getsentry-seer (wrong repo prefix)

​
Next steps

Use in code

Learn how to read options in Python and Rust

Test locally

Override values during development

Build docs developers (and LLMs) love

Get started for freeTalk to us