feat(schemas): separate public from internal schema

[caugner]

Summary

Adds a public schema for data.json, separate from the internal browser/compat file schemas.

Also refines the schema descriptions based on Daniel's feedback.

Test results and supporting details

There are two changes that are strictly speaking breaking:

1. The CompatStatement.source_file property is now required.
2. The BrowserStatement.upstream property is narrowed down to UpstreamBrowserName, a subset of BrowserName.

Before

/* This file is a part of @mdn/browser-compat-data
 * See LICENSE file for more information. */

/**
* This file was automatically generated by json-schema-to-typescript.
* DO NOT MODIFY IT BY HAND. Instead, modify the source schema files in
* schemas/*, and run "npm run gentypes" to regenerate this file.
*/

/**
 * The names of the known browsers.
 */
export type BrowserName = "bun" | "chrome" | "chrome_android" | "deno" | "edge" | "firefox" | "firefox_android" | "ie" | "nodejs" | "oculus" | "opera" | "opera_android" | "safari" | "safari_ios" | "samsunginternet_android" | "webview_android" | "webview_ios";

export type VersionValue = string | false;

/**
 * This interface was referenced by `BrowserDataFile`'s JSON-Schema
 * via the `definition` "browsers".
 */
export type Browsers = Record<BrowserName, BrowserStatement>;
/**
 * This interface was referenced by `BrowserDataFile`'s JSON-Schema
 * via the `definition` "browser_type".
 */
export type BrowserType = "desktop" | "mobile" | "xr" | "server";
/**
 * This interface was referenced by `BrowserDataFile`'s JSON-Schema
 * via the `definition` "browser_engine".
 */
export type BrowserEngine = "Blink" | "EdgeHTML" | "Gecko" | "Presto" | "Trident" | "WebKit" | "V8";
/**
 * This interface was referenced by `BrowserDataFile`'s JSON-Schema
 * via the `definition` "browser_status".
 */
export type BrowserStatus = "retired" | "current" | "beta" | "nightly" | "esr" | "planned";


/**
 * This interface was referenced by `BrowserDataFile`'s JSON-Schema
 * via the `definition` "browser_statement".
 */
export interface BrowserStatement {
  /**
   * The browser brand name (e.g. Firefox, Firefox Android, Chrome, etc.).
   */
  name: string;
  /**
   * The platform the browser runs on (e.g. desktop, mobile, XR, or server engine).
   */
  type: BrowserType;
  /**
   * The upstream browser this browser derives from (e.g. Firefox Android is derived from Firefox, Edge is derived from Chrome).
   */
  upstream?: BrowserName;
  /**
   * The name of the browser's preview channel (e.g. 'Nightly' for Firefox or 'TP' for Safari).
   */
  preview_name?: string;
  /**
   * URL of the page where feature flags can be changed (e.g. 'about:config' for Firefox or 'chrome://flags' for Chrome).
   */
  pref_url?: string;
  /**
   * Whether the browser supports user-toggleable flags that enable or disable features.
   */
  accepts_flags: boolean;
  /**
   * Whether the browser supports extensions.
   */
  accepts_webextensions: boolean;
  /**
   * The known versions of this browser.
   */
  releases: {[version: string]: ReleaseStatement};
}
/**
 * This interface was referenced by `BrowserDataFile`'s JSON-Schema
 * via the `definition` "release_statement".
 */
export interface ReleaseStatement {
  /**
   * The date on which this version was released, formatted as `YYYY-MM-DD`.
   */
  release_date?: string;
  /**
   * A link to the release notes or changelog for a given release.
   */
  release_notes?: string;
  /**
   * A property indicating where in the lifetime cycle this release is in (e.g. current, retired, beta, nightly).
   */
  status: BrowserStatus;
  /**
   * Name of the browser's underlying engine.
   */
  engine?: BrowserEngine;
  /**
   * Version of the engine corresponding to the browser version.
   */
  engine_version?: string;
}


/**
 * This interface was referenced by `CompatDataFile`'s JSON-Schema definition
 * via the `patternProperty` "^(?!__compat)(?!webextensions)[a-zA-Z_0-9-$@]*$".
 *
 * This interface was referenced by `CompatDataFile`'s JSON-Schema
 * via the `definition` "identifier".
 */
