Multiple problems example

[sdatspun2]

Examples are using causes for consistency. Added an example for 207 and multiple problems #6 .

[dret]

On 2021-10-12 00:00, Sanjay Dalal wrote:

• "instance": "/account/12345/msgs/abc",
• "instance": "/amount/value/50",

Ohh, that is how you read it. I read it differently. I am trying to point out the value of "that" in "Your current balance is 30, but that costs 50."

this is a slightly confusing edit. the instance message is about the account not having enough funds. but it's very unlikely and probably impractical that this message will be availble at the URI "/amount/value/50".

it is more likely that the service keeps a message log somewhere along the lines of "/account/12345/msgs/abc" and that when accessed, this log message will give you all the relevant details, probably including the "this costs 50 but you only have 30" bit.

[dret]

On 2021-10-12 00:09, Asbjørn Ulsberg wrote:

I think of the value of |instance| as the URI identifying the very |application/problem+json| document you're currently viewing. It seldom actually is in practice, but I think that's what |instance| semantically conveys. Perhaps a clarification in the spec should be provided to avoid confusion?

RFC 7807 says:

A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

the current draft says:

The "instance" member is a JSON string containing a URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.

the current draft has a lot of additional text about relative URIs in that member, but not much regarding the meaning has been changed. do you think we need more text?

[dret]

On 2021-10-12 16:00, Sanjay Dalal wrote:

@.**** commented on this pull request. |/amount/value/50| seems easy to explain in the context of a hypothetical payment transaction vs |/account/12345/msgs/abc| where I would not know what |msgs| and |abc| mean. Is it indicating that account |12345| has messages (|msgs|) and |abc| identifies a message instance and that message instance has a problem |Your current balance is 30, but that costs 50.|? How does this help a client of an API emitting this response?

URIs have no meaning, they are just identifiers. so at some level, this discussion is moot.

but the way RFC 7807 works is that the instance URIs identifies the instance of the error. it could be anything. if it is referencable (which it doesn't have to be) it most likely will reference a message in an error log that you can retrieve and inspect to learn more about the error instance. which is why i much prefer to use a URI that vaguely hints in that direction, rather than having one that vaguely hints in the wrong direction of suggesting that the URI itself has any inherent meaning.

but it seems that by now we have established that this aspect of the spec seems to be harder to understand than we expected, so maybe some additional explanation is warranted.

[dret]

On 2021-10-13 03:25, Sanjay Dalal wrote:

How about now? I have used URI fragment ids in examples and clarified the usage while describing "instance".

i don't find using instance URIs particularly helpful. imho, we should stick to the example of the original RFC, assuming that there is some persistent message storage, and showing how "instance" then could be used to link to that message that represents the problem instance.

[dret]

On 2021-10-16 21:45, Sanjay Dalal wrote:

• "property_location": "#/age"

iff we use this example we probably shouldn't use the fragment identifier separator.

[sdatspun2]

On 2021-10-16 21:45, Sanjay Dalal wrote: + "property_location": "#/age" iff we use this example we probably shouldn't use the fragment identifier separator.

@dret Is this because application/problem+json was not perhaps registered to support fragment identifier syntax or it is just a preference? see my comment on the spec.

{{RFC6901, Section 6}} says that a given media type needs to specify JSON Pointer as its fragment identifier syntax explicitly (usually, in its registration {{RFC6838}}). Does application/problem+json support JSON Pointer's fragment identifier syntax?

[dret]

On 2021-10-17 18:15, Sanjay Dalal wrote:

@dret https://github.com/dret Is this because application/problem+json was not perhaps registered to support fragment identifier syntax or it is just a preference? see my comment on the spec.

as discussed before, RFC 7807 had no intentions of pointing into a resource; "instance" has an entirely different meaning.

[sdatspun2]

On 2021-10-17 18:15, Sanjay Dalal wrote: @dret https://github.com/dret Is this because application/problem+json was not perhaps registered to support fragment identifier syntax or it is just a preference? see my comment on the spec. as discussed before, RFC 7807 had no intentions of pointing into a resource; "instance" has an entirely different meaning.

Got it. Since JSON pointer could be represented either as a string or a URI fragment identifier, API developer could decide. Example is using the fragment identifier, but the description of the extension does not indicate any preference.