add glossary entry for 'implementation'

[gregsdennis]

GitHub Issue:

Resolves json-schema-org/json-schema-spec#1440

Summary:

Adds a glossary entry for 'implementation' as discussed in the issue above.

Do you think resolving this issue might require an Architectural Decision Record (ADR)? (significant or noteworthy)

No

[Relequestual]

I think this is at odds with itself.
Code generation doesn't provide or expose anything defined in the specification.
It interprets the semantics of what's defined in the specification.

Applications which use JSON Schema internally without exposing that functionality in some way, for example, validating configuration files or web requests, are not considered implementations.

We list VSCode on the implementations page.

I think this is well intentioned, but this definition doesn't quite work.

[gregsdennis]

If you go back and read the discussion, it aligns with what we decided.

Regardless, I can change it, though I'm not sure what to change it to.

[jdesrosiers]

This sounds great to me!

[jdesrosiers]

@Relequestual

Code generation doesn't provide or expose anything defined in the specification.

I agree that these kinds of things are a bit of a stretch, but they certainly do implement aspects of the spec. They use the structure of the schema, use the same keywords, and implement identification and referencing as defined in the spec. If there's a better way to express this, I'm for it, but I don't think it's inconsistent. There are certainly some grey areas, but I think this definition successfully gets the right idea across.

Applications which use JSON Schema internally without exposing that functionality in some way, for example, validating configuration files or web requests, are not considered implementations.

We list VSCode on the implementations page.

I think you're misunderstanding what that line is saying. VSCode's fits that definition just fine because the functionality is exposed. JSON Schema based validation is presented to the user as inline error messages (as well as several other user facing features). What's not considered an implementation is an application like a REST API that accepts requests and validates those requests against a JSON Schema. The user may never know or care that JSON Schema was used under the hood to validate their request.

[cloudflare-pages]

Deploying with    Cloudflare Pages

Latest commit:	944e6ce
Status:	✅  Deploy successful!
Preview URL:	https://a855f237.website-2v2.pages.dev
Branch Preview URL:	https://gregsdennis-implementation-d.website-2v2.pages.dev

View logs

[Relequestual]

I 100% agree that this is a better definition, more in line with what we expect (Thanks @jdesrosiers). However, when I try to apply this to our current list, it raises some problems.

Consider: AJV. We know the default behaviour is non-compliant. Isn't any "non-compliance" with the spec (aka failing any test), legalistically in contradiction of the spec?

Unless anyone has a clear and obvious solution, maybe this could be discussed at our next OCWM?

[mwadams]

I 100% agree that this is a better definition, more in line with what we expect (Thanks @jdesrosiers). However, when I try to apply this to our current list, it raises some problems.

Consider: AJV. We know the default behaviour is non-compliant. Isn't any "non-compliance" with the spec (aka failing any test), legalistically in contradiction of the spec?

Unless anyone has a clear and obvious solution, maybe this could be discussed at our next OCWM?

I think this is possibly just trying to conflate two things:

1. Do I try to implement (some version or versions) of the spec
2. To what extent is that implementation compliant with the spec

So we have implementations with specific compliance.

(And the test suite is the yardstick for compliance, with bowtie being a great way to publicly demonstrate that compliance)

[Julian]

This has gone past lots of people at this point, and really has had more discussion than any glossary entry probably deserves :D -- so I hesitate to throw in another opinion. So I caveat that I don't think it matters much, we can always change things later if need be, so feel free to ignore my comment. Now, caveat aside:

This seems odd to me. I think to me this is "misusing" the glossary, which I think is why the definition seems awkward.

Glossaries are (I assert) intended to help unfamiliar users ¹ understand how an already used term is already used in a quick and self-contained way. The balance should be on colloquial use, with when possible a precise definition, but if the precise one isn't possible (because it relies on too much other knowledge) then fine, just the colloquial one.

To me this doesn't really do that -- to me what this does is document to us ourselves (the internal team) what we want the definition to be, and it does so for some complete side purpose -- namely defining what software we want to put on a page on the site which happens to be titled "Implementations" but could equally well be titled "JSON Schema Software" or "Stuff We Like".

If it were me, I would have written something like:

a concrete piece of software which exposes functionality defined by the JSON Schema specification to end users. (then perhaps some examples like listed here). Often -- but not always -- an implementation is synonymous with "data validator" (n.b. which I believe is the case)

and left it there. That indeed may exclude "code generation" -- i.e. taking a schema and generating a class in your programming language -- from being an implementation. I personally indeed would not call such software an "implementation of JSON Schema", even if it's software using JSON Schema. And I think that matches how people would colloquially talk about such software. And again I don't think that should have any relevance to whether we list that software on the page on the site :)

Just my 0.02, again feel free to take or leave.

Footnotes

1. a beginner, or anyone who doesn't already know what a specific term means ↩

[Relequestual]

Thanks for revising. I think this accurately reflects what we agree on, while also being easy enough to understand for the intended audience.

[jdesrosiers]

Perhaps we don't need to mention the spec in these definitions. I think @Relequestual had a good point about ajv which intentionally violates that spec, but we still consider it JSON Schema tooling.

Suggested changes are inline if people agree.