export type Identifier = {[key: string]: Identifier} & {__compat?: CompatStatement};
/**
 * The data for the support of each browser, containing a `support_statement` object for each browser identifier with information about versions, prefixes, or alternate names, as well as notes.
 */
export type SupportBlock = Partial<Record<BrowserName, SupportStatement>>;
/**
 * This interface was referenced by `CompatDataFile`'s JSON-Schema
 * via the `definition` "support_statement".
 */
export type SupportStatement =
  | SimpleSupportStatement
  | [SimpleSupportStatement, SimpleSupportStatement, ...SimpleSupportStatement[]];


/**
 * This interface was referenced by `CompatDataFile`'s JSON-Schema definition
 * via the `patternProperty` "^__compat$".
 *
 * This interface was referenced by `CompatDataFile`'s JSON-Schema
 * via the `definition` "compat_statement".
 */
export interface CompatStatement {
  /**
   * A string containing a human-readable description of the feature.
   */
  description?: string;
  /**
   * A URL that points to an MDN reference page documenting the feature. The URL should be language-agnostic.
   */
  mdn_url?: string;
  /**
   * An optional URL or array of URLs, each of which is for a specific part of a specification in which this feature is defined. Each URL must contain a fragment identifier.
   */
  spec_url?: string | [string, string, ...string[]];
  /**
   * An optional array of strings allowing to assign tags to the feature.
   *
   * @minItems 1
   */
  tags?: [string, ...string[]];
  /**
   * The path to the file that defines this feature in browser-compat-data, relative to the repository root. Useful for guiding potential contributors towards the correct file to edit. This is automatically generated at build time and should never manually be specified.
   */
  source_file?: string;
  support: SupportBlock;
  status?: StatusBlock;
}
/**
 * An object containing information about the stability of the feature.
 */
export interface StatusBlock {
  /**
   * @deprecated
   * (This property is deprecated. Prefer using more well-defined stability calculations, such as Baseline, instead.) A boolean value. Usually, this value is true for single-implementer features and false for multiple-implementer features or single-implementer features that are not expected to change.
   */
  experimental: boolean;
  /**
   * A boolean value indicating whether the feature is part of an active specification or specification process.
   */
  standard_track: boolean;
  /**
   * A boolean value that indicates whether the feature is no longer recommended. It might be removed in the future or might only be kept for compatibility purposes. Avoid using this functionality.
   */
  deprecated: boolean;
}
/**
 * This interface was referenced by `CompatDataFile`'s JSON-Schema
 * via the `definition` "simple_support_statement".
 */
export interface SimpleSupportStatement {
  /**
   * A string (indicating which browser version added this feature), or the value false (indicating the feature is not supported).
   */
  version_added: VersionValue;
  /**
   * A string, indicating which browser version removed this feature.
   */
  version_removed?: string;
  /**
   * A string, indicating the last browser version that supported this feature. This is automatically generated.
   */
  version_last?: string;
  /**
   * A prefix to add to the sub-feature name (defaults to empty string). If applicable, leading and trailing '-' must be included.
   */
  prefix?: string;
  /**
   * An alternative name for the feature, for cases where a feature is implemented under an entirely different name and not just prefixed.
   */
  alternative_name?: string;
  /**
   * An optional array of objects describing flags that must be configured for this browser to support this feature.
   *
   * @minItems 1
   */
  flags?: [FlagStatement, ...FlagStatement[]];
  /**
   * An optional changeset/commit URL for the revision which implemented the feature in the source code, or the URL to the bug tracking the implementation, for the associated browser.
   */
  impl_url?: string | [string, string, ...string[]];
  /**
   * A boolean value indicating whether or not the implementation of the sub-feature deviates from the specification in a way that may cause compatibility problems. It defaults to false (no interoperability problems expected). If set to true, it is recommended that you add a note explaining how it diverges from the standard (such as that it implements an old version of the standard, for example).
   */
  partial_implementation?: true;
  /**
   * A string or array of strings containing additional information.
   */
  notes?: string | [string, string, ...string[]];
}
/**
 * This interface was referenced by `CompatDataFile`'s JSON-Schema
 * via the `definition` "flag_statement".
 */
