Update readme.md

pennsignals · Aug 8, 2017 · b9e6bac · b9e6bac
1 parent facafb6
commit b9e6bac
Showing 1 changed file with 40 additions and 62 deletions.
diff --git a/readme.md b/readme.md
@@ -7,11 +7,14 @@
     <a href="https://coveralls.io/github/pennsignals/aptos"><img src="https://img.shields.io/coveralls/pennsignals/aptos.svg?style=flat-square" alt="Coverage Status"></a>
 </p>
 
-> A module that parses [JSON Schema](http://json-schema.org/) documents to validate client-submitted data and convert JSON schema documents to Avro schema documents.
+> Validate client-submitted data using [JSON Schema](http://json-schema.org/) documents and convert JSON Schema documents into different data-interchange formats.
 
 ## Usage
 
-`aptos` supports validating client-submitted data and generates Avro structured messages from a given JSON Schema document.
+`aptos` supports the following capabilities:
+
+ - **Data Validation:** Validate client-submitted data using [validation keywords](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6) described in the JSON Schema specification.
+ - **Schema Conversion:** Convert JSON Schema documents into different data-interchange formats. See the list of supported data-interchange formats for more information.
 
 ```
 usage: aptos [arguments] SCHEMA
@@ -38,64 +41,48 @@ More information on JSON Schema: http://json-schema.org/
 
 ## Data Validation
 
-Given a JSON Schema document, `aptos` can validate client-submitted data to ensure that it satisfies a certain number of criteria.
+Here is a basic example of a JSON Schema:
 
 ```json
 {
-    "title": "Product",
+    "title": "Person",
     "type": "object",
-    "definitions": {
-        "geographical": {
-            "title": "Geographical",
-            "description": "A geographical coordinate",
-            "type": "object",
-            "properties": {
-                "latitude": { "type": "number" },
-                "longitude": { "type": "number" }
-            }
-        }
-    },
     "properties": {
-        "id": {
-            "description": "The unique identifier for a product",
-            "type": "number"
-        },
-        "name": {
+        "firstName": {
             "type": "string"
         },
-        "price": {
-            "type": "number",
-            "minimum": 0,
-            "exclusiveMinimum": true
-        },
-        "tags": {
-            "type": "array",
-            "items": {
-                "type": "string"
-            },
-            "minItems": 1,
-            "uniqueItems": true
-        },
-        "dimensions": {
-            "title": "Dimensions",
-            "type": "object",
-            "properties": {
-                "length": {"type": "number"},
-                "width": {"type": "number"},
-                "height": {"type": "number"}
-            },
-            "required": ["length", "width", "height"]
+        "lastName": {
+            "type": "string"
         },
-        "warehouseLocation": {
-            "description": "Coordinates of the warehouse with the product",
-            "$ref": "#/definitions/geographical"
+        "age": {
+            "description": "Age in years",
+            "type": "integer",
+            "minimum": 0
         }
     },
-    "required": ["id", "name", "price"]
+    "required": ["firstName", "lastName"]
 }
 ```
 
-Validation keywords such as `uniqueItems`, `required`, and `minItems` can be used in a schema to impose requirements for successful validation of an instance.
+Given a JSON Schema, `aptos` can validate client-submitted data to ensure that it satisfies a certain number of criteria.
+
+JSON Schema [Validation keywords](http://json-schema.org/latest/json-schema-validation.html#rfc.section.6) such as `minimum` and `required` can be used to impose requirements for successful validation of an instance. In the JSON Schema above, both the `firstName` and `lastName` properties are required, and the `age` property *MUST* have a value greater than or equal to 0.
+
+| Valid Instance :heavy_check_mark:                     | Invalid Instance :heavy_multiplication_x:                                                                               |
+|-------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
+| `{"firstName": "John", "lastName": "Doe", "age": 42}` | `{"firstName": "John", "age": -15}` (missing required property `lastName` and `age` is not greater than or equal to 0)  |
+
+`aptos` can validate client-submitted data using either the CLI or the API:
+
+### CLI
+
+    $ aptos validate -instance INSTANCE SCHEMA
+
+| Successful Validation :heavy_check_mark:                                                                 | Unsuccessful Validation :heavy_multiplication_x:                                                         |
+|----------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
+| ![](https://user-images.githubusercontent.com/2184329/29053486-5c787966-7bbe-11e7-8fd3-4cb51d87d7d9.png) | ![](https://user-images.githubusercontent.com/2184329/29053538-afcce9c6-7bbe-11e7-8be5-61ac1d876fc1.png) |
+
+### API
 
 ```python
 import json
@@ -107,23 +94,14 @@ from aptos.visitor import ValidationVisitor
 with open('/path/to/schema') as fp:
     schema = json.load(fp)
 component = SchemaParser.parse('/path/to/schema')
-# Valid client-submitted data (instance)
+# Invalid client-submitted data (instance)
 instance = {
-    "id": 2,
-    "name": "An ice sculpture",
-    "price": 12.50,
-    "tags": ["cold", "ice"],
-    "dimensions": {
-        "length": 7.0,
-        "width": 12.0,
-        "height": 9.5
-    },
-    "warehouseLocation": {
-        "latitude": -78.75,
-        "longitude": 20.4
-    }
+  'firstName': 'John'
 }
-component.accept(ValidationVisitor(instance))
+try:
+    component.accept(ValidationVisitor(instance))
+except AssertionError as e:
+    print(e)  # instance {'firstName': 'John'} is missing required property 'lastName'
 ```
 
 ## Structured Message Generation