re-org & update README to match current spec (@truffle/contract-schema)

Author: CruzMolina

packages/contract-schema/README.md

@@ -56,21 +56,20 @@ Name used to identify the contract. Semi-alphanumeric string.
 | JSON Schema | [abi.spec.json](spec/abi.spec.json) |
 | **required** |
 
+
 External programmatic description of contract's interface. The contract's ABI
 determines the means by which applications may interact with individual contract
 instances. Array of functions and events representing valid inputs and outputs
 for the instance.
 
 
-### `ast`
+### `metadata`
 
-| type | _object_ |
+| type | _string_ |
 | ---: | ---- |
 
-_not included in current version of this specification_
 
-Abstract Syntax Tree. A nested JSON object representation of contract source
-code, as output by compiler.
+Contract metadata. Stringified JSON.
 
 
 
@@ -87,7 +86,6 @@ Specified as a hexadecimal string, may include `__`-prefixed (double underscore)
 link references.
 
 
-
 ### `deployedBytecode`
 
 | type | _string_ matching pattern `^0x0$\|^0x([a-fA-F0-9]{2}\|__.{38})+$` |
@@ -101,6 +99,26 @@ Specified as a hexadecimal string, may include `__`-prefixed (double underscore)
 link references.
 
 
+### `sourceMap`
+
+| type | _string_ matching pattern `^[0-9;]*` |
+| ---: | ---- |
+
+
+Source mapping for `bytecode`, pairing contract creation transaction data bytes
+with origin statements in uncompiled `source`.
+
+
+### `deployedSourceMap`
+
+| type | _string_ matching pattern `^[0-9;]*` |
+| ---: | ---- |
+
+
+Source mapping for `deployedBytecode`, pairing contract program data bytes
+with origin statements in uncompiled `source`.
+
+
 ### `source`
 
 | type | _string_ |
@@ -115,86 +133,147 @@ Uncompiled source code for contract. Text string.
 | type | _string_ |
 | ---: | ---- |
 
+
 File path for uncompiled source code.
 
 
-### `sourceMap`
+### `ast`
 
-| type | _string_ matching pattern `^[0-9;]*` |
+| type | _object_ |
 | ---: | ---- |
 
 
-Source mapping for `bytecode`, pairing contract creation transaction data bytes
-with origin statements in uncompiled `source`.
+_format not included in current version of this specification_
 
+Abstract Syntax Tree. A nested JSON object representation of contract source
+code, as output by compiler.
 
-### `deployedSourceMap`
 
-| type | _string_ matching pattern `^[0-9;]*` |
+### `legacyAST`
+
+| type | _object_ |
 | ---: | ---- |
 
-Source mapping for `deployedBytecode`, pairing contract program data bytes
-with origin statements in uncompiled `source`.
 
+_format not included in current version of this specification_
 
-### `schemaVersion`
+Legacy Abstract Syntax Tree. A nested JSON object representation of contract source
+code, as output by compiler.
 
-| type | _string_ matching pattern `[0-9]+\.[0-9]+\.[0-9]+` |
+
+### `compiler`
+
+| type | _object_ |
 | ---: | ---- |
 
-Version of this schema used by contract object representation.
 
+Compiler information.
 
 
-### `updatedAt`
+### `name`
 
-| type | _string_ |
+| type | string |
 | ---: | ---- |
-| format | IS0-8601 Datetime |
 
 
-Time at which contract object representation was generated/most recently
-updated.
+Name of the compiler used.
+
+
+### `version`
+
+| type | string |
+| ---: | ---- |
+
+
+Version of the compiler used.
 
 
 ### `networks`
 
 | type | _object_ |
 | ---: | ---- |
 
+
 Listing of contract instances. Object mapping network ID keys to network object
 values. Includes address information, links to other contract instances, and/or
 contract event logs.
 
+
 #### Properties (key matching `^[a-zA-Z0-9]+$`)
 
 | type | _object_ |
 | ---: | ---- |
 | ref | [Network Object](network-object.spec.md) |
 
 
+### `schemaVersion`
+
+| type | _string_ matching pattern `[0-9]+\.[0-9]+\.[0-9]+` |
+| ---: | ---- |
+
+
+Version of this schema used by contract object representation.
+
+
+### `updatedAt`
+
+| type | _string_ |
+| ---: | ---- |
+| format | IS0-8601 Datetime |
+
+
+Time at which contract object representation was generated/most recently
+updated.
+
+
+### `networkType`
+
+| type | string |
+| ---: | ---- |
+
+
+Specific blockchain network type targeted.
+
+
+### `devdoc`
+
+| type | string |
+| ---: | ---- |
+
+
+NatSpec developer documentation of the contract.
+
+
+### `userdoc`
+
+| type | string |
+| ---: | ---- |
+
+
+NatSpec user documentation of the contract.
+
+
 ## Custom Properties
 
 ### `^x-([a-zA-Z]+-)*[a-zA-Z]+`
 
 | type | _string or number or object or array_ |
 | ---: | ---- |
 
+
 Objects following this schema may include additional properties with
 `x-`-prefixed keys.
 
 
-
 ## Definitions
 
 
-
-
 ### <a name="contract-object--bytecode">Bytecode</a>
 
 | type | _string_ matching pattern `^0x0$\|^0x([a-fA-F0-9]{2}\|__.{38})+$` |
 | ---: | ---- |
 
+
 `0x`-prefixed string representing compiled EVM machine language.
 
 This string representation may indicate link references in place of