export interface FlagStatement {
  /**
   * An enum that indicates the flag type.
   */
  type: "preference" | "runtime_flag";
  /**
   * A string giving the name of the flag or preference that must be configured.
   */
  name: string;
  /**
   * A string giving the value which the specified flag must be set to for this feature to work.
   */
  value_to_set?: string;
}


export interface MetaBlock {
  version: string;
  timestamp: string;
}

export interface CompatData {
  /**
   * Contains metadata for the current BCD information, such as the BCD version.
   */
  __meta: MetaBlock;

  /**
   * Contains data for each [Web API](https://developer.mozilla.org/docs/Web/API) interface.
   */
  api: Identifier;

  /**
   * Contains data for each known and tracked browser/engine.
   */
  browsers: Browsers;

  /**
   * Contains data for [CSS](https://developer.mozilla.org/docs/Web/CSS) properties, selectors, and at-rules.
   */
  css: Identifier;

  /**
   * Contains data for [HTML](https://developer.mozilla.org/docs/Web/HTML) elements, attributes, and global attributes.
   */
  html: Identifier;

  /**
   * Contains data for [HTTP](https://developer.mozilla.org/docs/Web/HTTP) headers, statuses, and methods.
   */
  http: Identifier;

  /**
   * Contains data for [JavaScript](https://developer.mozilla.org/docs/Web/JavaScript) built-in Objects, statement, operators, and other ECMAScript language features.
   */
  javascript: Identifier;

  /**
   * Contains data for various manifests, such as the [Web Application Manifest](https://developer.mozilla.org/docs/Web/Progressive_web_apps/manifest).
   */
  manifests: Identifier;

  /**
   * Contains data for [MathML](https://developer.mozilla.org/docs/Web/MathML) elements, attributes, and global attributes.
   */
  mathml: Identifier;

  /**
   * Contains data for [Media types](https://developer.mozilla.org/docs/Web/HTTP/Guides/MIME_types).
   */
  mediatypes: Identifier;

  /**
   * Contains data for [SVG](https://developer.mozilla.org/docs/Web/SVG) elements, attributes, and global attributes.
   */
  svg: Identifier;

  /**
   * Contains data for [WebAssembly](https://developer.mozilla.org/docs/WebAssembly) features.
   */
  webassembly: Identifier;

  /**
   * Contains data for [WebDriver](https://developer.mozilla.org/docs/Web/WebDriver) commands.
   */
  webdriver: Identifier;

  /**
   * Contains data for [WebExtensions](https://developer.mozilla.org/Add-ons/WebExtensions) JavaScript APIs and manifest keys.
   */
  webextensions: Identifier;
}

After

/* This file is a part of @mdn/browser-compat-data
 * See LICENSE file for more information. */

/**
 * This file was automatically generated by json-schema-to-typescript.
 * DO NOT MODIFY IT BY HAND. Instead, modify the source schema files in
 * schemas/*, and run "npm run gentypes" to regenerate this file.
 */

export type Identifier = {__compat?: CompatStatement} & {[key: string]: Identifier};
/**
 * Data for each known and tracked browser/runtime.
 */
export type Browsers = Record<BrowserName, BrowserStatement>;
/**
 * Platform the browser runs on (e.g. desktop, mobile, XR, or server engine).
 */
export type BrowserType = "desktop" | "mobile" | "xr" | "server";
/**
 * Browser engine.
 */
export type BrowserEngine = "Blink" | "EdgeHTML" | "Gecko" | "Presto" | "Trident" | "WebKit" | "V8";
/**
 * Browser key (e.g. 'firefox', 'chrome_android', or 'webview_ios').
 */
export type BrowserName =
  | "bun"
  | "chrome"
  | "chrome_android"
  | "deno"
  | "edge"
  | "firefox"
  | "firefox_android"
  | "ie"
  | "nodejs"
  | "oculus"
  | "opera"
  | "opera_android"
  | "safari"
  | "safari_ios"
  | "samsunginternet_android"
  | "webview_android"
  | "webview_ios";
/**
 * Upstream browser key (e.g. 'firefox' or 'chrome_android').
 */
export type UpstreamBrowserName = "chrome" | "chrome_android" | "firefox" | "safari" | "safari_ios";
/**
 * Lifetime cycle status of a browser release (e.g. 'current', 'retired', 'beta', 'nightly').
 */
export type BrowserStatus = "retired" | "current" | "beta" | "nightly" | "esr" | "planned";
/**
 * A string (indicating which browser version added this feature), or the value false (indicating the feature is not supported).
 */
