Add support for custom data

[JanMiksovsky]

Salesforce is quite interested in capitalizing on a manifest like this for a range of projects. I believe the proposed state of schema.ts already covers the majority of Salesforce's requirements. The remaining requirements are rather proprietary, and could be addressed with general-purpose mechanism for including custom data in a manifest.

This could be achieved by:

1. Adding a standard, unrestricted custom key to the top-level schema.
2. Recommending a strategy for component authors or tool vendors to further subdivide that custom key. Example: an organization adding custom data should do so inside a key containing a relevant domain name they own.
3. Encouraging tools to either ignore custom keys they don't understand, or to perform generic processing of anything they find there. Type-checkers could potentially ignore all that data. A doc tool could either skip the custom data, or format it as a pretty-printed JSON block or table as supplementary documentation.

Example: Using some hypothetical custom data values taken from Salesforce's own internal requirements, a Salesforce component might include the following in its manifest:

{
  "custom": {
    "salesforce.com": {
      "apiVersion": "53", /* Salesforce platform API version targeted by this component */
      "formFactor": "mobile", /* Component is designed primarily for mobile use */
      "capabilities": [ /* In which product environments is the component capable of being used? */
        "dashboard",
        "communities"
      ]
    }
  }
}

Something like this would minimize the impact on the schema design, give component creators a way to include component metadata in a single place, and increase the chance that a tool created by one group could be used by a different group without choking on unexpected custom data. This would also provide a means of trying out new ideas for schema fields before standardizing on them.

[thepassle]

Just curious, but why not just have a separate salesforce.json file for these custom properties? Tools could easily pick it up and combine it with the custom elements manifest. I'm not entirely convinced having a kitchen sink custom property would be worth it just for the fact that users only have to add metadata in a single place.

This would also provide a means of trying out new ideas for schema fields before standardizing on them.

This feels like things could become messy pretty quickly 😅 Tools would first have to implement them under the custom property, and if it does get standardized, it would have to be implemented in the actual schema in a different place, im not sure if that would be the most efficient way to go about trying out new fields.

[JanMiksovsky]

Just curious, but why not just have a separate salesforce.json file for these custom properties?

I think the primary reason for doing this is because tools that work with a manifest could relatively easily be extend to do something reasonable with custom metadata:

1. Tools that generate a manifest: We expect to see tools that look at jsDoc annotations (say) in component source files and use those to generate a manifest based on what they find. jsDoc plugins let people declare custom tags, which is to say custom metadata. A jsDoc-to-manifest tool could output such custom metadata in the custom key. That saves each company with custom metadata from having to write its own jsDoc-to-manifest tool that largely replicates what the standard tool does.
2. Tools that read a manifest: As noted above, a tool that generates docs from a manifest could perform some baseline processing of custom data. Again, that saves companies with custom metadata from having to write custom tooling if that baseline processing is acceptable.

Tools would first have to implement them under the custom property, and if it does get standardized, it would have to be implemented in the actual schema in a different place,

The proposal here is to support the things that start out custom, then become ad hoc standards, then become real standards.

Consider the question of whether the manifest should cover demos. It's already a little unclear exactly what level of support for demos is necessary: e.g., should we let a component define multiple demos? Let's say for manifest v1 we decide that, no, a component can only define a single demo. A web component catalog comes along and wants to support multiple demos. They define a convention of their own for that, and tell people: "If you want to define multiple demos, add this custom key to your manifest". If that catches on, eventually that provides evidence that the feature should get standardized. It's given a standard key, and over time people switch to using the standard key.

I think there will be other situations like this where we will be glad to have an escape hatch. It will make it easier to get agreement on a v1 schema if features without broad support can be deferred to custom metadata.

[steel]

1. We expect to see tools that look at jsDoc annotations (say) in component source files and use those to generate a manifest based on what they find

This is exactly what we are doing here: https://github.com/polleverywhere/custom-element-analyzer We register these tags and parse the js files using jsdoc-api and output the formatted json.

[liamdebeasi]

The Stencil Team at Ionic likes option 3 in the initial proposal as it gives developers the most flexibility. If there is a popular custom key that we want to standardize on, it will be easy to do so as the key already exists, and tools would just need to be updated to recognize that key. One thing is that developers would have to be careful to make sure their custom keys do not collide with standardized keys, but that seems like a minor issue given the benefits of this feature.

[hsablonniere]

I don't have a strong preference for any of 1, 2 or 3. We've been listing a few custom stuffs in our components' JSDoc so we could see them in our Storybook:

• default display
• source link on (GitHub)
• image list

I would also really like to list some dependencies (images, npm...) so any user would know:

• component X uses images foo.svg, bar.svg...
• component Y uses 3rd party npm packages leaflet and chart.js

We've been maintaining a few of this ideas manually, but I would love to try to create CEM analyzer plugin that could add custom field to the CEM using custom JSDoc tags or analysis.

[hsablonniere]

I share the concern about this manifest becoming a mess but in my use cases, it makes sense to rely on the existing analyzer to extract the custom info. It would also make sense to extract the custom info and from the same file to use them in the same place in Storybook for example.

[hsablonniere]

Thinking about OpenAPI spec, they allow for extensions with a X- prefix. I'm not saying it's perfect but it's an option.

Look at this doc https://swagger.io/specification/ under "Specification Extensions".