Questions about the JSON-LD JSON Schema

[handrews]

Hi folks,
Some documents, such as the W3C Web of Things "Thing Description", use JSON-LD and JSON Schema in the same document.

Over at the JSON Schema project, we are working on a concept of Schema Vocabularies (I know, too many "vocabularies", sorry...) in order to facilitate this kind of usage. The main issue proposing vocabularies is json-schema-org/json-schema-spec#561.

In this view, JSON Schema is not just validation, but also Hyper-Schema, meta-data annotation, code generation hints, UI generation directives, and other things. In fact, most vocabularies will not directly affect validation (e.g. Hyper-Schema adds links, which never cause validation to fail).

Given that there is a JSON Schema for JSON-LD, I want to see if we can treat that schema as describing JSON-LD as a JSON Schema vocabulary. (@gkellogg this is where I've ended up based on the few discussions we had at the W3C WoT conference in Santa Clara about a year ago).

Before diving in, I have a few questions if anyone would be willing to help me understand how this schema works:

• JSON-LD documents are either a node object, or an array of node objects, but at the top level only the object aspect is defined. Should it be something like this instead? (Note the added items):

{
    "title": "Schema for JSON-LD",
    "$schema": "http://json-schema.org/draft-04/schema#",
    "definitions": {...},
    "allOf": [
        { "$ref": "#/definitions/context" },
        { "$ref": "#/definitions/graph" },
        { "$ref": "#/definitions/common" }
    ],

    "type": ["object", "array"],
    "additionalProperties": true,
    "items": {
        "allOf": [
            { "$ref": "#/definitions/context" },
            { "$ref": "#/definitions/graph" },
            { "$ref": "#/definitions/common" }
        ]
    }
}

• The @graph definition is the other way- it allows either an object or an array, but only specifies contents for an array. Which it does with additionalItems which is not correct (it should be items unless items is already present and an array, although many validators will use additionalItems as you have written it because draft-04 was unclear about that). Should there be properties or additionalProperties defined for @graph?

• Why was the allOf changed from anyOf to allOf? At first glance, anyOf seems correct, but I don't know JSON-LD well at all so I assume I'm missing something.

• Why are $refs to #/definitions/common wrapped in an anyOf even when they are the only entry in the anyOf and the anyOf is the only keyword in the subschema? (for example, lines 28-30

Thanks for any help you can offer!

[handrews]

I'm starting to write PRs for json-schema-org/json-schema-spec#561 (Basic vocabulary support), so if there is any feedback from the JSON-LD community on this concept, now would be a great time to comment :-)

I'm still just writing up the basics, but if anyone can reply to the questions I had above that would help me as I move on to specific uses as they relate to JSON-LD. I just want to make sure I'm reading things correctly and starting from an accurate description of JSON-LD when considering how to integrate it.

[akuckartz]

I have not yet looked at the questions in detail. But I suppose that answers for the yet unfinished JSON-LD 1.1 would be as helpful as for 1.0. Correct?

[millercl]

JSON-LD validation is possible using existing tools: jsonlint, jsonld, shalc. I didn't even attempt feasibility with JSON Schema because it seemed tree-oriented; which is to assume it would be incapable of interpreting the graph data model. Having jsonld reformat a document (compact, flatten, etc.) will expose whether it is valid JSON-LD or not. Would rather see SHACL-AF implemented in JavaScript.

[handrews]

@akuckartz I believe so

@millercl people using JSON LD have come to the JSON Schema project a number of times in the past and asked about it. JSON Schema is not attempting to solve the same problems as most, possibly all, of those tools you mention. If you need those tools, use them- this question is not directed at your use case.

[BigBlueHat]

@handrews first, thanks for digging into all this topic!

In the Web Annotation Working Group we used JSON Schemas to test the required tree structure for Web Annotation documents. Due to probably the same limitations you're looking to address, we ended up breaking up the schemas into several and used them in succession--because (as far as I recall) wasn't possible to check all the variations from a single schema.

Also, the new JSON-LD Working Group is now in full swing! It'd be great to have your thoughts, questions, ideas, and/or concerns raised on the new mailing list or issues on the new repositories.

Thanks again for exploring this use case!

[handrews]

@BigBlueHat you're welcome! Is there a particular new repository where it would be good to have a new tracking issue for this? At the moment I have my hands full with JSON Schema and closely related projects. I'll respond if you @-mention me, but I can't keep up with an entire project's mailing list or notifications at this time. I also just started a new job, so maybe once I'm a bit more settled in that I'll be able to take on more.

[BigBlueHat]

Understand completely! The primary repos are https://github.com/w3c/json-ld-syntax/ and https://github.com/w3c/json-ld-api/ (for syntax and API respectively). The syntax one is likely the best place to start for specific requests/needs for the shape of the JSON-LD.

I'll try to keep an eye on this space also, so if you have specific needs (but not the time to file the issues), you can @ mention me. Between the two of us, we should be able to get both these specs headed toward each other a bit more. 😁

Thanks for all you do here!
🎩

[marcadella]

@handrews you were saying when you started this issue that

JSON Schema is not just validation, but also Hyper-Schema, meta-data annotation, code generation hints, UI generation directives, and other things

I've had a look at JSON schema 2019-09 and of course there is validation and hyper-schema, but I don't think the spec offers any solution for the last 3 items (meta-data annotation, code generation hints, UI generation directives). Any hope to see those area covered in the spec or should I look somewhere else?

[handrews]

@marcadella 2019-09 adds $vocabulary, a mechanism for defining and requiring 3rd-party re-usable keyword vocabularies. A vocabulary is associated with a URI, so an extensible implementation could support a plugin architecture matching a plugin to a vocabulary URI, and handing keyword processing to that plugin.

That is how we expect to see those other use cases solved. Preferably by someone other than the core JSON Schema spec team as we have our hands full as it is. OpenAPI is very interested in the code generation part in particular, and as soon as we have the next OpenAPI version out that aligns with the latest (probably 2020-06?) JSON Schema draft, the OpenAPI code generation tooling ecosystem will start working on that problem.