export type VersionValue = string | false;
export type SupportStatement =
  | SimpleSupportStatement
  | [SimpleSupportStatement, SimpleSupportStatement, ...SimpleSupportStatement[]];
/**
 * The data for the support of each browser, containing a `support_statement` object for each browser identifier with information about versions, prefixes, or alternate names, as well as notes.
 */
export type SupportBlock = Partial<Record<BrowserName, SupportStatement>>;

/**
 * Shape of the `data.json` file in published BCD releases
 */
export interface CompatData {
  __meta: MetaBlock;
  api: Identifier;
  browsers: Browsers;
  css: Identifier;
  html: Identifier;
  http: Identifier;
  javascript: Identifier;
  manifests: Identifier;
  mathml: Identifier;
  mediatypes: Identifier;
  svg: Identifier;
  webassembly: Identifier;
  webdriver: Identifier;
  webextensions: Identifier;
}
/**
 * Metadata of the present BCD data.
 */
export interface MetaBlock {
  version: string;
  timestamp: string;
}
export interface BrowserStatement {
  /**
   * Name of the browser (e.g. 'Firefox', 'Firefox Android', 'Chrome', etc.).
   */
  name: string;
  type: BrowserType;
  upstream?: UpstreamBrowserName;
  /**
   * Name of the browser's preview channel (e.g. 'Nightly' for Firefox or 'TP' for Safari).
   */
  preview_name?: string;
  /**
   * URL of the page where feature flags can be changed (e.g. 'about:config' for Firefox or 'chrome://flags' for Chrome).
   */
  pref_url?: string;
  /**
   * Whether the browser supports user-toggleable flags that enable or disable features.
   */
  accepts_flags: boolean;
  /**
   * Whether the browser supports extensions.
   */
  accepts_webextensions: boolean;
  /**
   * The known versions of this browser.
   */
  releases: Record<string, ReleaseStatement>;
}
export interface ReleaseStatement {
  /**
   * The date on which this version was released, formatted as `YYYY-MM-DD`.
   */
  release_date?: string;
  /**
   * A link to the release notes or changelog for a given release.
   */
  release_notes?: string;
  status: BrowserStatus;
  engine?: BrowserEngine;
  /**
   * Version of the engine corresponding to the browser version.
   */
  engine_version?: string;
}
export interface SimpleSupportStatement {
  version_added: VersionValue;
  /**
   * A string, indicating which browser version removed this feature.
   */
  version_removed?: string;
  /**
   * A string, indicating the last browser version that supported this feature. This is automatically generated.
   */
  version_last?: string;
  /**
   * A prefix to add to the sub-feature name (defaults to empty string). If applicable, leading and trailing '-' must be included.
   */
  prefix?: string;
  /**
   * An alternative name for the feature, for cases where a feature is implemented under an entirely different name and not just prefixed.
   */
  alternative_name?: string;
  /**
   * An optional array of objects describing flags that must be configured for this browser to support this feature.
   *
   * @minItems 1
   */
  flags?: [FlagStatement, ...FlagStatement[]];
  /**
   * An optional changeset/commit URL for the revision which implemented the feature in the source code, or the URL to the bug tracking the implementation, for the associated browser.
   */
  impl_url?: string | [string, string, ...string[]];
  /**
   * A boolean value indicating whether or not the implementation of the sub-feature deviates from the specification in a way that may cause compatibility problems. It defaults to false (no interoperability problems expected). If set to true, it is recommended that you add a note explaining how it diverges from the standard (such as that it implements an old version of the standard, for example).
   */
  partial_implementation?: true;
  /**
   * A string or array of strings containing additional information.
   */
  notes?: string | [string, string, ...string[]];
}
export interface FlagStatement {
  /**
   * An enum that indicates the flag type.
   */
  type: "preference" | "runtime_flag";
  /**
   * A string giving the name of the flag or preference that must be configured.
   */
  name: string;
  /**
   * A string giving the value which the specified flag must be set to for this feature to work.
   */
  value_to_set?: string;
}
/**
 * An object containing information about the stability of the feature.
 */
