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 aProduct as thecredentialSubject 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"

Imisunderstood that error to mean that the problem was that theclaim property was not defined by thetype of the object in thecredentialSubject - theProduct. The "fix" therefore was to either:

• Add aclaim property to the type defined in the context for theProduct, or extend thatProduct type and add the extra property, or
• Create a new type that is composed of both the originalProduct and theclaim property (aProductClaims type) and use that in thecredentialSubject

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 asmallest 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 aREADME.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 foundgeneral confusion of devs modelling VC data in the past, specifically things like asking whether thecredentialSubject should be split intosubject andclaim properties (seew3c/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 thecredentialSubject and add the extraclaim property, getting the "invalid property" error and thinking the type of thecredentialSubject needs to be something which includes theclaim, 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.