Self reporting tooling schema and processes definition

projects/tooling-self-identification/identification.schema.json

@@ -0,0 +1,293 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.json-schema.org/ecosystem/identification-v-0.0.1",
+  "title": "Tooling Project Self Identification Document",
+  "$comment": "Decided not to use JSON-LD and Schema.org concepts, as this complicates things without a clear benefit for our use case.",
+  "description": "This is a schema which represents a self reporting document published by a JSON Schema tooling creator, maintainer, or vendor.",
+  "$defs": {
+    "persons": {
+      "type": "array",
+      "uniqueItems": "true",
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "github"
+        ],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "github": {
+            "type": "string"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "description": "Identifies the exact version of the schema and self reporting data structure to which the file intends to conform",
+      "type": "string",
+      "pattern": "https://schemas.json-schema.org/ecosystem/identification-v-\\d\\.\\d\\.\\d"
+    },
+    "name": {
+      "description": "The name of the project",
+      "type": "string"
+    },
+    "description": {
+      "description": "A brief description of the project",
+      "type": "string"
+    },
+    "toolingType": {
+      "description": "The categories of tooling for the project",
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "description": "One of the categories of tooling of the project",
+        "type": "string",
+        "enum": [
+          "validator",
+          "hyper-schema",
+          "benchmarks",
+          "documentation",
+          "LDO-utility",
+          "code-to-schema",
+          "data-to-schema",
+          "model-to-schema",
+          "schema-to-types",
+          "schema-to-code",
+          "schema-to-web-UI",
+          "schema-to-data",
+          "util-general-processing",
+          "util-schema-to-schema",
+          "util-draft-migration",
+          "util-format-conversion",
+          "util-testing",
+          "editor",
+          "editor-plugins",
+          "schema-to-documentation",
+          "schema-repository",
+          "linter",
+          "linter-plugins"
+        ]
+      }
+    },
+    "languages": {
+      "description": "The languages the tool supports or can be used in or with",
+      "type": "array",
+      "items": {
+        "description": "Individual language name, from the list unless not included.",
+        "type": "string",
+        "anyOf": [
+          {
+            "enum": [
+              [
+                "Common Lisp",
+                "Rust",
+                "Elm",
+                ".NET",
+                "PHP",
+                "Clojure",
+                "Python",
+                "XSD",
+                "Scala",
+                "Orderly",
+                "Kotlin",
+                "Elixir",
+                "RAML",
+                "Erlang",
+                "Java",
+                "Lua/LuaJIT",
+                "OpenAPI",
+                "Perl",
+                "TypeScript",
+                "Ruby",
+                "Objective-C",
+                "Swift",
+                "C#",
+                "Go",
+                "C++",
+                "JavaScript"
+              ]
+            ]
+          },
+          {
+            "description": "A string value not yet included in the list of languages"
+          }
+        ]
+      }
+    },
+    "environment": {
+      "description": "The platforms or environments in which the tool or library is designed to operate. This field is optional and should be included when the tool or library is specific to a certain platform or environment.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "anyOf": [
+          {
+            "enum": [
+              "Web (Online)",
+              "GitHub Actions",
+              "Command Line",
+              "COM/ActiveX"
+            ]
+          },
+          {
+            "description": "A string value not yet included in the list of envrionments"
+          }
+        ]
+      }
+    },
+    "dependsOnValidators": {
+      "description": "Documents if the tool is the primary validator provider or depends on another tool",
+      "type": "array",
+      "items": {
+        "description": "The names of the tooling that this tooling depends upon",
+        "type": "string"
+      }
+    },
+    "creators": {
+      "description": "The creators or authors of the project",
+      "$ref": "#/$defs/persons"
+    },
+    "maintainers": {
+      "description": "The maintainers of the project",
+      "$ref": "#/$defs/persons"
+    },
+    "license": {
+      "description": "The license under which the project is distributed. SPDX expressions or a URL.",
+      "$comment": "Schemastore package.json schema uses enum to assist in auto complete. Could be worth doing the same.",
+      "type": "string"
+    },
+    "projectType": {
+      "description": "The type of project, classified by Nadia Eghbal in Working in Public - https://project-types.github.io",
+      "type": "string",
+      "enum": [
+        "toy",
+        "club",
+        "stadium",
+        "federation"
+      ]
+    },
+    "repositoryURL": {
+      "type": "string",
+      "description": "The URL of the project's repository"
+    },
+    "repositoryStatus": {
+      "description": "The status of the project's repository, defined at https://www.repostatus.org",
+      "type": "string",
+      "enum": [
+        "concpet",
+        "WIP",
+        "suspended",
+        "abandoned",
+        "active",
+        "inactive",
+        "unsupported",
+        "moved"
+      ]
+    },
+    "homepageURL": {
+      "description": "The URL of the project's homepage",
+      "type": "string"
+    },
+    "documentation": {
+      "$comment": "This is reserved for future use",
+      "type": "object"
+    },
+    "supportedDialects": {
+      "description": "The declared supported dialects of JSON Schema. This includes draft version identifiers.",
+      "type": "object",
+      "properties": {
+        "draft": {
+          "description": "An array of dialects of JSON Schema.",
+          "type": "array",
+          "items": {
+            "enum": [
+              1,
+              2,
+              3,
+              4,
+              5,
+              6,
+              7,
+              "2019-09",
+              "2020-12"
+            ]
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "bowtie": {
+      "description": "Information related to compliance testing by Bowtie - https://bowtie.report - Presence of this property implies the tool is being tested in Bowtie",
+      "type": "object",
+      "properties": {
+        "identifier": {
+          "description": "The identifier used for the tool in Bowtie, including the language.",
+          "examples": [
+            "dotnet-jsonschema-net",
+            "js-ajv"
+          ]
+        }
+      },
+      "required": [
+        "identifier"
+      ],
+      "additionalProperties": false
+    },
+    "toolingListingNotes": {
+      "description": "Notes about the tooling which will appear in the tooling listing on the website.",
+      "type": "string"
+    },
+    "compliance": {
+      "description": "Details on what must be done to make the implementation the most compliant that it can be. This is displayed on the website with the tooling details",
+      "type": "object",
+      "properties": {
+        "config": {
+          "type": "object",
+          "properties": {
+            "docs": {
+              "description": "A URL which links to the documentation which explains how to follow the given instructions.",
+              "type": "string"
+            },
+            "instructions": {
+              "description": "Instructions on how to make the implementation the most compliant.",
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "landscape": {
+      "description": "Additional informatin that should be used when generating the JSON Schema landscape diagram - https://github.com/json-schema-org/landscape",
+      "type": "object",
+      "properties": {
+        "logo": {
+          "description": "The filename of the logo to use for the JSON Schema landscape diagram - Must be included in the landscape repo under the logos directory, and in SVG format.",
+          "type": "string"
+        },
+        "optOut": {
+          "description": "Set this value to a boolean `true` value if you do not wish to be included in the JSON Schema Landscape. If you do, we would like to hear why.",
+          "type": "boolean",
+          "default": false
+        }
+      }
+    },
+    "lastUpdated": {
+      "description": "A date in the format of YYYY-MM-DD which repersents when the document was last updated.",
+      "type": "string",
+      "regex": "^\\d{4}\\-(0[1-9]|1[012])\\-(0[1-9]|[12][0-9]|3[01])$"
+    }
+  },
+  "required": [
+    "name",
+    "description",
+    "repositoryURL",
+    "toolingType",
+    "lastUpdated"
+  ],
+  "additionalProperties": false
+}

projects/tooling-self-identification/readme.md

@@ -0,0 +1,28 @@
+# Self Identification of Open Source JSON Schema Tooling
+
+JSON Schema has a vast ecosystem. We have documented a fraction of the existing tools out there for JSON Schema.
+
+This project aims to enable tooling authors and maintainers to detail their tools existance and additional informaiton to be listed on the JSON Schema website and Landscape diagram.
+
+The approach is to define a data structure for a file which is located in their own repo, which will then be located and extracted into a single file within this repository. Other repositories such as the website and landscape repositories, will then copy and transform the data as required. The data may be used to augment or totally replace the data they hold, if any.
+
+## Just Open Source for now
+
+This project only aims to capture the open source tooling, and does not include detailing or tracking of tools which are not open source.
+
+There may be further projects which aim to collate and combine data collected from other locations (such as this project), and primary data (such as information deposited into the website or later this repository in relation to close source tools).
+
+## How do I self identify my tool?
+
+We (will) have automation that looks for data daily. It will look for data in GitHub repositories which meet the following conditions:
+
+- Repository has the Topic `json-schema` assigned
+- Has a file called `.json-schema-identification.json` in the project's root
+- The JSON file validates successfully against the version of the self identification JSON Schema it declares
+
+## Why should I include this file in my tooling repository?
+
+If you define this file in your tooling repository, you will:
+- Be able to update your listing on the JSON Schema website's tooling page
+- Have your tool listing show it's project status and be filterable based on the project status
+- Have your tool shown in the JSON Schema Landscape diagram (unless you opt out)