export interface StatusBlock {
  /**
   * @deprecated
   * (This property is deprecated. Prefer using more well-defined stability calculations, such as Baseline, instead.) A boolean value. Usually, this value is true for single-implementer features and false for multiple-implementer features or single-implementer features that are not expected to change.
   */
  experimental: boolean;
  /**
   * A boolean value indicating whether the feature is part of an active specification or specification process.
   */
  standard_track: boolean;
  /**
   * A boolean value that indicates whether the feature is no longer recommended. It might be removed in the future or might only be kept for compatibility purposes. Avoid using this functionality.
   */
  deprecated: boolean;
}
/**
 * A feature is described by an identifier containing the `__compat` property.
 *
 * In other words, identifiers without `__compat` aren't necessarily features, but help to nest the features properly.
 *
 * When an identifier has a `__compat` block, it represents its basic support, indicating that a minimal implementation of a functionality is included.
 *
 * What it represents exactly depends of the evolution of the feature over time, both in terms of specifications and of browser support.
 */
export interface CompatStatement {
  /**
   * Human-readable description of the feature.
   */
  description?: string;
  /**
   * Link to the MDN reference page documenting the feature.
   */
  mdn_url?: string;
  /**
   * An optional URL or array of URLs, each of which is for a specific part of a specification in which this feature is defined. Each URL must contain a fragment identifier.
   */
  spec_url?: string | [string, string, ...string[]];
  /**
   * An optional array of strings allowing to assign tags to the feature.
   *
   * @minItems 1
   */
  tags?: [string, ...string[]];
  /**
   * The path to the file that defines this feature in browser-compat-data, relative to the repository root. Useful for guiding potential contributors towards the correct file to edit. This is automatically generated at build time and should never manually be specified.
   */
  source_file: string;
  support: SupportBlock;
  status?: StatusBlock;
}

diff

diff --git a/before.d.ts b/after.d.ts
index fd09440..6c45e5b 100644
--- a/before.d.ts
+++ b/after.d.ts
@@ -8,8 +8,7 @@
  */
 
 /**
- * This interface was referenced by `BrowserDataFile`'s JSON-Schema
- * via the `definition` "browser_engine".
+ * Browser engine.
  */
 export type BrowserEngine =
   | "Blink"
@@ -20,7 +19,7 @@ export type BrowserEngine =
   | "WebKit"
   | "V8";
 /**
- * The names of the known browsers.
+ * Browser key (e.g. 'firefox', 'chrome_android', or 'webview_ios').
  */
 export type BrowserName =
   | "bun"
@@ -41,30 +40,19 @@ export type BrowserName =
   | "webview_android"
   | "webview_ios";
 /**
- * This interface was referenced by `BrowserDataFile`'s JSON-Schema
- * via the `definition` "browsers".
+ * Data for each known and tracked browser/runtime.
  */
 export type Browsers = Record<BrowserName, BrowserStatement>;
 
-/**
- * This interface was referenced by `BrowserDataFile`'s JSON-Schema
- * via the `definition` "browser_statement".
- */
 export interface BrowserStatement {
   /**
-   * The browser brand name (e.g. Firefox, Firefox Android, Chrome, etc.).
+   * Name of the browser (e.g. 'Firefox', 'Firefox Android', 'Chrome', etc.).
    */
   name: string;
-  /**
-   * The platform the browser runs on (e.g. desktop, mobile, XR, or server engine).
-   */
   type: BrowserType;
+  upstream?: UpstreamBrowserName;
   /**
-   * The upstream browser this browser derives from (e.g. Firefox Android is derived from Firefox, Edge is derived from Chrome).
-   */
-  upstream?: BrowserName;
-  /**
-   * The name of the browser's preview channel (e.g. 'Nightly' for Firefox or 'TP' for Safari).
+   * Name of the browser's preview channel (e.g. 'Nightly' for Firefox or 'TP' for Safari).
    */
   preview_name?: string;
   /**
@@ -82,11 +70,10 @@ export interface BrowserStatement {
   /**
    * The known versions of this browser.
    */
-  releases: { [version: string]: ReleaseStatement };
+  releases: Record<string, ReleaseStatement>;
 }
 /**
- * This interface was referenced by `BrowserDataFile`'s JSON-Schema
- * via the `definition` "browser_status".
+ * Lifetime cycle status of a browser release (e.g. 'current', 'retired', 'beta', 'nightly').
  */
 export type BrowserStatus =
   | "retired"
