Implement feedback

[ldexterldesign]

Sorry for not getting to this sooner. I've been off the grid for a while.

I like the way the custom keywords are working out. The only issue is that $comment doesn't make sense in alias. alias is not a schema, so putting JSON Schema keywords in there doesn't make sense. I'd move that up a level.

The main problem I see is missing properties keywords in a few places. Mostly, I see this at the top level. For example, it looks like you intend the following to be top level properties: buyer, priceSpecification, product, seller, service. These need to be under a properties keyword.

Hi @jdesrosiers!

Thanks for feedback - very kind

I've deleted the gist and migrated it to this repo, which I created the other day - it's almost identical to the gist with the exception of some bits unrelated to your feedback

I'll implement your feedback in a commit shortly and hope you'd be kind enough to glance at it again so I can resolve this issue

Sincerely

[ldexterldesign]

$comment doesn't make sense in alias. alias is not a schema, so putting JSON Schema keywords in there doesn't make sense

I deleted the $comment but still a little unsure why it doesn't make sense there

My [understanding] of $comments is was that they can appear anywhere but rereading it I see there are some stipulations (i.e. [...] "strictly intended for adding comments to the JSON schema source") - is this what you're referring to?

[understanding]:

4.9.2 Comments

New in draft 7 $comment

The $comment keyword is strictly intended for adding comments to the JSON schema source. Its value must always be a string. Unlike the annotations title, description and examples, JSON schema implementations aren’t allowed to attach any meaning or behavior to it whatsoever, and may even strip them at any time. Therefore, they are useful for leaving notes to future editors of a JSON schema, (which is quite likely your future self), but should not be used to communicate to users of the schema.

2020-04-12 - Understanding JSON Schema - Michael Droettboom

[ldexterldesign]

The main problem I see is missing properties keywords in a few places. Mostly, I see this at the top level. For example, it looks like you intend the following to be top level properties: buyer, priceSpecification, product, seller, service. These need to be under a properties keyword.

Doh, good spot!

8aa573d

Thanks

[jdesrosiers]

Regarding $comment, let's look at this example ...

{
  "type": "object",
  "properties": {
    "foo": { "type": "string" },
    "bar": { "type": "number" }
  }
}

In this example, the value at #/properties is not a schema. It's an object whose values are schemas. "foo" and "bar" are not keywords, they are property names. If we put a "$comment" under properties, it wouldn't be interpreted as a keyword, it would be be a property name.

{
  "type": "object",
  "properties": {
    "$comment": { "type": "string" },
    "foo": { "type": "string" },
    "bar": { "type": "number" }
  }
}

Here, "$comment" is not a comment, it's a just a property name. So, when I say that alias is not a schema, that's the kind of thing I mean.

[ldexterldesign]

Thanks again for your help!

[ldexterldesign]

Hi @jdesrosiers,

Sorry to necro this

Can you foresee a problem with this method?

