manifest-format.md in inqlude-0.0.8 vs manifest-format.md in inqlude-0.7.0

@@ -30,23 +30,37 @@
 attributes describing the library and the specific version represented by the
 concrete file.
 
 These are the attributes:
 
-### schema_version
+### $schema
 
-Version number of the schema used in this manifest
+This is a reference to the schema which is used in the manifest file. The
+schema follows the [JSON Schema](http://json-schema.org) specification.
 
-This is used to make expectations of tools and processing explicit and adapt
-to schema changes.
+The schema comes in three flavors: "generic", "release", and
+"proprietary-release". They differe in what fields are required, the meaning of
+fields is the same in all. "generic" is a subset of "proprietary-release", which
+is a subset of "release".
 
+Each schema has an identifier. The current identifier for the release schema is
+"http://inqlude.org/schema/release-manifest-v1#". It includes the version
+number. The other identifiers are the same, but instead of "release" they use
+the corresponding sub string identifying the flavor.
+
+The schema and its versioning is used to make expectations of tools and
+processing explicit and adapt to schema changes.
+
 If the schema is changed in a way incompatible with processing tools, the
 schema version number has to be increased.
 
-This document specifies schema version 1.
+As Inqlude currently still is in alpha, changes to the schema are to be expected
+and while we will try to not break things, there might be some incompatible
+changes without changing the version number during development. This will stop,
+when we have reached beta state.
 
-*schema_version is a mandatory attribute*
+*$schema is a mandatory attribute*
 
 ### name
 
 Name of the library
 
@@ -69,17 +83,17 @@
 
 ### release_date
 
 Date, when the version was released
 
-*release_date is a mandatory attribute*
+*release_date is a mandatory attribute in the release schemas*
 
 ### version
 
 Version of the release
 
-*version is a mandatory attribute*
+*version is a mandatory attribute in the release schemas*
 
 ### summary
 
 One-line summary describing the library
 
@@ -130,12 +144,12 @@
 ### description
 
 Full description of the library
 
 The description is a text describing the library. It can be of arbitrary length.
-No special formatting is supported other than using newlines to start a new
-paragraph.
+The text is formatted using
+[Markdown](http://daringfireball.net/projects/markdown/syntax).
 
 *description is a mandatory attribute*
 
 ### authors
 
@@ -156,11 +170,11 @@
 * "stable": for stable releases ready for production use
 * "beta": for pre-releases of stable versions used for gathering feedback, not
   recommended for production use
 * "alpha": preview releases, not suitable for production use
 
-*maturity is a mandatory attribute*
+*maturity is a mandatory attribute, it's optional in the generic schema*
 
 ### platforms
 
 List of supported platforms
 
@@ -188,10 +202,11 @@
 #### source
 
 This is the source code of the release. It has one URL to the file, which
 can be used to download the code.
 
-*source is a mandatory package attribute*
+*source is a mandatory package attribute in the release schema, it's optional
+in the proprietary-release schema*
 
 #### openSUSE
 
 openSUSE binary packages. For each version of openSUSE there is a separate
 entry.