@@ -96,96 +83,45 @@ export type BrowserStatus =
   | "esr"
   | "planned";
 /**
- * This interface was referenced by `BrowserDataFile`'s JSON-Schema
- * via the `definition` "browser_type".
+ * Platform the browser runs on (e.g. desktop, mobile, XR, or server engine).
  */
 export type BrowserType = "desktop" | "mobile" | "xr" | "server";
 
+/**
+ * Shape of the `data.json` file in published BCD releases
+ */
 export interface CompatData {
-  /**
-   * Contains metadata for the current BCD information, such as the BCD version.
-   */
   __meta: MetaBlock;
-
-  /**
-   * Contains data for each [Web API](https://developer.mozilla.org/docs/Web/API) interface.
-   */
   api: Identifier;
-
-  /**
-   * Contains data for each known and tracked browser/engine.
-   */
   browsers: Browsers;
-
-  /**
-   * Contains data for [CSS](https://developer.mozilla.org/docs/Web/CSS) properties, selectors, and at-rules.
-   */
   css: Identifier;
-
-  /**
-   * Contains data for [HTML](https://developer.mozilla.org/docs/Web/HTML) elements, attributes, and global attributes.
-   */
   html: Identifier;
-
-  /**
-   * Contains data for [HTTP](https://developer.mozilla.org/docs/Web/HTTP) headers, statuses, and methods.
-   */
   http: Identifier;
-
-  /**
-   * Contains data for [JavaScript](https://developer.mozilla.org/docs/Web/JavaScript) built-in Objects, statement, operators, and other ECMAScript language features.
-   */
   javascript: Identifier;
-
-  /**
-   * Contains data for various manifests, such as the [Web Application Manifest](https://developer.mozilla.org/docs/Web/Progressive_web_apps/manifest).
-   */
   manifests: Identifier;
-
-  /**
-   * Contains data for [MathML](https://developer.mozilla.org/docs/Web/MathML) elements, attributes, and global attributes.
-   */
   mathml: Identifier;
-
-  /**
-   * Contains data for [Media types](https://developer.mozilla.org/docs/Web/HTTP/Guides/MIME_types).
-   */
   mediatypes: Identifier;
-
-  /**
-   * Contains data for [SVG](https://developer.mozilla.org/docs/Web/SVG) elements, attributes, and global attributes.
-   */
   svg: Identifier;
-
-  /**
-   * Contains data for [WebAssembly](https://developer.mozilla.org/docs/WebAssembly) features.
-   */
   webassembly: Identifier;
-
-  /**
-   * Contains data for [WebDriver](https://developer.mozilla.org/docs/Web/WebDriver) commands.
-   */
   webdriver: Identifier;
-
-  /**
-   * Contains data for [WebExtensions](https://developer.mozilla.org/Add-ons/WebExtensions) JavaScript APIs and manifest keys.
-   */
   webextensions: Identifier;
 }
 /**
- * This interface was referenced by `CompatDataFile`'s JSON-Schema definition
- * via the `patternProperty` "^__compat$".
+ * A feature is described by an identifier containing the `__compat` property.
+ *
+ * In other words, identifiers without `__compat` aren't necessarily features, but help to nest the features properly.
  *
- * This interface was referenced by `CompatDataFile`'s JSON-Schema
- * via the `definition` "compat_statement".
+ * When an identifier has a `__compat` block, it represents its basic support, indicating that a minimal implementation of a functionality is included.
+ *
+ * What it represents exactly depends of the evolution of the feature over time, both in terms of specifications and of browser support.
  */
 export interface CompatStatement {
   /**
-   * A string containing a human-readable description of the feature.
+   * Human-readable description of the feature.
    */
   description?: string;
   /**
-   * A URL that points to an MDN reference page documenting the feature. The URL should be language-agnostic.
+   * Link to the MDN reference page documenting the feature.
    */
   mdn_url?: string;
   /**
@@ -201,14 +137,10 @@ export interface CompatStatement {
   /**
    * The path to the file that defines this feature in browser-compat-data, relative to the repository root. Useful for guiding potential contributors towards the correct file to edit. This is automatically generated at build time and should never manually be specified.
    */
-  source_file?: string;
+  source_file: string;
   support: SupportBlock;
   status?: StatusBlock;
 }
