Add a compliance section to the impl data

This adds a structured section on compliance, specifically how
to configure for it.  This is *not* intended to be the same sort
of compliance information that the test suite provides.  Rather,
it is about things that implementations document that don't
necessarily show up in test suite results.

This format includes brief instructions and optionally
(ideally) a documentation link.  I think this langauge is
appropriately neutral, and particularly when there is a doc link
it feels more like calling attention to something that is already
advertised rather than being judgemental.

The AJV and Opis cases are straightfoward.

The Common Lisp implementation's case of needing to disable
automatic downloading is worth a bit of thought as that is a
SHOULD NOT rather than a MUST NOT, but this is why the schema
description notes that it is the _most_ compliant config,
and other configs may still be compliant.

Similary, the networknt Java implementation having `nullable`
on by default is not technically non-compliant, but it is more
compliant to not have it.

There may be other compliance configuration changes that need
documenting, but these were the ones that I could find with
a reasonable amount of effort.

Author: handrews

_data/schema.yml

@@ -95,6 +95,8 @@ $defs:
                     Additional information.  Overly promotional (or critical)
                     wording should be avoided.
                 type: string
+            compliance:
+                $ref: "#/$defs/compliance"
             last-updated:
                 description: |
                     The date (in whatever timezone was relevant at the time)
@@ -108,3 +110,49 @@ $defs:
                 type: string
                 format: date
                 pattern: '^\d\d\d\d-[01]\d-[0123]\d$'
+    compliance:
+        description: |
+            The compliance section notes aspects of an implementation's
+            _default configuration_ that are non-compliant with the
+            specification in ways that are _not necessarily_ detected
+            by the test suite.  This information is provided based on
+            implementation documentation.
+        type: object
+        unevaluatedProperties: false
+        properties:
+            constraints:
+                description: |
+                    A brief note of design constraints that impacted choices
+                    regarding compliance.  This includes things like
+                    targeting memory-constrained environments, or trading
+                    off features for performance.  It does not include
+                    opinions regarding the value (or lack thereof) of
+                    the specification requirements.
+                type: string
+            config:
+                description: |
+                    Documents how to configure an implementation to produce
+                    the most specification-compliant behavior if it does
+                    not do so by default.  The resulting configuration
+                    may still have incomplete compliance (such as not
+                    having implemented all keywords), but will not
+                    have additional behavior that contradicts the
+                    specification (such as modifying the instance
+                    by filling in default values).
+                type: object
+                unevaluatedProperties: false
+                required: [instructions]
+                properties:
+                    docs:
+                        description: |
+                            A link to the implementation's configuration
+                            documentation, ideally to whatever part addresses
+                            configuration and compliance.
+                        type: string
+                        format: uri
+                    instructions:
+                        description: |
+                            Instructions to configure for compliance.  Will
+                            appear in a sentence after "you must" and before
+                            "to produce specification-compliant behavior."
+                        type: string

_data/validator-libraries-modern.yml

@@ -73,6 +73,11 @@
       date-draft: [2019-09]
       draft: [7, 6, 4]
       license: LGPL
+      compliance:
+        config:
+          docs: https://github.com/fisxoj/json-schema/blob/master/README.rst
+          instructions: |
+            set `resolve-remote-references` to `nil`
       last-updated: "2022-08-31"
 - name: Elixir
   implementations:
@@ -134,6 +139,10 @@
       date-draft: [2020-12, 2019-09]
       draft: [7, 6, 4]
       license: Apache License 2.0
+      compliance:
+        config:
+            docs: https://github.com/networknt/json-schema-validator/blob/master/doc/config.md
+            instructions: "set `handleNullableField` to `false`"
       last-updated: "2022-08-31"
     - name: Snow
       url: https://github.com/ssilverman/snowy-json
@@ -165,10 +174,14 @@
       last-updated: "2022-08-31"
     - name: ajv
       url: https://github.com/ajv-validator/ajv
-      notes: "for Node.js and browsers - supports [user-defined keywords](https://github.com/ajv-validator/ajv/blob/master/docs/keywords.md) and [$data reference](https://github.com/json-schema-org/json-schema-spec/issues/51); _Only specification-compliant when [strict mode](https://ajv.js.org/strict-mode.html) is **disabled.**_"
+      notes: "for Node.js and browsers - supports [user-defined keywords](https://github.com/ajv-validator/ajv/blob/master/docs/keywords.md) and [$data reference](https://github.com/json-schema-org/json-schema-spec/issues/51)"
       date-draft: [2019-09, 2020-12]
       draft: [7, 6, 4]
       license: MIT
+      compliance:
+        config:
+          docs: https://ajv.js.org/strict-mode.html
+          instructions: "set option `strict: false`"
       last-updated: "2022-08-31"
     - name: "@cfworker/json-schema"
       url: https://github.com/cfworker/cfworker/blob/master/packages/json-schema/README.md
@@ -249,6 +262,10 @@
       date-draft: [2020-12, 2019-09]
       draft: [7, 6]
       license: "Apache License 2.0"
+      compliance:
+        config:
+          docs: https://opis.io/json-schema/2.x/php-loader.html#parser-options
+          instructions: 'set several options to their "vanilla" values'
       last-updated: "2022-08-31"
     - name: Swaggest Json Schema
       url: https://github.com/swaggest/php-json-schema
@@ -386,6 +403,10 @@
       url: 'https://www.npmjs.com/package/ajv-cli'
       date-draft: [2020-12, 2019-09]
       draft: [7, 6, 4]
+      compliance:
+        config:
+          docs: https://github.com/ajv-validator/ajv-cli#ajv-options
+          instructions: "pass `--strict=false`"
       last-updated: "2022-08-31"
     - name: yajsv
       license: MIT

implementations.md

@@ -57,6 +57,17 @@ Validators
             {% endif %}
           </li>
 
+        {% if implementation.compliance %}
+          <li><em>Compliance:</em>
+          {% if implementation.compliance.config.docs %}
+            This implementation <a href="{{ implementation.compliance.config.docs }}">documents</a> that you must
+          {% endif %}
+          {% if implementation.compliance.config.instructions %}
+            <strong>{{ implementation.compliance.config.instructions | markdownify | remove: '<p>' | remove: '</p>' }}</strong> to produce specification-compliant behavior.
+          </li>
+          {% endif %}
+        {% endif %}
+
         {% if implementation.license %}
           <li><em>License:</em>
             {{ implementation.license | join: ", " }}