Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 6 commits into from
Apr 6, 2024
Merged

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

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
0e8a514
added human readable/machine readable, changed example to be more clear.
mkhraisha Feb 6, 2024
89ab44f
Update index.html
mkhraisha Feb 6, 2024
a209b44
Update index.html
mkhraisha Feb 6, 2024
f0e2f83
revert example changes
mkhraisha Mar 5, 2024
c95f903
Update index.html
mkhraisha Mar 5, 2024
86fd178
Update index.html
mkhraisha Mar 13, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -636,10 +636,11 @@ <h3>BitstringStatusListCredential</h3>
minimum two properties:
<ul>
<li id="status">
`status`, being a string of the hex value of the status
`status`, being a machine-readable string of the hex value of the status
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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`

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Member

@msporny msporny Mar 5, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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."

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

w3ctag/design-principles#453

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Applied @aphillips changes in 6626331.

</li>
<li id="message">
`message`, being a string containing the associated message
`message`, being an informative string used by software developers to
assist with debugging which SHOULD NOT be displayed to end users.
</li>
</ul>
Implementers MAY add additional values to objects in the `statusMessage` array.
Expand Down
Loading