"Dropping property..." error could avoid devs assuming property needs to be defined on relevant type

[absoludity]

Specifically, help devs less familiar with JSON-LD/RDF understand the difference between a typed property and a predicate property.

Background

While learning JSON-LD and attempting to model UNTP credentials, we were trying to use a Product as the credentialSubject for a VC, while adding an extra property (claims about that product), as that is one of the promises of the less-rigid jsonld/rdf (over other object modelling languages). But this would result in invalid JSON-LD, with the following error returned by the cli:

{
  "name": "jsonld.ValidationError",
  "details": {
    "event": {
      "type": [ "JsonLdEvent" ],
      "code": "invalid property",
      "level": "warning",
      "message": "Dropping property that did not expand into an absolute IRI or keyword.",
      "details": { "property": "claim", "expandedProperty": "claim" }
    }
  }
}

The "fix"

I misunderstood that error to mean that the problem was that the claim property was not defined by the type of the object in the credentialSubject - the Product. The "fix" therefore was to either:

• Add a claim property to the type defined in the context for the Product, or extend that Product type and add the extra property, or
• Create a new type that is composed of both the original Product and the claim property (a ProductClaims type) and use that in the credentialSubject

both of which worked to "fix" the validation error, but led to considerably more complex types/models (and away from the intent of the VC model)

The actual fix

After reading an email interaction between @onthebreeze and @msporny about this, and creating a smallest working example to further understand, I realise that the returned error is more general than I had read it: it isn't saying the property didn't exist on the type, but just that the property wasn't defined at all (not necessarily on the type) - and need not even be understood as a property of that type. In fact, in this context, it just needs to be defined and used as a predicate to relate the Product to the claim(s). I've detailed this with a smallest working example in a README.md for the above example repo, which allows the extra property (a predicate) to exist on the object data without adding the property to the type - and is still valid jsonld.

Helping future community devs

More generally, I'm wondering if the jsonld-cli tool can help avoid developers going down this path when less familiar with jsonld/rdf. If it's just my misunderstanding, it may not be worth improving the error response here, but I've found general confusion of devs modelling VC data in the past, specifically things like asking whether the credentialSubject should be split into subject and claim properties (see w3c/vc-data-model#1130 but it comes up a few times in the history) . I'm not sure, but wonder if this question arrises for the same reason: developers trying to model the credentialSubject and add the extra claim property, getting the "invalid property" error and thinking the type of the credentialSubject needs to be something which includes the claim, as I did.

If the error said something more verbose, including contextual data, like:

Dropping property that did not expand into an absolute IRI or keyword. Either the "Product" type should include a property "claim" in its context, or the "claim" term should be defined separately as a predicate for relating a subject to other data. See <url> for an example.

it may help future devs modelling and validating data with the jsonld tool (in particular, credentialSubject data) avoid going down the wrong path to fix the issue.

I realise my attempt at the error message is probably not accurate, but hopefully conveys the gist.

[msporny]

Hey @absoludity -- we really appreciate the thoughtful issue w/ analysis of the problem and proposed solution. I do think the tools could do a better job of reporting errors and possible solutions for those errors. We are also working on tooling to help make data modelling better/easier (see yml2vocab). We are also looking into using LLMs, combined with the JSON-LD Best Practices to provide tips and reduce the sort of pain you experienced above.

All this to say that we realize things could be better, and part of the issue is the number of people working to make the tooling better vs. the number of people using the tooling (the latter far outweighing the former). I'm going to pull @BigBlueHat into this since he's working on improving the DX around JSON-LD (and the new JSON-LD WG is just now kicking off to figure out how to sand off some of these rough edges).

I haven't had time to think about what might be best for your specific issue above, but just wanted to note and acknowledgement that there is a problem that could be improved with better tooling and error messages.

[absoludity]

Great, thanks @msporny . I just wanted to document it while it was fresh... the actual issue was my own misunderstanding, but just thought it might help a future dev avoid the same mistake, given it seems I might not be the first to fall in that trap. Thanks for the quick feedback!

[absoludity]

Just another note regarding one of the ways we attempted to fix the original issue, which with some adjustment, we've just found can result in identical expanded json-ld as the predicate, while still allowing an object definition (and so the ability to generate a schema etc.) including the relationship:

• Create a new type that is composed of both the original Product and the claim property (a ProductClaims type) and use that in the credentialSubject

What we just tried in addition to this is:

• Updating the new ProductClaim type to masquerade as the Product type (by setting the id identically)

With that, it remains valid jsonld and expands to the identical expanded jsonld (and so RDF, I assume).

I've tested this in a PR to my smallest example, which you can view at absoludity/vc-experiment#1

Unless there are some really bad reasons not to do this, it gives us a big advantage of being able to use a tool to automatically generate JSON-Schema files for the credentials as well as sample data etc. (see jargon-sh/issues#65 where I've discussed this same issue with the author of that tool). Guessing you'd not want to recommend this approach for your best practices though.