Add an internal-only "annotations" field

[ddbeck]

What would you like to see added to BCD?

This is a proposal for a new, internal-only tagging field to help tools and contributors make sense of the data while reviewing and editing it.

I'm suggesting an annotations field that could be used in __compat and status objects and simple support statements. It would accept an array of (enumerated) strings. It would not be a free-form notes field. Instead, we'd have a file (or a lint script) declare which annotations are permitted and their meaning. At build time, these annotations would be stripped from the data.

Here are some use-cases:

Provenance

We could use this field to mark the origin of a piece of data. For example, when the collector runs and creates a new support statement, it could leave a breadcrumb that it produced that value (e.g., that it was not manually introduced).

{
  "version_added": "131",
  "annotations": [
    "provenance:collector"
  ]
}

Meanwhile, a human contributor could mark a new data point (such a behaviorial feature) as being hand-written:

{
  "version_added": "131",
  "annotations": [
    "provenance:authored"
  ]
}

In the course of other investigations, we might note when something was originally migrated from the wiki but was later confirmed:

{
  "version_added": "1",
  "annotations": [
    "provenance:wiki",
    "confirmed:collector"
  ]
}

{
  "version_added": "16",
  "annotations": [
    "provenance:authored",
    "confirmed:manual-test"
  ]
}

FIXME comments

Suppose we discovered some issue with data, but had not been able to resolve it yet. We could mark that data, setting ourselves up for a burndown of data that needs investigation. To ensure that the flags are useful, we could require an issue URL:

{
  "version_added": "4",
  "annotations": [
    "fixme:https://github.com/mdn/browser-compat-data/issue/00000"
  ]
}

How impactful do you think this enhancement will be?

I think it would help us mark up data to make it easier for our future selves to understand what we've done, without doing heavier and riskier alternatives, such as switching formats (e.g., JSONC, JSON5, YAML) and allowing traditional code comments.

Do you have anything more you want to share?

No response

[ddbeck]

This would be an alternative to #9223.

[ddbeck]

On the BCD call today, we discussed this tangential to a data PR, where we had some uncertainty about the data. I mentioned this proposal as a way to mark data that's uncertain.

The discussion and reading over this revealed one issue: "annotations" is a bit long and doesn't obviously mark itself as an internal field. @caugner suggested something like "_notes" instead, both to be shorter and to indicate the internal-ness of the field. In the distant past, there have been suggestions to use $ as an internal marker, so something like $notes$ could do as well.

There were also questions about this being a schema change that might impact consumers. Since there's a separate build step in BCD, it's not clear to me that this is required, though we might need something like an internal schema, then a public schema that removes the internal-only fields. I don't think this would be terribly difficult, but it would be a new bit of indirection within the repo.

cc: @caugner, @Elchi3

[caugner]

Given that "annotations" is a bit long, and "notes" is already taken, how about repurposing the "tags" field:

1. Move the web-features tags into a dedicated feature field,
2. Start reusing the tags field for internal annotations, and
3. Introduce a tags field on support statements.

As for prefixes, here are some potentially useful ones that come to mind:

Key	Value	Feature	Support
provenance	<'authored'|'wiki'>	-	✅
fixme	<task or url to issue/comment>	✅	✅
confirmed	<'collector'|'manual-test'>	✅	-
collector	<'yes'|'no'>	✅	-
wpt-url	<url to WPT query>	✅	-
webcompat-url	<url to webcompat issue>	✅	-
same-as	<other BCD key>	✅	-
inherits	<'yes'>	-	✅
deprecation	<reason>	✅	-