Formalizing the specification

[joostfarla]

We need to agree on how we write, identify, and test requirements as part of the specification.

Some basic principles I would like to propose:

1. BCP 14 keywords. We use the boilerplate from OpenAPI, Arazzo, and Overlay. MUST, SHOULD, MAY and the others have their RFC2119 meaning only when written in capitals (RFC8174). Examples are always informative.
2. Defined terms. The spec has a glossary of the terms its requirements depend on, such as document, ruleset, rule, match, result and linter. Requirements use these terms only in their defined meaning. Where a normative reference already defines a term, we link to that definition instead of writing our own.
3. Exact normative references. Every normative reference names an exact version. This matters most for JSONPath, regular expressions, JSON Schema and YAML.
4. One conformance target per requirement. Every requirement says whether it applies to a ruleset or to a linter, never both.
5. A permanent ID for every requirement. Linters, reports, etc. can refer to a requirement by its ID. An ID keeps its meaning across releases and is never reused. When we drop a requirement, its ID stays listed as removed.
6. Conformance tests for every requirement. The spec lists the tests for each requirement, and the conformance suite implements them. See example below.
7. A defined result model. We adopt the result model Spectral uses for its JSON output (code, path, severity, message, range, source) and make it normative.
8. Immutable releases. Every release lives at its own URL, like spec.openlint.org/1.0.0/, and never changes after it's published. A fix means a new patch release. Work in progress lives at spec.openlint.org/draft/.

A requirement with its test could look like this:

Requirement  /req/given/no-match
             If a rule's `given` matches nothing in a document, the linter MUST NOT report results for that rule.

Test         /conf/given/no-match
Requirement  /req/given/no-match
Method       1. Lint a document without an `info` object, using a single rule with `given: $.info` and `then: { function: truthy }`.
             2. Check that the linter reports no results.

Open questions:

• Do we want to group requirements into conformance classes (modules)?
• Do path-style IDs like the one above work for everyone?
• What form do we use for publication? Respec? Bikeshed? Something else?

[kinlane]

I've created a repo for the spec and kicked off first PR to document - Add the specification, schema and README #1

[kinlane]

I've created an issue to add page for the specification to website - Add a specification page- #7