Explore machine reachable approach to event definitions

[timcappalli]

We've long discussed the challenges with the event specs, which are effectively just dictionaries, being formal specifications that go through full OIDF process. This can make it challenging to add new events quickly which can make the effort feel less accessible.

This issue is to track and explore a more machine readable approach to defining events, such as using a JSON schema file mainted on GitHub with version controls.

Some early thoughts:

• There would no longer be a single document
• Events would be versioned instead of the document (likely using a path in the event URI)
• The event URI would be dereferencable to the JSON schema (or other file)

[timcappalli]

Here's an example of the CAEP Session Revoked event, defined in JSON Schema. This only includes the properties of the event object (e.g. "https://schemas.openid.net/secevent/caep/event-type/session-revoked/": { < this > }.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schemas.openid.net/secevent/caep/event-type/session-revoked/v1.schema.json",
  "title": "Session Revoked",
  "description": "Session Revoked signals that the session identified by the subject has been revoked. The explicit session identifier may be directly referenced in the subject or other properties of the session may be included to allow the receiver to identify applicable sessions.",
  "type": "object",
  "properties": {
    "initiating_entity": {
      "description": "Describes the entity that invoked the event.",
      "type": "string",
      "oneOf": [
        {
          "const": "admin",
          "description": "an administrative action triggered the event"
        },
        {
          "const": "user",
          "description": "an end-user action triggered the event"
        },
        {
          "const": "policy",
          "description": "a policy evaluation triggered the event"
        },
        {
          "const": "system",
          "description": "a system or platform assertion triggered the event"
        }
      ]
    },
    "reason_admin": {
      "description": "a localizable administrative message intended for logging and auditing. The object MUST contain one or more key/value pairs, with a BCP47 [RFC5646] language tag as the key and the locale-specific administrative message as the value.",
      "type": "object"
    },
    "reason_user": {
      "description": "a localizable user-friendly message for display to an end-user. The object MUST contain one or more key/value pairs, with a BCP47 [RFC5646] language tag as the key and the locale-specific end-user message as the value.",
      "type": "object"
    },
    "event_timestamp": {
      "description": "the time at which the event described by this SET occurred. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. This value MUST represent the time at which the session revocation occurred",
      "type": "number"
    }
  }
}

I think this could work. One question is whether the schema should contain the entire SET (including sub_id) or just the event payload. Thoughts @openid/wg-sharedsignals-editors?

[FragLegs]

I feel strongly that we should not include the entire SET in the definition. Just the event itself. Since the events claim of the SET is a dictionary mapping these URNs to objects, it will be easier to model if we have schemas for each individual object. Also, if the schema included the full SET, then any changes to the SET structure (like the proposed inclusion of txn) would force us to update all of the event schemas.

[tulshi]

A few comments / observations:

1. If it's not a single document, how will all such documents be organized?
2. The initial issue talks about event versioning, but the detailed description does not indicate how the versioning will be captured.
3. How do you describe the optionality of specific fields in the current proposal?
4. We need to be able to give non-normative examples of such events. We need to think of how to specify that in this format
5. We need semantics around normative and non-normative language in the description of the fields.
6. What is the OpenID Foundation process that we are proposing for using this format? How does someone propose it, how does the WG discuss / work on it, when is OIDF required to review it (like in the case of implementer's draft)?

[timcappalli]

From 2024-05-28 in person discussion:

• Sentiment is generally positive for this
• @timcappalli to add a RISC example to this issue
• Need to define a new spec (ex: "Shared Signals Event Definition Specification") that explains the schema, process, etc (this spec would replace RISC and CAEP documents)
• Need to check OIDF policy document on whether the schema files are normative or non-normative in the context of IPR as those checks are done during spec process (ID, etc)

[tulshi]

Notes from the call on 11/19:

• Jen reviewed the current proposal
• Mike Jones had some concerns about how this would work?
  • He thought a JSON schema won't be sufficient, and a spec would be required
  • (Jen) So does the WG think that just the schema is sufficient or we need a spec.
  • (Atul) What's an example of the insufficiency?
  • (Jen) Using the schema description of a field is not sufficient to describe the semantics of the field
  • (Jen) Not managing the spec lifecycle is one of the main benefits of the JSON schema approach, so if we need a schema, we will negate that benefit.
• (Yair) do we need to specify the same common field across different schemas, or do we need to specify them in a common file?
  • (Jen) The schemas could have inheritance, but we could duplicate if required
  • (Yair) But if you duplicate, then it will get complicated
  • (Yair) We should think about the end-to-end process. If we had a schema, how would we use it, and then work backwards from there?
  • (Jen) A good exercise would be to go through a few events and see where this proposal falls short. (e.g. one RISC event, one SCIM event, etc.)
  • (Atul) Once you do that, we could divide up the rest of the events among all of us, and go through the same exercise