diff --git a/doc/composer-schema.json b/doc/composer-schema.json
index 185f1dd82..2545a8d4b 100644
--- a/doc/composer-schema.json
+++ b/doc/composer-schema.json
@@ -5,119 +5,121 @@
     "properties": {
         "name": {
             "type": "string",
-            "description": "Package name, including type prefix if it's a plugin",
+            "description": "Package name, including 'vendor-name/' prefix.",
             "required": true
         },
         "type": {
-            "description": "Package type, either 'Library', or the parent project it applies to if it's a plugin for a framework or application (e.g. 'Symfony2', 'Typo3', 'Drupal', ..), note that this has to be defined and communicated by any project implementing a custom composer installer, those are just unreliable examples.",
-            "type": "string",
-            "optional": true
+            "description": "Package type, either 'library' for common packages, 'composer-installer' for custom installers, or a custom type defined by whatever project this package applies to.",
+            "type": "string"
         },
         "target-dir": {
-            "description": "Override install location of package",
+            "description": "Forces the package to be installed into the given subdirectory path. This is used for autoloading PSR-0 packages that do not contain their full path. Use forward slashes for cross-platform compatibility.",
             "type": "string"
         },
         "description": {
             "type": "string",
-            "description": "Package description",
+            "description": "Short package description.",
             "required": true
         },
         "keywords": {
             "type": "array",
             "items": {
-                "type": "string"
-            },
-            "optional": true
+                "type": "string",
+                "description": "A tag/keyword that this package relates to."
+            }
         },
         "homepage": {
             "type": "string",
-            "description": "Homepage URL for the project",
-            "format": "uri",
-            "optional": true
+            "description": "Homepage URL for the project.",
+            "format": "uri"
         },
         "version": {
             "type": "string",
-            "description": "Package version, see http://packagist.org/about for more info on valid schemes",
+            "description": "Package version, see http://packagist.org/about for more info on valid schemes.",
             "required": true
         },
+        "time": {
+            "type": "string",
+            "description": "Package release date, in 'YYYY-MM-DD' or 'YYYY-MM-DD HH:MM:SS' format."
+        },
         "license": {
             "type": ["string", "array"],
-            "description": "License name",
-            "optional": true
+            "description": "License name. Or an array of license names."
         },
         "authors": {
             "type": "array",
+            "description": "List of authors that contributed to the package. This is typically the main maintainers, not the full list.",
             "items": {
                 "type": "object",
                 "additionalProperties": false,
                 "properties": {
                     "name": {
                         "type": "string",
-                        "description": "Full name of the author",
+                        "description": "Full name of the author.",
                         "required": true
                     },
                     "email": {
                         "type": "string",
-                        "description": "Email address of the author",
-                        "format": "email",
-                        "required": true
+                        "description": "Email address of the author.",
+                        "format": "email"
                     },
                     "homepage": {
                         "type": "string",
-                        "description": "Homepage URL for the author",
-                        "format": "uri",
-                        "optional": true
+                        "description": "Homepage URL for the author.",
+                        "format": "uri"
                     }
                 }
-            },
-            "optional": true
+            }
         },
         "require": {
             "type": "object",
-            "additionalProperties": true,
-            "optional": true
+            "description": "This is a hash of package name (keys) and version constraints (values) that are required to run this package.",
+            "additionalProperties": true
         },
         "replace": {
             "type": "object",
-            "additionalProperties": true,
-            "optional": true
+            "description": "This is a hash of package name (keys) and version constraints (values) that can be replaced by this package.",
+            "additionalProperties": true
         },
         "conflict": {
             "type": "object",
-            "additionalProperties": true,
-            "optional": true
+            "description": "This is a hash of package name (keys) and version constraints (values) that conflict with this package.",
+            "additionalProperties": true
         },
         "provide": {
             "type": "object",
-            "additionalProperties": true,
-            "optional": true
+            "description": "This is a hash of package name (keys) and version constraints (values) that this package provides in addition to this package's name.",
+            "additionalProperties": true
         },
         "recommend": {
             "type": "object",
-            "additionalProperties": true,
-            "optional": true
+            "description": "This is a hash of package name (keys) and version constraints (values) that this package recommends to be installed (typically this will be installed as well).",
+            "additionalProperties": true
         },
         "suggest": {
             "type": "object",
-            "additionalProperties": true,
-            "optional": true
+            "description": "This is a hash of package name (keys) and version constraints (values) that this package suggests work well with it (typically this will only be suggested to the user).",
+            "additionalProperties": true
         },
         "extra": {
             "type": ["object", "array"],
-            "additionalProperties": true,
-            "optional": true
+            "description": "Arbitrary extra data that can be used by custom installers, for example, package of type composer-installer must have a 'class' key defining the installer class name.",
+            "additionalProperties": true
         },
         "autoload": {
             "type": "object",
+            "description": "Description of how the package can be autoloaded.",
             "properties": {
                 "psr-0": {
                     "type": "object",
+                    "description": "This is a hash of namespaces (keys) and the directories they can be found into (values) by the autoloader.",
                     "additionalProperties": true
                 }
             }
         },
         "repositories": {
             "type": ["object", "array"],
+            "description": "A set of additional repositories where packages can be found.",
             "additionalProperties": true
         }
     }