What is the philosophy of this vocabulary?

[gregsdennis]

This project has a charter, but it's not descriptive as to what the goals of the project are (or even defining what it means by "IDL"). The readme and charter should probably be updated to include these things.

---

An interface description/definition language (IDL), at its heart, defines an interaction layer between two languages.

IDLs describe an interface in a language-independent way, enabling communication between software components that do not share one language

As such, the primary goal of this project should be to define a set of JSON Schema conventions that align with the concepts and constructs available in various programming languages (further just "languages") for two purposes:

• generation of language code from schemas
• generation of schemas from language code

Ideally, in my opinion, these two purposes should cooperate to the degree that a schema that is generated from language code can then be used to regenerate the original (or functionality equivalent) code, and vice versa.

---

There is a disparity between JSON Schema and languages. Specifically JSON Schema is constraints-based while languages are typically definition-based. I think Henry described the problem well in his blog post.

JSON Schema is a subtractive system, in which an empty schema matches every instance, and each constraint added to the schema decreases the set of matching instances.

Languages are additive systems, in which an empty type definition matches no instance, and each property added to the type increases the set of matching instances.

The point of this vocabulary is to bridge this gap.

All of the issues up through #21 have had the mindset of trying to figure out what some JSON Schema construct might mean in a language. But the inherent flaw with that approach is that most JSON Schema constructs likely will not map to a language concept. Moreover, those JSON Schema constructs which do appear to have some sort of language parallel are often incompatible (e.g. enum).

This is trying to fit the square peg of JSON Schema into the round hole of languages. They're fundamentally incompatible. There are ideas in JSON Schema that just don't map to languages. Conversely there are ideas in languages that can't be represented using core ("out of the box") JSON Schema. In order to get any kind of compatibility between the two worlds, two things must happen:

• This vocabulary must define ways to represent language concepts in JSON Schema that the core specs can't sufficiently provide.
• Some core JSON Schema constructs must be disallowed or redefined in this context as they have no parallel in languages.

As we, the JSON Schema org, do not control languages, we cannot change or amend them to align with the capabililties of JSON Schema. Therefore, it is incumbant upon us to amend JSON Schema, via this vocabulary, to align with the capabilities of languages. To do this, we must start with those languages by enumerating their features, and, for each language feature, find a way to represent it in JSON Schema using either existing keywords or defining new ones.