-/**
- * This interface was referenced by `CompatDataFile`'s JSON-Schema
- * via the `definition` "flag_statement".
- */
 export interface FlagStatement {
   /**
    * An enum that indicates the flag type.
@@ -223,25 +155,18 @@ export interface FlagStatement {
    */
   value_to_set?: string;
 }
-/**
- * This interface was referenced by `CompatDataFile`'s JSON-Schema definition
- * via the `patternProperty` "^(?!__compat)(?!webextensions)[a-zA-Z_0-9-$@]*$".
- *
- * This interface was referenced by `CompatDataFile`'s JSON-Schema
- * via the `definition` "identifier".
- */
-export type Identifier = { [key: string]: Identifier } & {
-  __compat?: CompatStatement;
+
+export type Identifier = { __compat?: CompatStatement } & {
+  [key: string]: Identifier;
 };
 
+/**
+ * Metadata of the present BCD data.
+ */
 export interface MetaBlock {
   version: string;
   timestamp: string;
 }
-/**
- * This interface was referenced by `BrowserDataFile`'s JSON-Schema
- * via the `definition` "release_statement".
- */
 export interface ReleaseStatement {
   /**
    * The date on which this version was released, formatted as `YYYY-MM-DD`.
@@ -251,27 +176,14 @@ export interface ReleaseStatement {
    * A link to the release notes or changelog for a given release.
    */
   release_notes?: string;
-  /**
-   * A property indicating where in the lifetime cycle this release is in (e.g. current, retired, beta, nightly).
-   */
   status: BrowserStatus;
-  /**
-   * Name of the browser's underlying engine.
-   */
   engine?: BrowserEngine;
   /**
    * Version of the engine corresponding to the browser version.
    */
   engine_version?: string;
 }
-/**
- * This interface was referenced by `CompatDataFile`'s JSON-Schema
- * via the `definition` "simple_support_statement".
- */
 export interface SimpleSupportStatement {
-  /**
-   * A string (indicating which browser version added this feature), or the value false (indicating the feature is not supported).
-   */
   version_added: VersionValue;
   /**
    * A string, indicating which browser version removed this feature.
@@ -330,10 +242,6 @@ export interface StatusBlock {
  * The data for the support of each browser, containing a `support_statement` object for each browser identifier with information about versions, prefixes, or alternate names, as well as notes.
  */
 export type SupportBlock = Partial<Record<BrowserName, SupportStatement>>;
-/**
- * This interface was referenced by `CompatDataFile`'s JSON-Schema
- * via the `definition` "support_statement".
- */
 export type SupportStatement =
   | SimpleSupportStatement
   | [
@@ -341,5 +249,16 @@ export type SupportStatement =
       SimpleSupportStatement,
       ...SimpleSupportStatement[],
     ];
-
+/**
+ * Upstream browser key (e.g. 'firefox' or 'chrome_android').
+ */
+export type UpstreamBrowserName =
+  | "chrome"
+  | "chrome_android"
+  | "firefox"
+  | "safari"
+  | "safari_ios";
+/**
+ * A string (indicating which browser version added this feature), or the value false (indicating the feature is not supported).
+ */
 export type VersionValue = string | false;

Related issues

Fixes #29059.

[github-actions]

Tip: Review these changes grouped by change (recommended for most PRs), or grouped by feature (for large PRs).

[LeoMcA]

Nice! Looks ready to go from my side.

Tested breaking the types in multiple places (scripts/generate-types.js, types/index.d.ts and schemas/public.schema.json) and TS caught them all when running gentypes - very nice!

[caugner]

FYI @ddbeck Removing the example values from the type descriptions may have been technically correct, but it means the Typescript type declarations now longer have these. I fear this might be a regression in terms of developer experience, so I would suggest to revert this. How strongly do you feel about this?

[ddbeck]

@caugner yes, that's fine. You can add examples back to the descriptions if that has a real benefit to developers. 👍

[caugner]

@caugner yes, that's fine. You can add examples back to the descriptions if that has a real benefit to developers. 👍

Done via 21ec227: Realized we can inject the examples into the descriptions at build time, so there's no risk of the descriptions/examples getting out of sync. 👍

Also noticed a duplicate banner, remoed via 5b92e5f.

@LeoMcA Can you please take another look at these latest code changes? 🙏