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!