Review JSON Schema

[septs]

https://github.com/tc39/dataset/blob/master/schema/individual.json CC @codehag

Planning:

1. Freeze individual proposal schema
2. Provide an GitHub Action on tc39/template-for-proposals (see TC39 Proposal Linter (GitHub Action) #3)
   Validate /metadata.json (filename TBD)

---

Pre-discussion: JSCIG/dataset#6

[ljharb]

It seems a bit heavy handed, hard to scale, and impractical to install on archived proposal repos to have a mandated json file in each repo (the template isn’t even mandated). Why wouldn’t this info go in the main proposals repo? We could offer an action in the template to help proposal repos pull info from the main list rather than making the proposal repos the source of truth?

[codehag]

I think the direction of pulling from the tc39/proposals repo is a good one. We cannot guarantee that individual proposals repositories will be always up to date, but, as mentioned elsewhere, the tc39/proposals repo generally is. So, +1 to what ljharb suggested here. The hierarchy should be proposals -> individual proposal for information like stage, last notes, tests. Proposals themselves should be seen as slower moving but more comprehensive, so if for example, the stage differs for a given proposal between the tc39/proposals repo, and the proposal itself -- then in most cases the tc39/proposals repo is the correct one. Information that is too detailed for the tc39/proposals repo is the responsibility of the individual proposal. This way we have clear responsibilities, with a bit of duplication which needs to be kept up to date.

This also gives us more flexibility for archived proposals. They may, or may not, have the same format as more modern proposals, and this is ok. They may or may not be automated, but if there is an inconsistency we generally know where to look for which type of info, and it is easier to correct. The ultimate fall back is talking to individual champions responsible but usually this isn't a huge deal. Consistency may be a side effect, the real goal here is making things machine readable, with the benefit of consistency (and hopefully, less labour).

I am a bit hesitant on freezing the schema right now. We should first ensure that this works for what it is intended before freezing it and maintaining it. This is a detail. Once we have a few consumers and are happy with how everything works, we can look into freezing the data structure and maintaining it.

[codehag]

I reviewed the schema you wrote, looks really good. Very happy with it so far! Thank you for doing the work.

Here are a few comments. I added everything inline, as github is inconsistent with display of the links:

https://github.com/tc39/dataset/blob/master/schema/individual.json#L121

    "implementations": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "Babel",
          "ChakraCore",
          "Chrome",
          "Edge",
          "Engine262",
          "Firefox",
          "GraalJS",
          "Hermes",
          "JavaScriptCore",
          "Nashorn",
          "Node",
          "QuickJS",
          "Safari",
          "SpiderMonkey",
          "TypeScript",
          "v8"
        ]
      },

we might want to have specific version numbers for this, but that may also overlap with caniuse. Mozilla maintains a list of this as well, we might be able to share data with them: https://github.com/mdn/browser-compat-data -- this may be more efficient and effective in the long run.

https://github.com/tc39/dataset/blob/master/schema/individual.json#L153

    "edition": {
      "type": "number",
      "minimum": 2015,
      "maximum": 2999,
      "description": "available edition of ECMAScript (stage 4 only)"
    }

this will only be valid for recent proposals, unless we retcon how we think of things like es5. I am not against the idea, but it sticks out. Is there another way to specify this?

dataset/schema/individual.json

Line 161 in f6ad2bb

"required": ["tags", "name", "stage", "authors", "champions"]

  "required": ["tags", "name", "stage", "authors", "champions"]

Ah, this looks quite good (in the linter issue I was expecting to see more). The one that might be not be required here, is champions for stage 0.

https://github.com/tc39/dataset/blob/master/schema/individual.json#L46

      "description": "List of Authour"

Nit: Authour should be Authors

dataset/schema/individual.json

Line 110 in f6ad2bb

"description": "Provide example code of tc39.es show code"

      "description": "Provide example code of tc39.es show code"

Nit: of should be for here.