Versioning and extensions

content/docs/specifications/data-package.md

@@ -138,12 +138,33 @@ Packaged data resources are described in the `resources` property of the package
 
 #### Required Properties
 
+##### `resources`
+
 The `resources` property is `REQUIRED`, with at least one resource.
 
 #### Recommended Properties
 
 In addition to the required properties, the following properties `SHOULD` be included in every package descriptor:
 
+##### `$schema`
+
+A Data Package descriptor `SHOULD` have the `$schema` property that `MUST` be an URL with default value `https://datapackage.org/profiles/datapackage-1.0.json`.
+
+The `$schema` property is both used as a Data Package version identifier and the location of a [JSON Schema file](../glossary/#metadata-profile) against which this Data Package `MUST` be valid.
+
+The `$schema` property `MUST`:
+
+- be exactly `https://datapackage.json/profiles/datapackage-X.Y.json` where `X` and `Y` are major and minor Data Package Standard versions OR
+- ends with `/EXTENSION-datapackage-X.Y.json` where `EXTENSION` is a name of an extension limited to the `[a-z0-9]` characters subset, and `X` and `Y` are major and minor extension versions.
+
+For example, a descriptor for a data package extension might have the property `$schema` set to `https://raw.githubusercontent.com/organization/project/main/automotive-datapackage-2.3.json`.
+
+If the `$schema` property indicates an extension, a data consumer `MUST` retrieve a Data Package version from the extension JSON Schema according the rules described in the [Extensions](../extensions) specification.
+
+:::note[Backward Compatibility]
+If the `$schema` property is not provided but a descriptor has the `profile` property a data consumer `MUST` validate the descriptor according to the [Profiles](https://specs.frictionlessdata.io/profiles/) specification.
+:::
+
 ##### `name`
 
 The name is a simple name or identifier to be used for this package in relation to any registry in which this package will be deposited.
@@ -199,26 +220,6 @@ Here is an example:
 [semver]: http://semver.org
 [url-or-path]: /data-resource/#url-or-path
 
-##### `profile`
-
-A string identifying the [profile][] of this descriptor as per the [profiles][profile] specification.
-
-[profile]: /profiles/
-
-Examples:
-
-```javascript
-{
-  "profile": "tabular-data-package"
-}
-```
-
-```javascript
-{
-  "profile": "http://example.com/my-profiles-json-schema.json"
-}
-```
-
 #### Optional Properties
 
 The following are commonly used properties that the package descriptor `MAY` contain: