added human readable/machine readable, changed example to be more clear.

[mkhraisha]

Status field should be machine readable, message should be human readable, I changed the example to make the message more clearly human readable.

---

Preview | Diff

[msporny]

Status field should be machine readable, message should be human readable, I changed the example to make the message more clearly human readable.

I was afraid that this was going to be the answer.

Understand that this will trigger i18n requirements on the "message" field and will require explanatory text wrt. how one supports i18n on the field. You'll want to do two things at this point:

1. Point to the section on i18n in the VCDM specification to guide people on how to support i18n for the message string: https://w3c.github.io/vc-data-model/#language-and-base-direction
2. Add a note stating that the message examples just use English for the purposes of making the example easy to read, but any real implementation MUST utilize language markup in order to support i18n properly.

I'm tagging @aphillips and @r12a to review this PR given that they'll be able to let us know if we're hitting the mark with this PR or not.

[msporny]

If we're making the string human-readable now, we're going to have to provide i18n guidance.

[aphillips]

This change undoes the rough "i18n okay-ish" aspect of the current design and is probably more work than you think it is. The value of message is supposed to be in the array credentialSubject.statusMessages. The idea appears to be to provide a debugging friendly pre-defined token in "programmerese". Ideally the value will not tempt developers to show the string to end users, but instead use it as a key for localizable resources.

You especially don't want to localize the string so that recipients can use the value in code to look up what the error is, which means guaranteeing that it's not free text. Admittedly, the status field, which is a hex number, also does this.

If we make the string look like and behave like natural language, then we should take the next step and make it localizable (which might mean removing the message part from the statusMessages array or requiring the whole response to have a default language and direction). You sure you want to do this?

[msporny]

@aphillips wrote:

You sure you want to do this?

editor hat on -- No, for all the reasons you mentioned; I advised against this sort of PR. If this is going to undo the i18n horizontal review approval, we don't want to go down that route unless the implementers feel very strongly that human readable strings are necessary here. I don't think the case has been made for them.

At this point, we'll need the implementers to make a case for why these values are human readable and how they plan to internationalize them given your feedback.

[mkhraisha]

This was not at all the intention behind the change, it was purely to signal that this is intended to be read and consumed by a developer NOT an end user.My intention was something akin to developer digestible debugging tokens.

Does anyone have any suggestions for language that implies the audience is humans but it does not need to be natural language?

[aphillips]

@mkhraisha The text you have does that?

It's fine to use strings instead of numbers as code-like IDs. This is what, for example, enum is for in various programming languages: developers have to read and maintain the code and they have to look at call results and debug stuff. Self-documenting code and data structures are super helpful. It's a lot easier to figure out what invalid_value is than remember what 0x1E stands for.

However, we want to make it unappealing to show these (usually English) strings to actual end users outside of a debugging environment. It's a super common I18N bug to assume that the word(s) in the error will mean something to the user (who might not speak English).

So the I18N group is "okay" with you having a string there for debugging. And we recognize that developers might abuse that string by putting a displayable value in there--we can't stop them. But your example should use code-like formatting (pending_review vs. Pending Review) to get the point across not to do that. Saying this explicitly in you spec and making examples like this is the fig leaf that saves us from having to decorate the developer-convenient fields with language and string direction or enable localization.

[mkhraisha]

I have reverted the example changes to be inline with the previous ones, @msporny does that resolve your CR?

[aphillips]

I think this change isn't necessary? Machines can, of course, read the status field. The key thing is that it is a string representation of a hexadecimal value. It's maybe a little curious that you don't specify the format? The examples shows e.g. 0x0 or 0x1, but DEADBEEF, -1e, or 10EF are "hex strings" too. Perhaps:

Suggested change

	`status`, being a machine-readable string of the hex value of the status
	`status`, a string representing the hexadecimal value of the status prefixed with `0x`

[mkhraisha]

@mprorock @msporny correct me if i'm wrong, but I believe 0x1 was just an example, and we do not intend to limit hex values to be prefixed with 0x1.

my understanding of current consensus is that this is a predifined list of status codes that the issuer is responsible for providing a definition for.

[msporny]

There is no consensus on this feature outside of the Traceability cohort (other implementers aren't implementing it; we're putting it in there for Transmute, Mesur.io, and Mavennet).

You guys will need to implement this and tell us how you intended to use this feature.

IIRC, "0x1" wasn't an example, it was intended to express a hexadecimal value in a very specific format. I was presuming that the "message" field contained information that was useful to a developer, but MUST NOT be conveyed to an end-user (which seems to be what we're back to in this PR).

Please check w/ the Traceability folks to help us understand how they want to encode and use the status field and the message field. I expect that something like this will be acceptable to i18n:

"status": "0x1", "message": "frobinator_error"

but something like this will cause i18n issues (as it should, because it's not clear that the status value is a hexadecimal value and that message is not meant to be displayed to end users:

"status": "deadbeef", "message": "ERROR: The frobinator is no longer connected to the deviator."

[mprorock]

@mprorock @msporny correct me if i'm wrong, but I believe 0x1 was just an example, and we do not intend to limit hex values to be prefixed with 0x1.

my understanding of current consensus is that this is a predifined list of status codes that the issuer is responsible for providing a definition for.

we utilize hex codes most often, however, we are open to a definition that does not block use of a hex code of the index - this is NOT user facing information

[OR13]

w3ctag/design-principles#453

[msporny]

@OR13 @mkhraisha @mprorock ping again -- trying to get closure on this issue so we can have a clear path to Candidate Recommendation in two weeks.

[mkhraisha]

This feature is required by the traceability cohort.
We should not restrict it to hex codes however.

[msporny]

Ok, got it, so here's where we are as of right now:

• This is a required feature for Traceability, that's the only place the requirements for this feature are coming from at this moment in time.
• @aphillips seems to agree that if the "message" field is only meant for developers that we don't need a full localization treatment on the field.
• There is no way that we can provide "packed" encoding for the status field unless we use some sort of binary expression for the status value.

As such, we're just going to go with all that, merge this PR (with @aphillips additions), and call it a day.

@mprorock @msporny correct me if i'm wrong, but I believe 0x1 was just an example, and we do not intend to limit hex values to be prefixed with 0x1.

If you want a packed bitfield structure, you're going to have to use a binary representation of some kind. I don't think we can leave this open ended and hope for interop on that requirement from Traceability.

[msporny]

@mkhraisha looks like you didn't allow Editors to modify your PR. I'm going to merge what you have and apply @aphillips' changes on top of that.

[msporny]

Applied @aphillips changes in 6626331.

[msporny]

Normative, multiple reviews, changes requested made (will apply @aphillips' changes post-merge), no objections, merging.