Suggest renaming `trust_mark_id` to better reflect its meaning

[jcmelati]

While reviewing the Trust Mark section of the spec, I’d like to suggest clarifying the naming of the trust_mark_id field.

Currently, trust_mark_id refers to the identifier of the class or definition of a Trust Mark.

However, the _id suffix commonly implies an instance identifier, which in this case can lead to confusion. For example, it’s easy to misinterpret trust_mark_id as referring to a specific, issued trust mark (the JWT), rather than the type or class it belongs to.

In a past discussion with @peppelinux, the idea came up that this value is closer to a "Trust Mark Type" identifier. Therefore, naming it trust_mark_type_id (or trust_mark_definition_id, or simply trust_mark_type) might better reflect its role as a reference to the Trust Mark's category, and not to an issued Trust Mark instance.

@peppelinux acknowledged this as a semantic point and mentioned that trust_mark_type_id could be a better fitting name.

Proposed change: Rename trust_mark_id to something more precise, such as:

• trust_mark_type_id
• trust_mark_definition_id
• or even trust_mark_type

This would more clearly signal that the field is identifying a class of trust mark (not an issued instance), improving developer understanding without affecting semantics.

Making this change would not only improve clarity, but also lay the groundwork for potential features like a Trust Mark definition repository, where each trust_mark_type_id could be enriched with metadata, documentation, or validation rules.

[selfissued]

At this point, there's a high bar for making breaking changes, as we're nearly final.

Perhaps we can discuss this next week at the Federation Interop event in Stockholm.

[jcmelati]

Hi @selfissued, thanks for the reply.

I understand we want to avoid significant changes as we approach a final first version, but I sincerely believe making this adjustment before the final release is very important from a data modeling perspective.

As an implementer issuing Trust Marks and assigning unique IDs to each issued Trust Mark, I’ve found it confusing and quite counterintuitive that we currently use the field name trust_mark_id for something entirely different from its common meaning. The current attribute naming steepens the spec learning curve without clear benefit, because the convention used in the OpenID Federation specification diverges from widely adopted data modeling practices.

I’m concerned that this naming choice is likely to lead to misunderstandings among implementers and users as the ecosystem grows. I believe that taking the opportunity to clarify this now, before releasing the final version, would help us avoid considerable friction in the future.

Looking forward to your thoughts, and happy to discuss this further in Stockholm!

[selfissued]

We discussed this on the 24-Apr-25 working group call. This is actually more of a class identifier or type identifier than an ID for an individual issued trust mark instance.

[selfissued]

Per in-person discussions at the Federation Interop including @rohe, @peppelinux, and @jcmelati, there was agreement that the current name trust_mark_id is a source of confusion, because we typically use names with ID for instance identifiers. For instance, JWT ID (jti) and Entity Identifier.

There seemed to be consensus to rename it to trust_mark_kind, with careful attention to the accompanying wording.

[selfissued]

Also, this language in Trust Mark Claims is fairly circular. It says that the id is an identifier.

trust_mark_id
REQUIRED. The trust_mark_id (identifier) claim defined in Section 7.1 is used in Trust Marks to provide the identifier of the Trust Mark.

[selfissued]

Or maybe trust_mark_label, accompanied by a better explanation?

[jcmelati]

In my opinion "type" sounds more natural.

Quick exercise: If I have for example 3 different Trust Marks representing different qualities, what is the "spoken" difference between them?
Do I have 3 different "types" of Trust Marks? Or 3 different "classes" of Trust Marks? "Kinds"?
Whatever sounds more natural is probably the best choice.

[selfissued]

Having thought about it for a week since the interop, I now think that trust_mark_type is the most natural name for this.

[Razumain]

I'm sorry to disagree, but I think we are moving backwards here.

trust_mark_id makes perfect sense to me. This is an identifier of a TrustMark. It's straightforward and logical. And we just got through a whole pile of work, changing this from "id" to "trust_mark_id".

I understand that you may see an issue that an ID should be an ID of an instance, like if you have 50 certificates of the same type, they need different individual ID:s. But that is not the case here. You can only have a trust mark with an ID, or not. You can't have several. So in this case, ID works as a class identifier.

Why the alternative are worse:

• kind and type: defines a group of classes. Like what kind of car do you have. same with type.
• label: Is more commonly used to provide a descriptive text.

What we have here is actually an identifier. Something that identifiers exactly which trust mark this is.

[zachmann]

I mostly agree with Stefan, type for me also sounds like a group of classes. Type is something where there exists a handful, but not hundreds, thousands or more. But this would by the case with trust marks.

I also agree hat I think t indeed is an identifier for a "Trust Mark" - the abstract thing, not the individual JWT.

However, you can have multiple JWTs of one Trust Mark (id) - (they might be issued by the same or different issuers). And those JWT instances also might have an id, but this is not the same and we have jti for that.

Keep speaking in the picture of cars. I would see it somewhat like this:

• The car manufacturers are trust mark issuers
• Cars are trust marks
• There could be different types of cars, like SUVs, sports car, limousine - the same could be applied to trust marks but we don't do this currently and I don't have a good example.
• The car manufacturer produces different car models (trust marks) they will have an id -> The trust mark id
• Each instance of a car will have a serial number -> the jti

Personally, this seems reasonable and I think trust_mark_id is understandable, but I would agree that we need some clarifications around it.

[peppelinux]

A label is human-readable and mainly for display or editorial purposes. It can vary by language or context and is not unique.

A class/type identifier (like trust_mark_type) is a stable, machine-readable value that uniquely identifies the trust mark’s category, ensuring interoperability and clarity across systems.

Personally, I strongly prefer using trust_mark_type for its precision and reliability.

[Razumain]

I'm looking at how "identifier" or "id" is used in other places, and I think it is perfectly in line with how "trust_mark_id" is used in this case.

I think the root of the problem is the confusion between what a TrustMark actually is in the spec, as we discussed in the workshop. The text is inherently unclear whether a TrustMark is the JWT, or a status awarded to an entity.

I think if we clarify this first, this issue will resolve itself. So please at least wait with determining this before we solve the bigger issue.

If you view the Trust Mark as the instance of a JWT, then I see the problem raised here. If you clarify that the trust_mark_id is an ID that uniquely represents a specific set of requirements that must be met to get a TrustMark, then it makes sense to keep it as it is.

The text in the document today identifies the TrustMark as the JWT. And that is absolutely fine, until you try to define what a status endpoint does. To ask about the status of an individual JWT seems very useless and a service that is almost impossible to provide if you are generous to issue new JWT:s upon request (which we are). All the requester is interested in is if a particular entity has the right to this TrustMark (has been certified to be in compliance with the requirements). I bet that all implementations has implemented this logic and that none attempts to return the status of an individual JWT.

I still think "trust_mark_id" is the best label for an identifier that identifies the set of rules for this TrustMark. This ID distinguish this TrustMark from any other TrustMark representing different rules.

However, if you still think you need to change it, I would rather look into solutions like:

• trust_mark_definition
• trust_mark_requirements
• trust_mark_rules
• trust_mark_policy
• trust_mark_declaration

All of these could also be extended with "_id"

Why I still struggle is because TrustMarks can also be self-issued and mean virtually anything like "I'm an OP", "I'm a member of this group" or what ever you choose. There are always cases where the labels above are not spot on. Except just using "trust_mark_id".