Starting point

Given that some tools already support reading and writing the custom-elements.json format, should we take that as a starting point?

On the other hand, @octref has suggested starting from the VS Code Custom Data Format. Whether the format should be based on one IDEs format is a great question to answer.

[daKmoR]

I would start “small” and go for it… and then add more stuff step by step

For all use cases, I worked on (documentation, api playground, catalog) the following was good enough. So I would consider it a good starting point.

one adjustment I might see is to adjust type to typeHint or so as discussed in https://github.com/webcomponents/custom-elements-json/issues/6#issuecomment-546749135

{
  "version": 2,
  "tags": [
    {
      "name": "demo-wc-card",
      "description": "This is a container looking like a card with a back and front side you can switch",
      "attributes": [
        {
          "name": "header",
          "type": "String",
          "description": "Shown at the top of the card",
          "default": "Your Message",
          "required": true
        }
      ],
      "properties": [
        {
          "name": "header",
          "type": "String",
          "attribute": "header",
          "description": "Shown at the top of the card",
          "default": "Your Message",
          "required": true
        }
      ],
      "events": [
        {
          "name": "side-changed",
          "description": "Fires whenever it switches between front/back"
        }
      ],
      "slots": [
        {
          "name": "",
          "description": "Content inside the card gets displayed on the front page"
        }
      ],
      "cssProperties": [
        {
          "name": "--demo-wc-card-front-color",
          "description": "Font color for the front",
          "type": "Color"
        },
      ]
    }
  ]
}

[bahrus]

This is probably the schema