Provide Guidance and Examples for Edge Cases in Complex Subject Matching

[vatsalgupta]

Section 8.1.3.1 (Subject Matching) defines rules for matching Complex Subjects, stating that two subjects match if all fields are undefined or identical. However, it lacks guidance on edge cases, such as nested Complex Subjects or fields with multiple values (e.g., ip-addresses).
This could lead to inconsistent matching logic.

Nested Complex Subjects

Subject 1:
{
"format": "complex",
"tenant": {
"format": "opaque",
"id": "example-a38h4792-uw2"
},
"user": {
"format": "complex",
"email": {
"format": "email",
"email": "jdoe@example.com"
}
}
}

Subject 2:
{
"format": "complex",
"tenant": {
"format": "opaque",
"id": "example-a38h4792-uw2"
},
"user": {
"format": "complex",
"email": {
"format": "email",
"email": "jdoe@example.com"
},
"role": {
"format": "opaque",
"id": "admin"
}
}
}

IP Address:

Subject 1:
{
"format": "complex",
"device": {
"format": "ip-addresses",
"ip-addresses": ["10.29.37.75", "10.29.37.76"]
}
}

Subject 2:
{
"format": "complex",
"device": {
"format": "ip-addresses",
"ip-addresses": ["10.29.37.75"]
}
}

[FragLegs]

Complex Subjects cannot have nested Complex Subjects, so your first example is not a concern. But I agree that we should say something about subjects that have lists in their fields (ip-addresses and aliases).

The spec currently claims that the fields must be identical to match, so your IP Address example above would be considered not matching. Including an example for both ip-addresses and aliases to clarify the behavior seems prudent.

[FragLegs]

Shoot. I started adding examples for this and realized that we should probably treat array values as an ANY match (i.e. if the event's value matches any of the values in the array that the Receiver added, the event should be sent).

Here is an example:

The Receiver has added the following subject to their stream:

{
  "format": "complex",
  "user": {
    "format": "aliases",
    "identifiers": [
      {
        "format": "email",
        "email": "jdoe@example.com"
      },
      {
        "format": "email",
        "email": "john.doe@example.com"
      },
      {
        "format": "phone_number",
        "phone_number": "+12065550100"
      }
    ]
  }
}

The Transmitter has an event to broadcast with the following subject:

{
  "format": "complex",
  "user": {
    "format": "aliases",
    "identifiers": [
      {
        "format": "email",
        "email": "jdoe@example.com"
      },
      {
        "format": "phone_number",
        "phone_number": "+12065550100"
      }
    ]
  }
}

According to the matching rules currently described in the spec, the Transmitter SHOULD NOT broadcast the event over the Receiver's stream because the two aliases identifiers are not an exact match. But looking at this example, we would probably want to consider this a match. We would probably also want to consider the following a match

{
  "format": "complex",
  "user": {
      "format": "email",
      "email": "jdoe@example.com"
   }
}

Doing this would be a major normative change, so I think we should wait until v2.