List properties used to evaluate single/all flags

[oxddr]

Add API method that returns properties (property = field in the evaluation context) used to evaluate single/all flags. The OFREP client then can only calculate and send properties, which are used by given flags.

Some properties are expensive to calculate (e.g. they require separate, expensive RPC) and we'd like to avoid calculating them if possible. With the protocol in the current shape, it's not possible.

[thomaspoignant]

Hey @oxddr just to be sure that I am understanding correctly, what do you call properties?
Are you talking about the fields in the evaluation context?

[oxddr]

That's correct - property = field in the evaluation context. I've updated the top-level description.

[thomaspoignant]

If I understand correctly, you would like a way to know which fields of the evaluation context each flag is using?
Something like :

- flag1: name, targetingKey, company
- flag2: age, targetingKey
- flag3: city, country
- ...

This is an interesting use case, I don't know if any vendors are doing this.
@beeme1mr @toddbaert have you heard about something like this?

[thomaspoignant]

@oxddr do you expect some validation in the provider based on that? Just trying to understand what would be the scope of this feature if we decide to implement it.

[beeme1mr]

Hey @oxddr, could you please elaborate on how this would work? How would this information be returned to the service so that it could be used to avoid expensive async calls? How would changes to the flag definition (e.g. a new property is added to a rule) be communicated to the provider?

Vendors would have access to this information in the ruleset, but I haven't seen many expose it. I've thought about using this information for reporting purposes in the past. It's an interesting use case that we'll have to consider the end-to-end ramifications.

[grimly]

This looks like a key metadata endpoint.

To that effect, I would propose an extension specification that extends the configuration response with a keyMetadataEndpoint property.
Its value, if present, must be a URI.
Its resolution should grant all key metadata. I propose this kind of format :

---
keys:
  my-flag-a:
    dependencies:
      # List of Json Pointers (RFC 6901) this flag depends on
      # If between a change in your context, the value of one of these pointers is not equal to its previous value, then the key is invalid
      # Equality would be described the same as JSONPatch "test" operation ( https://datatracker.ietf.org/doc/html/rfc6902#section-4.6 ) or JSON Schema instance equality ( https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-01#name-instance-equality )
      - /email
      - /language
    schema: # As a bonus, you could verify the flag has the type you expect
      type: boolean
  I.love.dotted.flag.names:
    dependencies: [] # Flags could just be set without dependency by the service
    schema:
      type: string
  and/slashed/ones:
    # a missing dependencies key could mean it depends on everything. Or maybe it's not obvious and we should rather remove it
    schema:
      type: integer
      format: int32
  "and also spaces because the spec do not forbid them":
    description: |
      Keys could have descriptions attached for documentation. That's out of the scope of your request but I'd like that :)
    dependencies:
      - / # You could depend on just everything by pointing to the root
    schema: # As a bonus, you could verify the flag has the type you expect
      type: boolean

Some notes on my format proposal:

• This is YAML because I'm lazy.
• I'm bad at naming things
• I though of using a /context prefix to account for the possibility of taking into account other request parameters such as a claim from a JWT in the Authorization header.

[thomaspoignant]

My main question with such endpoint will be, what will we do in the providers with it?

[grimly]

My main question with such endpoint will be, what will we do in the providers with it?

1. You could just not consider it. I propose an extension after all. Support is at discretion of both provider and service.
2. Looking at the dependencies, you can maintain a cache and invalidate this cache when you detect the context changed.
3. Looking at the schema, you can generate code for an adapter that offer the flags with immediate knowledge of their key and type (provided it is static enough)
4. You can use a web UI to provide documentation on the flags

[thomaspoignant]

I like all of those ideas but I am not sure this should be part of OFREP, it may be another API definition than this one.

[beeme1mr]

Something like this would be extremely useful and powerful. It could also potentially be used in integrations like the Vercel toolbar. However, I think that it's out of scope for the initial implementation of OFREP and that we'll need to define a strategy for supporting optional "extension".

In the meantime, @grimly, would you be willing to put together a prototype? That would help showcase the value and implementation effort and perhaps highlight where this could fit into the rest of OFREP.

[grimly]

However, I think that it's out of scope for the initial implementation of OFREP

I know, that's why I call it an extension. Also it's one of the first thing you can read on this repo :

Non-Goals

• defining a schema for the definition or storage of feature flags

Please understand I was trying to find a solution to @oxddr 's issue and I hope my proposal is a good fit.

---

In the meantime, @grimly, would you be willing to put together a prototype?

I have no time for it. It would not serve my current concerns. But here are my thoughts

Server side

The effort required on server side depends only on the vendor's offer.

Dependencies

To fill in the dependencies, you must identify the fields your evaluator may access.
If you have dynamic property access, this can become a really hard problem.

Schema

To fill in the schema, you can :

• Have a limited set of types and therefore have pre-evaluated schemas
• Use the true schema for unrestricted values. The SDK would then provide for unstructured types such as Typescript's unknown, Java+Jackson's JsonNode, Go's any...
• Aim at a developer user base that would themselves provide the schemas

There is no one-size fits all here

Documentation

This is just like Swagger UI (hard if you want to show all details of a schema)

Consumer side

Context re-evaluation (dependencies)

This is really easy on consumer side.
Cache a flag value with aside an array of all its dependencies evaluated from the context.
On next request, if the new array of its dependencies is different from the cached version, then the cache must be invalidated and the flag re-evaluated.

Code generators

There are code generators based on JSON Schema here and there so depending on the language's ecosystem, the task could be either a breeze or a pain in the a**

[Kavindu-Dodan]

Is this something that we can achieve by utilizing already defined metadata section ¹ of a successful flag evaluation ?

For example,

{
  "value": true,
  "key": "my-flag",
  "reason": "STATIC",
  "variant": "string",
  "metadata": {
    "evaluationDecisionBasedOnCtx": [
       "email",
       "country",
       ....
    ],
  }
}

Footnotes

1. https://github.com/open-feature/protocol/blob/main/service/openapi.yaml#L218-L225 ↩

[oxddr]

I apologize for not responding yet to questions and comments. I am going to get back to you in few days.

[oxddr]

I apologize for not responding earlier - I am currently on the longer leave. Kamil from my team is going to take over discussion from our end.