Update EIP-1523: Parameter handling (#4338)

- More parameters, standardize naming
- Differentiate between optional and mandatory parameters

EIPS/eip-1523.md

@@ -3,7 +3,7 @@ eip: 1523
 title: Standard for Insurance Policies as ERC-721 Non Fungible Tokens
 author: Christoph Mussenbrock (@christoph2806)
 discussions-to: https://github.com/ethereum/EIPs/issues/1523
-status: Stagnant
+status: Draft
 type: Standards Track
 category: ERC
 created: 2018-10-10
@@ -73,36 +73,40 @@ In analogy to the “ERC721 Metadata JSON Schema”, the tokenURI **MUST** point
             "type": "string",
             "description": "Describes the asset to which this NFT represents",
         },
-        "carrier": {
-            "type": "string",
-            "description": "Describes the carrier which takes the primary risk",
-        },
-        "risk": {
-            "type": "string",
-            "description": "Describes the risk",
-        },
-        "parameters": {
-            "type": "string",
-            "description": "Describes further parameters characterizing the risk",
-        },
-        "status": {
-            "type": "string",
-            "description": "Defines the status of the policy, e.g. Applied, Underwritten, Claimed, Paid out, etc."
-        }
+        \[additional parameters according to the following table\]
     }
 }
 ```
 
+### Additional parameters for the metadata JSON Schema
+
+| Parameter     | Type          | Mandatory | Description                                                                        |
+| ------------- | ------------- | ----------| ---------------------------------------------------------------------------------- |  
+| carrier       | string        | yes       | Describes the carrier which takes the primary risk                                 |
+| risk          | string        | yes       | Describes the risk                                                                 |
+| status        | string        | yes       | Describes the status of the policy, e.g. applied for, underwritten, expired        |
+| parameters    | string        | no        | Describes further parameters characterizing the risk                               |
+| terms         | string        | no        | Describes legal terms & conditions which apply for this policy                     |
+| premium       | string        | no        | A string representation of the premium, **MAY** contain currency denominator       |
+| sum_insured   | string        | no        | A string representation of the sum insured, **MAY** contain currency denominator   |
+
+Parameters which are mandatory **MUST** be included in the metadata JSON. Other parameters **MAY** be included. However, the proposed optional parameters **SHOULD** be used for the intended purpose, so e.g. if the premium amount would be included in the metadata, the parameter name **SHOULD** be "premium".
+All parameters **MAY** be plain text or **MAY** also be URIs pointing to resources which contain the respective information, and which **MAY** be protected by an authentication mechanism. 
+
 ## Rationale
 Insurance policies form an important class of financial assets, and it is natural to express those assets as a class of non-fungible tokens which adhere to the established ERC-721 standard.
-We propose a standard for the accompanying metadata structures which are needed to uniquely define an insurance policy.
+We propose a standard for the accompanying metadata structures which are needed to uniquely define an insurance policy. Standardization is key because we expect decentralized insurance to receive widespread adoption and it is crucial to establish a unified standard to enable composability and the creation of universal toolsets. 
+We therefore propose a standardized naming scheme for the different parameters describing an insurance policy. We propose three mandatory parameters which need to be included in every NFT and further parameters which **MAY** be used, and for which we only standardize the naming conventions.
+### Mandatory parameters
 While policies can have a multitude of possible properties, it is common that policies are issued by some entity, which is basically the entity responsible for paying out claims.
 Second, an insurance policy is typically related to a specific risk. Some risks are unique, but there are cases where many policies share the same risk
 (e.g. all flight delay policies for the same flight).
 In general, the relation of policies to risks is a many-to-one relation with the special case of a one-to-one relation.
-Third, most policies need more parameters to characterize the risk and other features, like premium, period etc.
-Forth, a policy has a lifecycle of different statuses. 
+Third, a policy has a lifecycle of different statuses. Therefore the NFT 
 We believe that those four properties are necessary to describe a policy. For many applications, those properties may be even sufficient. 
+
+### Optional parameters
+Most policies need more parameters to characterize the risk and other features, like premium, period etc. The naming conventions are listed in the above table.
 However, any implementation **MAY** chose to implement more properties.
 
 ### On-chain vs. off-chain metadata