Document a public API and SemVer policy

README.md

@@ -30,39 +30,102 @@ bcd.css.properties.background;
 // returns a compat data object (see schema)
 ```
 
-## Repository contents
+## Package contents
 
-There's a top-level directory for each broad area covered: for example, "http",
-"javascript", "webextensions". Inside each of these directories is one or more
-JSON file containing the compatibility data.
+The `@mdn/browser-compat-data` package contains a tree of objects, with support and browser data objects at their leaves. There are over 12,000 features in the dataset; this documentation highlights significant portions, but many others exist at various levels of the tree.
 
-- [api/](https://github.com/mdn/browser-compat-data/tree/master/api) contains data for each [Web API](https://developer.mozilla.org/en-US/docs/Web/API) interface.
+The definitive description of the format used to represent individual features and browsers is the [schema definitions](https://github.com/mdn/browser-compat-data/blob/master/schemas/).
 
-- [css/](https://github.com/mdn/browser-compat-data/tree/master/css) contains data for [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) properties, selectors, and at-rules.
+Apart from the explicitly documented objects below, feature-level support data may change at any time. See [_Semantic versioning policy_](#Semantic-versioning-policy) for details.
 
-- [html/](https://github.com/mdn/browser-compat-data/tree/master/html) contains data for
-  [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) elements, attributes, and global attributes.
+The package contains the following top-level objects:
 
-- [http/](https://github.com/mdn/browser-compat-data/tree/master/http) contains data for [HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP) headers, statuses, and methods.
+### [`api`](https://github.com/mdn/browser-compat-data/tree/master/api)
 
-- [javascript/](https://github.com/mdn/browser-compat-data/tree/master/javascript) contains data for [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) built-in Objects, statement, operators, and other ECMAScript language features.
+Data for [Web API](https://developer.mozilla.org/en-US/docs/Web/API) features.
 
-- [mathml/](https://github.com/mdn/browser-compat-data/tree/master/mathml) contains data for [MathML](https://developer.mozilla.org/docs/Web/MathML) elements, attributes, and global attributes.
+### [`browsers`](https://github.com/mdn/browser-compat-data/tree/master/browsers)
 
-- [svg/](https://github.com/mdn/browser-compat-data/tree/master/svg) contains data for [SVG](https://developer.mozilla.org/en-US/docs/Web/SVG) elements, attributes, and global attributes.
+Data for browser and engine releases. See the [browser schema](https://github.com/mdn/browser-compat-data/blob/master/schemas/browsers-schema.md) for details.
 
-- [webdriver/](https://github.com/mdn/browser-compat-data/tree/master/webdriver) contains data for [WebDriver](https://developer.mozilla.org/en-US/docs/Web/WebDriver) commands.
+### [`css`](https://github.com/mdn/browser-compat-data/tree/master/css)
 
-- [webextensions/](https://github.com/mdn/browser-compat-data/tree/master/webextensions) contains data for [WebExtensions](https://developer.mozilla.org/en-US/Add-ons/WebExtensions) JavaScript APIs and manifest keys.
+Data for [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) features, including:
 
-- [xpath/](https://github.com/mdn/browser-compat-data/tree/master/xpath) contains data for [XPath](https://developer.mozilla.org/docs/Web/XPath) axes, and functions.
+- `at-rules` - at-rules
+- `properties` - properties
+- `selectors` - selectors (such as basic selectors, combinators, or pseudo elements)
+- `types` - types for rule values
 
-- [xslt/](https://github.com/mdn/browser-compat-data/tree/master/xslt) contains data for [XSLT](https://developer.mozilla.org/docs/Web/XSLT) elements, attributes, and global attributes.
+### [`html`](https://github.com/mdn/browser-compat-data/tree/master/html)
 
-## Format of the browser compat json files
+Data for [HTML](https://developer.mozilla.org/en-US/docs/Web/HTML) features, including:
 
-The definitive description of the format used to represent compatibility data is the [schema file](https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data.schema.json).
-You can also have a look at the [schema documentation](https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data-schema.md).
+- `elements` - Elements
+- `global_attributes` - Global attributes
+- `manifest` - Web App manifest keys
+
+### [`http`](https://github.com/mdn/browser-compat-data/tree/master/http)
+
+Data for [HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP) features, including:
+
+- `headers` - Request and response headers
+- `methods` - Request methods
+- `status` - Status codes
+
+### [`javascript`](https://github.com/mdn/browser-compat-data/tree/master/javascript)
+
+Data for JavaScript language features, including:
+
+- `builtins` - Built-in objects
+- `classes` - Class definition features
+- `functions` - Function features
+- `grammar` - Language grammar
+- `operators` - Mathematical and logical operators
+- `statements` - Language statements and expressions
+
+### [`mathml`](https://github.com/mdn/browser-compat-data/tree/master/mathml)
+
+Data for [MathML](https://developer.mozilla.org/en-US/docs/Web/MathML) features, including:
+
+- `elements` - Elements
+
+### [`svg`](https://github.com/mdn/browser-compat-data/tree/master/svg)
+
+Data for [SVG](https://developer.mozilla.org/en-US/docs/Web/SVG) features, including:
+
+- `attributes` - Attributes
+- `elements` - Elements
+
+### [`webdriver`](https://github.com/mdn/browser-compat-data/tree/master/webdriver)
+
+Data for [WebDriver](https://developer.mozilla.org/en-US/docs/Web/WebDriver) features.
+
+### [`webextensions`](https://github.com/mdn/browser-compat-data/tree/master/webextensions)
+
+Data for [WebExtensions](https://developer.mozilla.org/en-US/Add-ons/WebExtensions) features, including:
+
+- `api` - WebExtension-specific APIs
+- `manifest` - `manifest.json` keys
+
+### [`xpath`](https://github.com/mdn/browser-compat-data/tree/master/xpath)
+
+Data for [XPath](https://developer.mozilla.org/en-US/docs/Web/XPath) features.
+
+### [`xslt`](https://github.com/mdn/browser-compat-data/tree/master/xslt)
+
+Data for [XSLT](https://developer.mozilla.org/en-US/docs/Web/XSLT) features.
+
+## Semantic versioning policy
+
+For the purposes of [semantic versioning](https://semver.org/) (SemVer), the public API consists of:
+
+- The high-level namespace objects documented in [_Package contents_](#Package-contents)
+- The schema definitions for browser and support data structures
+
+The details of browser compatibility change frequently, as browsers ship new features, standards organizations revise specifications, and Web developers discover new bugs. We routinely publish updates to the package to reflect these changes.
+
+You should expect lower-level namespaces, feature data, and browser data to be added, removed, or modified at any time. That said, we strive to communicate changes and preserve backward compatibility; if you rely on a currently undocumented portion of the package and want SemVer to apply to it, please [open an issue](https://github.com/mdn/browser-compat-data/issues).
 
 ## Issues?