Before:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "alias": {
        "s": "http://schema.org"
    },
    "definitions": {
        "disambiguatingDescription": {
            "$id": "#disambiguatingDescription",
            "s:additionalType": "http://schema.org/Text",
            "s:sameAs": "http://schema.org/disambiguatingDescription",
            "type": "string"
        } [...]

After:

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "alias": {
        "s": "http://schema.org"
    },
    "definitions": {
        "disambiguatingDescription": {
            "$id": "#disambiguatingDescription",
            "s:additionalType": "s:Text",
            "s:sameAs": "s:disambiguatingDescription",
            "type": "string"
        } [...]

Hope to hear back

Sincerely

[jdesrosiers]

Seems reasonable to me. I don't see any issues.

[ldexterldesign]

Hi @jdesrosiers,

Hope you're well

Is there any documentation for this alias technique - correct me if I'm wrong but I vaguely recall you said you "made it up"?:

• If yes then I'd love to understand, syntactically, what's going on here more

Example, for the after code block above would both of these be correct?:

[...]
    "alias": {
        "s": "http://schema.org"
    },
[...]

[...]
    "alias": {
        "s": "http://schema.org/"
    },
[...]

Hope to hear back

Sincerely

[jdesrosiers]

Yep, we made it up, so you can define it to do whatever you want. It was inspired by how aliasing works in JSON-LD, so I'd suggest that you do whatever JSON-LD is doing. I'm pretty sure it uses standard URI resolution, but it's possible that it uses string concatenation. You'll have to look up the documentation to be sure.

[ldexterldesign]

Yes, JSON-LD compact IRIs is nice; tersely illustrates keyword and type (just working my way through this spec' but it's pretty dense 😔)

Presuming the vocabulary has all keywords I need, I'm now left wondering why I should even use JSON Schema..?

I always (naively, not knowing JSON-LD fully) evaluated based on whether I need it on the web (i.e. to link data)?:

• If yes then JSON-LD
• If no then JSON Schema

... but I wonder how you evaluate?

Can I combine JSON Schema and JSON-LD?

For instance, I haven't seen anything in the JSON-LD spec' yet that allows me to combine schemas conditionally like in JSON Schema

Hope to hear back

Sincerely

[ldexterldesign]

👋 https://json-schema.slack.com/archives/C5CF75URH/p1598224172025500

[jdesrosiers]

What are you trying to accomplish?

Presuming the vocabulary has all keywords I need, I'm now left wondering why I should even use JSON Schema..?

This doesn't make sense. JSON Schema and JSON-LD are not alternatives. They do very different things. If you need to validate the structure of JSON data, then JSON Schema is what you need. You can't validate JSON with JSON-LD. If you need to assign semantics to your data, then JSON-LD is what you need. You can't assign semantics to data with JSON Schema.

Can I combine JSON Schema and JSON-LD?

I'm not entirely sure what that means.

Can you validate a JSON-LD document with JSON Schema? No, JSON-LD doesn't have a single fixed structure, so validating it's structure with JSON Schema would be inconclusive. However, you can validate a JSON document with JSON Schema and then apply a JSON-LD context to the JSON document to get a JSON-LD document.

Can you define semantics and validation constraints in the same document? Not without inventing a JSON Schema vocabulary as we have done here. If you do this, however, you can't expect tools to automatically understand what you've invented. You'll have to write your own tooling to make use of the thing you invented.

I can imagine an application needing both JSON-LD and JSON Schema, but not at the same time. You might need one in one context and another in another context. I'd have to know more about what you are trying to do to advise which to use. But, I suspect there is some fundamental misunderstanding at play that is the cause of the confusion.

[ldexterldesign]

I read a bit more of the JSON-LD spec' yesterday so I'm a little clearer on what it does...

What are you trying to accomplish?

A logical process/workflow that comprises structure validation AND semantic validation really

🎯 This is the explanation I was looking for; practically how to go from a JSON Schema document to a JSON-LD document:

You can validate a JSON document with JSON Schema and then apply a JSON-LD context to the JSON document to get a JSON-LD document.

Sincerely

[jdesrosiers]

A logical process/workflow that comprises structure validation AND semantic validation

I'm afraid this doesn't clear anything up for me. A process/workflow for what? Are you developing a static website, a web app, an API, something else? All of these things and more will factor into what you choose. What does "semantic validation" mean?

how to go from a JSON Schema document to a JSON-LD document

There might be some confusion here. You can't go from a JSON Schema to a JSON-LD document. If you start with a plain JSON document you have two paths you can take. One involves JSON Schema and the other involves JSON-LD.

1. validate(JSON, JSON Schema) => boolean
2. applyContext(JSON, JSON-LD context) => JSON-LD

You can't do this: validate(JSON-LD, JSON Schema) => boolean.

In theory, if you invent a JSON Schema vocabulary for linked data, let's call it "JSON-LD Schema" you could do

1. validate(JSON, JSON-LD Schema) => boolean
2. applyContext(JSON, JSON-LD Schema) => JSON-LD

But, I'm fairly certain that not even inventing a vocabulary will allow you to do this: validate(JSON-LD, JSON-LD Schema) => boolean

[karenetheridge]

FWIW, I don't think this is legal in json schema (anchor names are referenced with # (the fragment indicator), but when identifying the name, the # should be omitted):

"$id": "#disambiguatingDescription",

[jdesrosiers]

@karenetheridge "$id": "#disambiguatingDescription" is correct in draft-06/7. In draft 2019-09, you would use "$anchor": "disambiguatingDescription" (without the #) instead.

[karenetheridge]

Yes, I saw "$schema": "http://json-schema.org/draft-07/schema#", in an example above so I was speaking regarding that spec version.

[ldexterldesign]

@jdesrosiers

A process/workflow for what?

A context-agnostic JSON data structuring process/workflow

I often create data structures simply to make sense of data (e.g. query, sort) so JSON Schema is useful because I can use tools to validate data structures. To date this is what I've been doing but I see some features in JSON-LD that I'd like to use (e.g. aliasing) for semantic validation (i.e. vocabulary, type, keyword). I don't know any tools to help automate semantic validation but I can reference type and keywords manually using this alias technique so first and foremost it's useful for my future self.

Are you developing a static website, a web app, an API, something else?

None of the above (yet), but I may want to use my data in (one of) these contexts later

What does "semantic validation" mean?

I infer "semantic validation" is validating keywords are part of an object's type but please correct me if I'm wrong (I suspect you may be referring to JSON-LD syntax tokens and keywords, which I suppose could be automated)

I'm now clear JSON Schema and JSON-LD are mutually exclusive

I guess a better question would be: if I'm using JSON Schema when should I involve JSON-LD?

Sincerely

[jdesrosiers]

I infer "semantic validation" is validating keywords are part of an object's type but please correct me if I'm wrong

I'm not sure that makes sense. JSON-LD gives meaning to data. Asserting that properties are part of an object's type sounds like structural validation. An object is a structure.

if I'm using JSON Schema when should I involve JSON-LD?

Let's say you want to aggregate several databases with information about people. All of these databases store names in different ways. One might use "firstName" while another uses "first_name" and yet another uses "givenName". As humans, we understand the semantics of those names and can successfully make sense of any of those records. But a computer will need someone to map all of those different names to the same concept. If all of those databases make their data available as JSON-LD which says something like "firstName" means https://schema.org/givenName, then your aggregation service doesn't need a human middleman to translate.

So, I would get JSON-LD involved if you expect a third party to be able understand your data without having to coordinate with you about your internal data model. A real life example is web crawlers. If they find JSON-LD on your web page, they can use that information to better index your site and provide more effective search results.

[ldexterldesign]

@jdesrosiers

I'm not sure that makes sense. JSON-LD gives meaning to data. Asserting that properties are part of an object's type sounds like structural validation. An object is a structure.

Yes, your point makes (more) sense

JSON Schema for structural validation and JSON-LD for semantic validation helps clarify things

Aside, I'm looking at creating some data instances from this repo's data schema using JSON-LD - practically how would one go about doing that?:

1. Create the JSON instance
2. Validate JSON instance structure with JSON schema
3. Add JSON-LD (i.e. @context)
4. Validate JSON-LD instance semantics with [tool/s]?
5. Validate JSON-LD instance structure with JSON schema?

I guess #3 should be fairly painless, since I'm already using this alias technique and have all the IRIs..?

Unsure about #4 and #5 (i.e. maintaining these files (e.g. json-schema.json, json-instance.json, json-ld.json))?

Sincerely

NB I did see this:

Can you validate a JSON-LD document with JSON Schema? No, JSON-LD doesn't have a single fixed structure, so validating it's structure with JSON Schema would be inconclusive. However, you can validate a JSON document with JSON Schema and then apply a JSON-LD context to the JSON document to get a JSON-LD document.

[jdesrosiers]

4. Validate JSON-LD instance semantics with [tool/s]?

The concept of "validating semantics" still sounds like nonsense to me. Semantics are arbitrary. Some blob of data represents a book because I say it represents a book. What would a semantic validator do? Would it tell me, "Actually, that data doesn't represent a book, it's more of a pamphlet."? No, it's a book because I decided it is to be understood to be a book.

You need to decouple any concept of validation (semantic or otherwise) from JSON-LD. That's just not what it's for.

5. Validate JSON-LD instance structure with JSON schema?

Like I said, I don't think this is possible. The good news is it's also unnecessary because you've already validated the structure in step 2. You don't need to do it again. Your data didn't change because you added a @context. The @context just provides enough metadata to transform JSON into RDF.

---

I probably shouldn't bring up something new at this point, but you might be interested in SHACL (https://shacl.org/playground/). SHACL is kinda like JSON Schema for RDF. Since JSON-LD is just a JSON serialization of RDF, you can use SHACL to validate JSON-LD documents. So your process would be:

1. Create SHACL schema
2. Create JSON-LD instances
3. Validate each JSON-LD instance against SHACL schema
4. Make your JSON-LD data available to the world (because otherwise, what was the point?)

If you really want/need JSON-LD, this might be a more integrated workflow. The downside is that SHACL is relatively new and not widely adopted. You'll have difficulty finding tools and the learning curve will likely be steep. I personally don't know SHACL beyond the high level description I've given you here, so I can't comment on it's capabilities compared to JSON Schema. It might suit your needs and it might not.

[ldexterldesign]

@jdesrosiers

What would a semantic validator do?

Erm, validate that name is the correct type (i.e. string not a number):

{
    "@context": "https://json-ld.org/contexts/person.jsonld",
    "@id": "http://dbpedia.org/resource/John_Lennon",
    "name": "John Lennon",
    "born": "1940-10-09",
  }

{
    "@context": "https://json-ld.org/contexts/person.jsonld",
    "@id": "http://dbpedia.org/resource/John_Lennon",
    "name": 5,
    "born": "1940-10-09",
  }

Sorry, I now see that mostly everything in JSON-LD is a string (haven't got this far in the spec' yet 🤭) and presume, as you say, that validating this type of thing (i.e. semantics) isn't the job of JSON-LD; it's the job of JSON Schema (i.e. structure)

I probably shouldn't bring up something new at this point, but you might be interested in SHACL

LOL

Bit busy ATM

Sincerely