Skip to content

feat: add support for typesafe object flags #248

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
beeme1mr wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

feat: add support for typesafe object flags #248

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 26 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -294,24 +294,45 @@ The flag manifest file should follow the [JSON schema](https://raw.githubusercon
- `flags` - An object containing the feature flags
- `flagKey` - A unique key for the flag
- `description` - A description of what the flag does
- `type` - The type of the flag (`boolean`, `string`, `number`, `object`)
- `flagType` - The type of the flag (`boolean`, `string`, `integer`, `float`, `object`)
- `defaultValue` - The default value of the flag
- `schema` - *(Optional, object flags only)* A [JSON Schema subset](./docs/object-flag-schemas.md) describing the object shape for type-safe code generation

### Example Flag Manifest

```json
{
"$schema": "https://raw.githubusercontent.com/open-feature/cli/refs/heads/main/schema/v0/flag-manifest.json",
"flags": {
"uniqueFlagKey": {
"description": "Description of what this flag does",
"type": "boolean|string|number|object",
"defaultValue": "default-value",
"enableFeatureA": {
"flagType": "boolean",
"defaultValue": false,
"description": "Controls whether Feature A is enabled."
},
"themeCustomization": {
"flagType": "object",
"defaultValue": {
"primaryColor": "#007bff",
"secondaryColor": "#6c757d"
},
"description": "Allows customization of theme colors.",
"schema": {
"type": "object",
"properties": {
"primaryColor": { "type": "string" },
"secondaryColor": { "type": "string" }
},
"required": ["primaryColor"]
}
}
}
}
```

> **_NOTE:_**
> The `schema` field is optional. Object flags without a `schema` continue to generate generic types.
> See the [Object Flag Schemas](./docs/object-flag-schemas.md) documentation for details on supported JSON Schema keywords, runtime validation hooks, per-language behavior, and limitations.

## Remote Flag Management

The OpenFeature CLI supports synchronizing flags with remote flag management services through a standardized OpenAPI-based approach. This enables teams to:
Expand Down
53 changes: 46 additions & 7 deletions docs/custom-templates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,16 +48,26 @@ type TemplateData struct {
Flags []Flag
}
Params struct {
OutputPath string
Custom any // Language-specific parameters
OutputPath string
RuntimeValidation bool // Whether to generate runtime validation hooks (--runtime-validation flag)
Custom any // Language-specific parameters
}
}

type Flag struct {
Key string // The flag key (e.g., "enable-feature")
Type FlagType // The flag type (boolean, string, integer, float, object)
Description string // Optional description of the flag
DefaultValue any // The default value for the flag
Key string // The flag key (e.g., "enable-feature")
Type FlagType // The flag type (boolean, string, integer, float, object)
Description string // Optional description of the flag
DefaultValue any // The default value for the flag
Schema *ObjectSchema // Optional JSON Schema subset for object flags (nil if not provided)
}

type ObjectSchema struct {
Type string // JSON Schema type: "object", "array", "string", "number", "integer", "boolean"
Properties map[string]*ObjectSchema // Object properties (only for type "object")
Required []string // Required property names (only for type "object")
Items *ObjectSchema // Array element schema (only for type "array")
AdditionalProperties *bool // Whether extra properties are allowed (only for type "object")
}
```

Expand Down Expand Up @@ -94,6 +104,15 @@ These functions are available in all templates:
| `Quote` | Add double quotes | `{{ .Key \| Quote }}` → `"enable-feature"` |
| `QuoteString` | Quote if string type | `{{ .DefaultValue \| QuoteString }}` |

### Schema-Related Functions (Available in All Templates)

These functions are available in all language templates for working with [object flag schemas](./object-flag-schemas.md):

| Function | Description |
|----------|-------------|
| `HasSchema` | Returns `true` if a flag has an object schema defined. Usage: `{{ if HasSchema . }}` |
| `HasObjectFlagsWithSchema` | Returns `true` if any flag in the list has a schema. Usage: `{{ if HasObjectFlagsWithSchema .Flagset.Flags }}` |

### Go-Specific Functions

| Function | Description |
Expand All @@ -102,13 +121,21 @@ These functions are available in all templates:
| `TypeString` | Convert flag type to Go type (`bool`, `string`, `int64`, `float64`, `map[string]any`) |
| `SupportImports` | Generate required imports based on flags |
| `ToMapLiteral` | Convert object value to Go map literal |
| `GoTypeDef` | Generate a Go struct type definition from a flag's object schema |
| `GoHookDef` | Generate a Go validation hook struct with `After` method for a flag's object schema |
| `GoFlagReturnType` | Return the Go type for a flag (typed struct name if schema exists, generic type otherwise) |
| `GoHookName` | Return the hook variable name for a typed object flag |

### React/Node.js/NestJS-Specific Functions
### React/Node.js/Angular/NestJS-Specific Functions

| Function | Description |
|----------|-------------|
| `OpenFeatureType` | Convert flag type to TypeScript type (`boolean`, `string`, `number`, `object`) |
| `ToJSONString` | Convert value to JSON string |
| `TSInterfaceDef` | Generate a TypeScript interface definition from a flag's object schema |
| `TSValidationHookDef` | Generate a TypeScript validation hook function for a flag's object schema |
| `TSFlagReturnType` | Return the TypeScript type for a flag (interface name if schema exists, generic type otherwise) |
| `TSValidationHookName` | Return the hook function name for a typed object flag |

### Python-Specific Functions

Expand All @@ -121,6 +148,10 @@ These functions are available in all templates:
| `TypedDetailsMethodAsync` | Get async details method name |
| `PythonBoolLiteral` | Convert boolean to Python literal (`True`/`False`) |
| `ToPythonDict` | Convert object value to Python dict literal |
| `PythonTypedDictDef` | Generate Python TypedDict class definitions from a flag's object schema |
| `PythonHookDef` | Generate a Python Hook class for runtime validation of a flag's object schema |
| `PythonFlagReturnType` | Return the Python type for a flag (TypedDict name if schema exists, generic type otherwise) |
| `PythonHookName` | Return the hook class name for a typed object flag |

### C#-Specific Functions

Expand All @@ -129,6 +160,10 @@ These functions are available in all templates:
| `OpenFeatureType` | Convert flag type to C# type (`bool`, `string`, `int`, `double`, `object`) |
| `FormatDefaultValue` | Format default value for C# |
| `ToCSharpDict` | Convert object value to C# dictionary literal |
| `CSharpRecordDef` | Generate C# record definitions from a flag's object schema |
| `CSharpHookDef` | Generate a C# Hook class for runtime validation of a flag's object schema |
| `CSharpFlagReturnType` | Return the C# type for a flag (record name if schema exists, generic type otherwise) |
| `CSharpHookName` | Return the hook class name for a typed object flag |

### Java-Specific Functions

Expand All @@ -137,6 +172,10 @@ These functions are available in all templates:
| `OpenFeatureType` | Convert flag type to Java type (`Boolean`, `String`, `Integer`, `Double`, `Object`) |
| `FormatDefaultValue` | Format default value for Java |
| `ToMapLiteral` | Convert object value to Java Map literal |
| `JavaRecordDef` | Generate Java record definitions from a flag's object schema |
| `JavaHookDef` | Generate a Java Hook class for runtime validation of a flag's object schema |
| `JavaFlagReturnType` | Return the Java type for a flag (record name if schema exists, generic type otherwise) |
| `JavaHookName` | Return the hook class name for a typed object flag |

## Example: Simple Go Template

Expand Down
Loading
Loading