openwhisk-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From houshen...@apache.org
Subject [incubator-openwhisk-wskdeploy] branch master updated: Programming Guide - part6 and Specification in HTML (#551)
Date Mon, 25 Sep 2017 02:09:03 GMT
This is an automated email from the ASF dual-hosted git repository.

houshengbo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-openwhisk-wskdeploy.git


The following commit(s) were added to refs/heads/master by this push:
     new 61a0412  Programming Guide - part6 and Specification in HTML (#551)
61a0412 is described below

commit 61a04126f39b8dedf63a509e6a685a7e503cfec5
Author: Matt Rutkowski <mrutkows@us.ibm.com>
AuthorDate: Sun Sep 24 21:09:01 2017 -0500

    Programming Guide - part6 and Specification in HTML (#551)
    
    * Added doc for creating tagged releases from Vincent.
    
    * Added doc for creating tagged releases from Vincent.
    
    * Add spec. grammar for Packages.
    
    * Add spec. grammar for Packages.
    
    * Add spec. grammar for Packages.
    
    * Add spec. grammar for Packages.
    
    * Add spec. grammar for Packages.
    
    * Add spec. grammar for Packages.
    
    * Add spec. grammar for Packages.
    
    * Add spec. grammar for Packages.
    
    * Add spec. grammar for Packages.
    
    * Add spec. grammar for Packages.
    
    * Add spec. grammar for Packages.
    
    * Add spec. grammar for Packages.
    
    * Add full listing of supported types; YAML and OW..
    
    * Add full listing of supported types; YAML and OW..
    
    * Add full listing of supported types; YAML and OW..
    
    * Add full listing of supported types; YAML and OW..
    
    * Add full listing of supported types; YAML and OW..
    
    * Link Packages grammar to Guide.
    
    * Link Packages grammar to Guide.
    
    * Link Packages grammar to Guide.
    
    * Link Packages grammar to Guide.
    
    * Link Packages grammar to Guide.
    
    * Link Packages grammar to Guide.
    
    * Link Packages grammar to Guide.
    
    * Link Packages grammar to Guide.
    
    * Link Packages grammar to Guide.
    
    * Add Trigger and Rule spec. HTML page.
    
    * Add Trigger and Rule spec. HTML page.
    
    * Add Trigger and Rule spec. HTML page.
    
    * Add Shared Entity Schema HTML page.
    
    * Add Spec. HTML index.
    
    * Add Spec. HTML index.
    
    * Add Spec. HTML index.
    
    * Add Spec. HTML index.
    
    * Add Spec. HTML index.
    
    * Archive older versions of the specification.
    
    * Adjust index links.
    
    * Adjust index links.
    
    * Adjust index links.
    
    * Adjust index links.
    
    * Adjust index links.
    
    * Adjust index links.
    
    * Adjust index links.
    
    * Adjust index links.
    
    * Add Parameter schema HTML page.
    
    * Add Parameter schema HTML page.
    
    * Add Parameter schema HTML page.
    
    * Add Parameter schema HTML page.
    
    * Add Parameter schema HTML page.
    
    * Add Sequences schema HTML page.
    
    * Adjust spec. README to be the launch page for prog. guide and HTML spec.
    
    * Adjust spec. README to be the launch page for prog. guide and HTML spec.
    
    * Adjust spec. README to be the launch page for prog. guide and HTML spec.
    
    * Adjust spec. README to be the launch page for prog. guide and HTML spec.
    
    * Adjust spec. README to be the launch page for prog. guide and HTML spec.
    
    * Adjust spec. README to be the launch page for prog. guide and HTML spec.
    
    * Update guide to have index and step-by-step navigation.
    
    * Update guide to have index and step-by-step navigation.
    
    * Update guide to have index and step-by-step navigation.
    
    * Update guide to have index and step-by-step navigation.
    
    * Update guide to have index and step-by-step navigation.
    
    * Update guide to have index and step-by-step navigation.
    
    * Update guide to have index and step-by-step navigation.
    
    * Update guide to have index and step-by-step navigation.
    
    * Update guide to have index and step-by-step navigation.
    
    * Update guide to have index and step-by-step navigation.
    
    * Update guide to have index and step-by-step navigation.
    
    * Update guide to have index and step-by-step navigation.
    
    * Adding helloworld Action IO example.
    
    * Helloworld with advanced parms. example.
    
    * Helloworld with advanced parms. example.
    
    * Helloworld with advanced parms. example.
    
    * Helloworld with advanced parms. example.
    
    * Helloworld with advanced parms. example.
    
    * Helloworld with advanced parms. example.
    
    * Helloworld with advanced parms. example.
---
 README.md                                          |   5 +
 docs/creating_tagged_releases.md                   |  15 +
 docs/programming_guide.md                          |  82 ++---
 docs/wskdeploy_debugging.md                        |   2 +-
 docs/wskdeploy_hello_world.md                      |  77 ++++
 docs/wskdeploy_helloworld_advanced_parms.md        |  64 ++++
 docs/wskdeploy_helloworld_basic_parms.md           |  59 ++++
 docs/wskdeploy_packages.md                         |  77 +++-
 specification/README.md                            |  64 ++--
 .../openwhisk_v0.8.1.pdf}                          | Bin
 specification/{ => archive}/openwhisk_v0.8.2.pdf   | Bin
 specification/{ => archive}/openwhisk_v0.8.3.pdf   | Bin
 specification/{ => archive}/openwhisk_v0.8.4.pdf   | Bin
 specification/{ => archive}/openwhisk_v0.8.5.pdf   | Bin
 specification/{ => archive}/openwhisk_v0.8.6.pdf   | Bin
 specification/{ => archive}/openwhisk_v0.8.7.pdf   | Bin
 specification/{ => archive}/openwhisk_v0.8.8.pdf   | Bin
 specification/html/spec_actions.md                 | 349 ++++++++++++++++++
 specification/html/spec_index.md                   |  18 +
 specification/html/spec_packages.md                | 168 +++++++++
 specification/html/spec_parameters.md              | 244 +++++++++++++
 specification/html/spec_sequences.md               |  59 ++++
 specification/html/spec_shared_entity_schema.md    |  90 +++++
 specification/html/spec_trigger_rule.md            | 222 ++++++++++++
 specification/html/spec_types.md                   | 391 +++++++++++++++++++++
 specification/html/spec_types_yaml.md              | 139 --------
 26 files changed, 1886 insertions(+), 239 deletions(-)

diff --git a/README.md b/README.md
index df60ed3..315afc9 100644
--- a/README.md
+++ b/README.md
@@ -191,3 +191,8 @@ This is caused by newer `git` versions not forwarding requests anymore. One solu
 ```
 $ git config --global http.https://gopkg.in.followRedirects true
 ```
+
+## Creating Tagged Releases
+
+Committers can find instructions on how to create tagged releases here:
+- [creating_tagged_releases.md](https://github.com/apache/incubator-openwhisk-wskdeploy/tree/master/docs/creating_tagged_releases.md)
diff --git a/docs/creating_tagged_releases.md b/docs/creating_tagged_releases.md
new file mode 100644
index 0000000..7491a31
--- /dev/null
+++ b/docs/creating_tagged_releases.md
@@ -0,0 +1,15 @@
+# Creating Tagged Releases of ```wskdeploy```
+
+The most convenient way to create a tagged release for wskdeploy is to build the binaries by adding tag to upstream master.
+
+
+1. Add a tag to a commit id: ```git tag -a 0.8.9<tag> c08b0f<commit id>```
+2. Push the tag upstream: ```git push -f upstream 0.8.9<tag>```
+
+Travis will start the build of 0.8.9 automatically by the event of tag creation.
+
+If the travis build passed, binaries will be pushed into releases page.
+
+If we modify the tag by pointing to a different commit, use ```git push -f upstream 0.8.9<tag>``` to overwrite the old tag. New binaries from travis build will overwrite the old binaries as well.
+
+You can download the binaries, and delete them from the releases page in GitHub if we do not want them to be public.
diff --git a/docs/programming_guide.md b/docs/programming_guide.md
index 3a6b75d..fd1c56b 100644
--- a/docs/programming_guide.md
+++ b/docs/programming_guide.md
@@ -13,71 +13,29 @@ In addition to the normal output the ```wskdeploy``` utility provides, you may e
 
 ---
 
-## Creating a "hello world" application
+# Guided Examples
 
-As with most language introductions, here we show a minimal "hello world" application as encoded in an OpenWhisk Package Manifest YAML file:
+Below is the list of "guided examples" where you can start by "Creating a 'hello world' application" and traverse through each example or jump to any example that interests you.
 
-```yaml
-package:
-  name: hello_world_package
-  version: 1.0
-  license: Apache-2.0
-  actions:
-    hello_world:
-      function: src/hello.js
-```
+Each example shows the "code", that is the Package Manifest, Deployment file and Actions that will be used to deploy that application or package, as well as discusses the interesting features the example is highlighting.
 
-where "hello.js" contains the following JavaScript code:
-```javascript
-function main(params) {
-    msg = "Hello, " + params.name + " from " + params.place;
-    return { greeting:  msg };
-}
-```
-
-#### Source code
-The source code for the manifest and JavaScript files can be found here:
-- [manifest_hello_world.yaml](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/manifest_hello_world.yaml)
-- [hello.js](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/src/hello.js)
-
-
-### Deploying "hello world"
-
-You can actually deploy the "hello world" manifest from the incubator-openwhisk-wskdeploy project directory if you have downloaded it from GitHub:
-
-```sh
-$ ./wskdeploy -m docs/examples/manifest_hello_world.yaml
-```
-
-if you want to simply verify your manifest is able to read and parse your manifest file, you can add the ```-i``` or ```--allow-interactive``` flag:
-
-```sh
-$ ./wskdeploy -i -m docs/examples/manifest_hello_world.yaml
-```
-
-and the utility will stop, show you all the OpenWhisk package components it will deply and ask you if you want to deploy them or not.
-
-```
-Package:
-  name: hello_world_package
-  bindings:
-
-  * action: hello_world
-    bindings:
-    annotations:
-
-  Triggers:
-  Rules:
-
-Do you really want to deploy this? (y/N):
-```
-
-### Examining the "hello world" Manifest
-
-The "hello world" example represents the minimum valid Manifest file which includes only the required parts of the Package and Action desciptors.
+- [Creating a minimal Package](wskdeploy_packages.md#packages) - creating a basic package manifet and deploying it.
+- [Creating a "Hello World" package](wskdeploy_hello_world.md#creating-a-hello-world-package) - deploy your first function using a manifest.
+- [Actions with Basic Parameters](wskdeploy_helloworld_basic_parms.md#actions-with-basic-parameters) - declare named input and output parameters on an Action with their types.
+- [Actions with Advanced Parameters](wskdeploy_helloworld_advanced_parms.md#actions-with-advanced-parameters) - input and output parameter declarations with more detailed information.
 
+---
 <!--
-If you want to explore all possible Package and Action declarations (i.e., their schema) you can read:
-- [Exploring Packages](wskdeploy_packages.md) - step-by-step guide on the **Package** schema.
-- [Exploring Actions](wskdeploy_actions.md) - step-by-step guide on the **Action** schema.
+ Bottom Navigation
 -->
+<html>
+<div align="center">
+<table align="center">
+  <tr>
+    <td><a>&lt;&lt;&nbsp;previous</a></td>
+    <td><a href="programming_guide.md#guided-examples">Index</a></td>
+    <td><a href="wskdeploy_packages.md#packages">next&nbsp;&gt;&gt;</a></td>
+  </tr>
+</table>
+</div>
+</html>
diff --git a/docs/wskdeploy_debugging.md b/docs/wskdeploy_debugging.md
index 1f4fbe7..d062e5c 100644
--- a/docs/wskdeploy_debugging.md
+++ b/docs/wskdeploy_debugging.md
@@ -12,7 +12,7 @@ $ wskdeploy -v -m manifest.yaml
 
 ## Enable console logging in your Action
 
-You may call ```console.log(<text>)`` within your Action (function) code to aid in debugging.  For example, in NodeJS (JavaScript) you could output your entire JSON payload before returning it:
+You may call ```console.log(<text>)``` within your Action (function) code to aid in debugging.  For example, in NodeJS (JavaScript) you could output your entire JSON payload before returning it:
 ```
 function main(params) {
     msg = "Hello, " + params.name + " from " + params.place;
diff --git a/docs/wskdeploy_hello_world.md b/docs/wskdeploy_hello_world.md
new file mode 100644
index 0000000..5994c19
--- /dev/null
+++ b/docs/wskdeploy_hello_world.md
@@ -0,0 +1,77 @@
+## Creating a "hello world" package
+
+As with most language introductions, here we show a minimal "hello world" application as encoded in an OpenWhisk Package Manifest YAML file:
+
+### Manifest file
+```yaml
+package:
+  name: hello_world_package
+  version: 1.0
+  license: Apache-2.0
+  actions:
+    hello_world:
+      function: src/hello.js
+```
+
+where "hello.js" contains the following JavaScript code:
+```javascript
+function main(params) {
+    msg = "Hello, " + params.name + " from " + params.place;
+    return { greeting:  msg };
+}
+```
+
+### Deploying "hello world"
+
+You can actually deploy the "hello world" manifest from the incubator-openwhisk-wskdeploy project directory if you have downloaded it from GitHub:
+
+```sh
+$ ./wskdeploy -m docs/examples/manifest_hello_world.yaml
+```
+
+### Running
+```sh
+$ wsk action invoke hello_world_package/hello_world --blocking
+```
+should return an 'ok' with a response that looks like:
+```sh
+    "response": {
+        "result": {
+            "greeting": "Hello, undefined from undefined"
+        },
+        "status": "success",
+        "success": true
+    },
+```
+
+### Discussion
+
+This "hello world" example represents the minimum valid Manifest file which includes only the required parts of the Package and Action descriptors.
+
+- The package and action were deployed to the user’s default namespace:
+  - ```/<default namespace>/hello_world_package/hello_world```
+- The NodeJS runtime was selected automatically based upon the file extension '```.js```'' of the function's source file '```hello.js```'.
+- The parameters 'name' and 'place' in this example are not set to any default values; therefore 'greeting' will appear a follows:
+  - ```"greeting": "Hello, undefined from undefined"```
+  we will explore setting these values in later examples.
+
+### Source code
+The source code for the manifest and JavaScript files can be found here:
+- [manifest_hello_world.yaml](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/manifest_hello_world.yaml)
+- [hello.js](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/src/hello.js)
+
+---
+<!--
+ Bottom Navigation
+-->
+<html>
+<div align="center">
+<table align="center">
+  <tr>
+    <td><a href="wskdeploy_packages.md#packages">&lt;&lt;&nbsp;previous</a></td>
+    <td><a href="programming_guide.md#guided-examples">Index</a></td>
+    <td><a href="wskdeploy_helloworld_basic_parms.md#hello-world-action-with-basic-parameters">next&nbsp;&gt;&gt;</a></td>
+  </tr>
+</table>
+</div>
+</html>
diff --git a/docs/wskdeploy_helloworld_advanced_parms.md b/docs/wskdeploy_helloworld_advanced_parms.md
new file mode 100644
index 0000000..ac105c1
--- /dev/null
+++ b/docs/wskdeploy_helloworld_advanced_parms.md
@@ -0,0 +1,64 @@
+## Actions with advanced parameters
+
+This example builds on the previous “Hello world with basic input and output parameters” example with more robust input and output parameter declarations by using a multi-line format for declaration.
+
+This example:
+- shows how to declare input and output parameters on the action ‘```hello_world```’ using a multi-line grammar.
+- adds the ‘```name```’ and ‘```place```’ input parameters, both of type ‘```string```’, to the ‘```hello_world``’ action each also includes an associated ‘```description```’ value.
+- adds the ‘```greeting```’ output parameter of explicit ‘```type```’ of ‘```string```’ to the ‘```hello_world```’ action with a ‘```description```’.
+
+### Manifest File
+
+If we want to do more than declare the type (i.e., ‘string’, ‘integer’, ‘float’, etc.) of the input parameter, we can use the multi-line grammar.
+
+#### Example 3: input and output parameters with explicit types and descriptions
+```yaml
+package:
+  name: hello_world_package
+  ... # Package keys omitted for brevity
+  actions:
+    hello_world_3:
+      function: src/hello/hello.js
+      runtime: nodejs@6
+      inputs:
+        name:
+          type: string
+          description: name of person
+        place:
+          type: string
+          description: location of person
+      outputs:
+        greeting:
+          type: string
+          description: greeting string
+```
+
+### Discussion
+Describing the input and output parameter types, descriptions and other meta-data helps
+- tooling validate values users may input and prompt for missing values using the descriptions provided.
+- allows verification that outputs of an Action are compatible with the expected inputs of another Action so that they can be composed in a sequence.
+
+### Source code
+The manifest file for this example can be found here:
+- [manifest_hello_world_3.yaml](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/manifest_hello_world_2.yaml)
+
+### Specification
+For convenience, links to the schema and grammar for Actions and Parameters:
+- **Actions**: [https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_actions.md#actions](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_actions.md#actions)
+- **Parameters** [https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_parameters.md#parameters](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_parameters.md#parameters)
+
+---
+<!--
+ Bottom Navigation
+-->
+<html>
+<div align="center">
+<table align="center">
+  <tr>
+    <td><a href="wskdeploy_helloworld_basic_parms.md#actions-with-basic-parameters">&lt;&lt;&nbsp;previous</a></td>
+    <td><a href="programming_guide.md#guided-examples">Index</a></td>
+    <td><a href="">next&nbsp;&gt;&gt;</a></td>
+  </tr>
+</table>
+</div>
+</html>
diff --git a/docs/wskdeploy_helloworld_basic_parms.md b/docs/wskdeploy_helloworld_basic_parms.md
new file mode 100644
index 0000000..21d3b82
--- /dev/null
+++ b/docs/wskdeploy_helloworld_basic_parms.md
@@ -0,0 +1,59 @@
+## Actions with basic parameters
+
+This example extends the 'Hello world' example with explicit input and output Parameter declarations.
+
+This example:
+- shows how to declare input and output parameters on the action 'hello_world'
+using a simple, single-line grammar.
+- adds two input parameters, '```name```' and '```place```', both of type '```string```' to the '```hello_world```' action.
+- adds one output parameter, '```greeting```' of type string to the '```hello_world```' action.
+
+### Manifest File
+
+#### Example 2: 'Hello world' with explicit input and output parameter declarations
+```yaml
+package:
+  name: hello_world_package
+  ... # Package keys omitted for brevity
+  actions:
+    hello_world_2:
+      function: src/hello.js
+      inputs:
+        name: string
+        place: string
+      outputs:
+        greeting: string
+```
+
+### Discussion
+This packaging specification grammar places an emphasis on simplicity for the casual developer who may wish to hand-code a Manifest File; however, it also provides a robust optional schema that can be advantaged when integrating with larger application projects using design and development tooling such as IDEs.
+
+In this example:
+
+- The default values for the '```name```' and '```place```' inputs would be set to empty strings (i.e., ''), since they are of type 'string', when passed to the 'hello.js' function; therefore 'greeting' will appear a follows:
+  - ```"greeting": "Hello, from "```
+
+### Source code
+The manifest file for this example can be found here:
+- [manifest_hello_world_2.yaml](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/manifest_hello_world_2.yaml)
+
+### Specification
+For convenience, links to the schema and grammar for Actions and Parameters:
+- **Actions**: [https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_actions.md#actions](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_actions.md#actions)
+- **Parameters** [https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_parameters.md#parameters](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_parameters.md#parameters)
+
+---
+<!--
+ Bottom Navigation
+-->
+<html>
+<div align="center">
+<table align="center">
+  <tr>
+    <td><a href="wskdeploy_hello_world.md#creating-a-hello-world-package">&lt;&lt;&nbsp;previous</a></td>
+    <td><a href="programming_guide.md#guided-examples">Index</a></td>
+    <td><a href="wskdeploy_helloworld_advanced_parms.md#actions-with-advanced-parameters">next&nbsp;&gt;&gt;</a></td>
+  </tr>
+</table>
+</div>
+</html>
diff --git a/docs/wskdeploy_packages.md b/docs/wskdeploy_packages.md
index e042d8c..e038711 100644
--- a/docs/wskdeploy_packages.md
+++ b/docs/wskdeploy_packages.md
@@ -1,4 +1,9 @@
-# Working with packages
+# Packages
+
+The wskdeploy utility works primarily with the OpenWhisk **Package** resource as described in the [OpenWhisk Packaging Specification](https://github.com/apache/incubator-openwhisk-wskdeploy/tree/master/specification#openwhisk-packaging-specification).
+
+For convenience, the schema and grammar for declaring a **Package** can be found here:
+[https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_packages.md#packages](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/html/spec_packages.md#packages)
 
 ## Creating an OpenWhisk Package
 
@@ -8,22 +13,82 @@ The wskdeploy utility mainly uses a single file, that uses a YAML syntax, called
 The minimal manifest file would include only a package declaration, a version number and a license for the package:
 ```
 package:
-  name: helloworld
+  name: hello_world_package
   version: 1.0
   license: Apache-2.0
 ```
 
-Save this into a file called "manifest.yaml" in a directory of your choice.
+Save this into a file called ```"manifest.yaml"``` in a directory of your choice.
 
 ### Executing the wskdeploy utility
 Simply execute the wskdeploy binary against the directory you saved your "manifest.yaml" file in by pointing it to the package location using the ```-p``` flag.
 
-```
+```sh
 $ wskdeploy -p <my_directory>
 ```
-wskdeploy will automatically look for any file named "manifest.yaml" or "manifest.yml" in the directory it is pointed; however, the manifest file can be called anything as long as it has a .yaml or .yml extension and passed on the command line using the ```-m``` flag.
+wskdeploy will automatically look for any file named ```"manifest.yaml"``` or ```"manifest.yml"``` in the directory it is pointed; however, the _manifest file can be called anything_ as long as it has a .yaml or .yml extension and passed on the command line using the ```-m``` flag.
 
 For example, if you called your manifest "my_pkg_manifest.yml" you could simply provide the manifest file name as follows:
-```
+```sh
 $ wskdeploy -p <my_directory> -m my_pkg_manifest.yaml
 ```
+### Interactive mode
+
+if you want to simply verify your manifest is able to read and parse your manifest file, you can add the ```-i``` or ```--allow-interactive``` flag:
+
+```sh
+$ ./wskdeploy -i -m docs/examples/manifest_hello_world.yaml
+```
+
+and the utility will stop, show you all the OpenWhisk package components it will deploy and ask you if you want to deploy them or not.
+
+```sh
+Package:
+  name: hello_world_package
+  bindings:
+
+  * action: hello_world
+    bindings:
+    annotations:
+
+  Triggers:
+  Rules:
+
+Do you really want to deploy this? (y/N):
+```
+
+Now you can verify what the utility intends to deploy and decide whether to continue onto actual deployment with your chosen provider.
+
+#### Source code
+The source code for the manifest and JavaScript files can be found here:
+- [manifest_package_minimal.yaml](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/examples/manifest_package_minimal.yaml)
+
+## Common questions
+
+### What if ```wskdeploy``` finds an error in my manifest?
+
+- The ```wskdeploy``` utility will not attempt to deploy a package if an error in the manifest is detected, but will report as much information as it can to help you locate the error in the YAML file.
+
+### What if ```wskdeploy``` encounters an error during deployment?
+
+-  The ```wskdeploy``` utility will cease deploying as soon as it receives an error from the target platform and display what error information it receives to you.
+- then it will attempt to undeploy any entities that it attempted to deploy.
+  - If "interactive mode" was used to deploy, then you will be prompted to confirm you wish to undeploy.
+
+---
+
+When ready, you can navigate to the next example _'Creating a "hello world" package'_.
+<!--
+ Bottom Navigation
+-->
+<html>
+<div align="center">
+<table align="center">
+  <tr>
+    <td><a href="programming_guide.md#guided-examples">&lt;&lt;&nbsp;previous</a></td>
+    <td><a href="programming_guide.md#guided-examples">Index</a></td>
+    <td><a href="wskdeploy_hello_world.md#creating-a-hello-world-package">next&nbsp;&gt;&gt;</a></td>
+  </tr>
+</table>
+</div>
+</html>
diff --git a/specification/README.md b/specification/README.md
index 003457c..89318bd 100644
--- a/specification/README.md
+++ b/specification/README.md
@@ -2,44 +2,44 @@
 
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](http://www.apache.org/licenses/LICENSE-2.0)
 
-Current version (link):  [openwhisk_v0.8.8.pdf](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/openwhisk_v0.8.8.pdf)
+Current version (link):  [openwhisk_v0.8.9.pdf](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/openwhisk_v0.8.9.pdf)
 
 ## Purpose
 
-This specification defines two file artifacts, along with YAML schema, that are used to describe OpenWhisk Packages for deployment to a target OpenWhisk platform; these are:
+In general, the goal of this specification is to evolve a simple grammar to describe and deploy a complete OpenWhisk package without having to use any APIs.  Primarily, it is accomplished by coding a Package Manifest file and optionally a Deployment file using YAML.
 
-*	**Package Manifest file**: Contains the Package definition along with any included Action, Trigger or Rule definitions that comprise the package.  This file includes the schema of input and output data to each entity for validation purposes.
-*	**Deployment file**: Contains the values and bindings used configure a Package to a target OpenWhisk platform provider’s environment and supply input parameter values for Packages, Actions and Triggers.  This can include Namespace bindings, security and policy information.
+# Programming Guide
+
+If you want to learn how to write Packages and Applications by example using the specification and deploy them using the ```wskdeploy``` utility, please read the step-by-step guide:
+- "[wskdeploy utility by example](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/programming_guide.md#wskdeploy-utility-by-example)"
+
+# OpenWhisk Package Specification (HTML)
+
+Portions of the OpenWhisk Packaging Specification, for convenience, are made available here in HTML format. The canonical source for the specification is in PDF format and can be found within this directory.
+
+## Index
+
+- [Parameters](spec_parameters.md#parameters) - grammar, schema and examples for input and output parameters.
+- [Parameter Types](spec_types.md#parameter-types) - supported YAML and OpenWhisk Types.
+- [Shared Entity Schema](spec_shared_entity_schema.md#shared-entity-schema) - fields that are common among entities in the programming model.
+- [Packages](spec_packages.md#packages) - grammar, schema and examples for Packages.
+- [Actions](spec_actions.md#actions) - grammar, schema and examples for Actions.
+- [Triggers and Rules](spec_trigger_rule.md#triggers-and-rules) - grammar, schema and examples for Triggers and Rules.
+- [Sequences](spec_sequences.md#sequences) - shema to compose multiple Actions into a sequence.
+- [Normative & Non-normative References](spec_normative_refs.md)
+
+---
 
 ### Note
-This specification is under development and in draft status; therefore, it is subject to change during this development period.  We are posting this draft seeking review, comment, suggestions from the OpenWhisk and greater Serverless community including areas such as: model description and semantics, schema and grammar (YAML), end-user readability, concept explanations, use cases completeness, etc.  In general, mthe goal is to make the document a top-quality means to describe a complete  [...]
-
-## Contents
-
-The specification includes the following general sections:
-
-* Introduction
-* Programming model
-  * OpenWhisk Entities, Composition, Namespacing, Cardinality
-* Package Processing
-* Definitions
-* References
-* Specification
-  * Types, Schema and Artifacts
-* Scenarios and Use cases
-  * Usage Scenarios
-  * Schema use cases
-    * e.g., Hello world (variants), Basic Trigger and Rule, GitHub Feed, etc.
-* Event sources
-  * Curated Feeds, Public Sources
-* Other Considerations
-  * Tooling Interaction, Simplification of WebHook Integration, Enablement of Debugging and DevOps
-  
-## Formats
-
-Once the draft progresses further (i.e., known outstanding "high priority" design issues have been addressed), we will make the document available in markdown. 
+This specification is under development and in draft status; therefore, it is subject to change during this development period.  We are posting drafts seeking review, comments, suggestions and use cases from the OpenWhisk and greater Serverless community.
+
 ---
 
+## Package Manifest and Deployment files
+
+- **Package Manifest file**: Contains the Package definition along with any included Action, Trigger or Rule definitions that comprise the package.  This file includes the schema of input and output data to each entity for validation purposes.
+- **Deployment file**: Contains the values and bindings used configure a Package to a target OpenWhisk platform provider’s environment and supply input parameter values for Packages, Actions and Triggers.  This can include Namespace bindings, security and policy information.
+
 ### Conceptual Manifest and Deployment file usage
 
 The following images outline the basic process for creating and using both Manifest and Deployment files against a typical developer workstream:
@@ -47,5 +47,7 @@ The following images outline the basic process for creating and using both Manif
 #### Conceptual Manifest file creation
 ![Manifest file creation](images/OpenWhisk%20-%20Conceptual%20Manifest%20File%20Creation.png "image 1")
 
-#### Conceptual Manifest file deployment
+---
+
+### Conceptual Manifest file deployment
 ![Manifest file deployment](images/OpenWhisk%20-%20Conceptual%20Manifest%20File%20Deployment.png "image 1")
diff --git a/specification/openwhisk_v0.8.pdf b/specification/archive/openwhisk_v0.8.1.pdf
similarity index 100%
rename from specification/openwhisk_v0.8.pdf
rename to specification/archive/openwhisk_v0.8.1.pdf
diff --git a/specification/openwhisk_v0.8.2.pdf b/specification/archive/openwhisk_v0.8.2.pdf
similarity index 100%
rename from specification/openwhisk_v0.8.2.pdf
rename to specification/archive/openwhisk_v0.8.2.pdf
diff --git a/specification/openwhisk_v0.8.3.pdf b/specification/archive/openwhisk_v0.8.3.pdf
similarity index 100%
rename from specification/openwhisk_v0.8.3.pdf
rename to specification/archive/openwhisk_v0.8.3.pdf
diff --git a/specification/openwhisk_v0.8.4.pdf b/specification/archive/openwhisk_v0.8.4.pdf
similarity index 100%
rename from specification/openwhisk_v0.8.4.pdf
rename to specification/archive/openwhisk_v0.8.4.pdf
diff --git a/specification/openwhisk_v0.8.5.pdf b/specification/archive/openwhisk_v0.8.5.pdf
similarity index 100%
rename from specification/openwhisk_v0.8.5.pdf
rename to specification/archive/openwhisk_v0.8.5.pdf
diff --git a/specification/openwhisk_v0.8.6.pdf b/specification/archive/openwhisk_v0.8.6.pdf
similarity index 100%
rename from specification/openwhisk_v0.8.6.pdf
rename to specification/archive/openwhisk_v0.8.6.pdf
diff --git a/specification/openwhisk_v0.8.7.pdf b/specification/archive/openwhisk_v0.8.7.pdf
similarity index 100%
rename from specification/openwhisk_v0.8.7.pdf
rename to specification/archive/openwhisk_v0.8.7.pdf
diff --git a/specification/openwhisk_v0.8.8.pdf b/specification/archive/openwhisk_v0.8.8.pdf
similarity index 100%
rename from specification/openwhisk_v0.8.8.pdf
rename to specification/archive/openwhisk_v0.8.8.pdf
diff --git a/specification/html/spec_actions.md b/specification/html/spec_actions.md
new file mode 100644
index 0000000..f0e3c71
--- /dev/null
+++ b/specification/html/spec_actions.md
@@ -0,0 +1,349 @@
+## Actions
+
+The Action entity schema contains the necessary information to deploy an OpenWhisk function and define its deployment configurations, inputs and outputs.
+
+### Fields
+<html>
+<table>
+  <tr>
+   <th width="80">Key Name</th>
+   <th>Required</th>
+   <th>Value Type</th>
+   <th>Default</th>
+   <th>Description</th>
+  </tr>
+ <tr>
+  <td>version</td>
+  <td>no</td>
+  <td>version</td>
+  <td>N/A</td>
+  <td>The optional user-controlled version for the Action.</td>
+ </tr>
+ <tr>
+  <td>function</td>
+  <td>yes</td>
+  <td>string</td>
+  <td>N/A</td>
+  <td>Required source location (path inclusive) of the Action code either:
+    <ul>
+      <li>Relative to the Package manifest file.</li>
+      <li>Relative to the specified Repository.</li>
+    </ul>
+  </td>
+ </tr>
+ <tr>
+  <td>runtime</td>
+  <td>no</td>
+  <td>string</td>
+  <td>N/A</td>
+  <td>The required runtime name (and optional version) that the Action code requires for an execution environment.
+  <p><i>Note: May be optional if tooling allowed to make assumptions about file extensions.</i></p>
+  </td>
+ </tr>
+ <tr>
+  <td>inputs</td>
+  <td>no</td>
+  <td>list of parameter</td>
+  <td>N/A</td>
+  <td>The optional ordered list inputs to the Action.</td>
+ </tr>
+ <tr>
+  <td>outputs</td>
+  <td>no</td>
+  <td>list of parameter</td>
+  <td>N/A</td>
+  <td>The optional outputs from the Action.</td>
+ </tr>
+ <tr>
+  <td>limits</td>
+  <td>no</td>
+  <td>map of limit keys and values</a></td>
+  <td>N/A</td>
+  <td>Optional map of limit keys and their values.
+  <p><i>See section '</i><a href="#TABLE_LIMIT_KEYS"><i>Valid limit keys</i></a><i>' below for a listing of recognized keys and values.</i></p>
+  </td>
+ </tr>
+ <tr>
+  <td>feed</td>
+  <td>no</td>
+  <td>boolean</td>
+  <td>false</td>
+  <td>Optional indicator that the Action supports the required parameters (and operations) to be run as a Feed Action.</td>
+ </tr>
+ <tr>
+  <td>web-export</td>
+  <td>no</td>
+  <td>boolean</td>
+  <td>false</td>
+  <td>Optionally, turns the Action into a <a href="https://github.com/apache/incubator-openwhisk/blob/master/docs/webactions.md">&quot;<em><u>web actions</u></em>&quot;</a>
+  causing it to return HTTP content without use of an API Gateway.
+  </td>
+ </tr>
+</table>
+</html>
+
+### Requirements
+
+- The Action name (i.e., &lt;actionName&gt; MUST be less than or equal to 256 characters.
+- The Action entity schema includes all general <a href="#SCHEMA_ENTITY">Entity Schema</a> fields in addition to any fields declared above.
+- Supplying a runtime name without a version indicates that OpenWhisk SHOULD use the most current version.
+- Supplying a runtime <i>major version</i> without a <i>minor version</i> (et al.) indicates OpenWhisk SHOULD use the most current <i>minor version</i>.
+- Unrecognized limit keys (and their values) SHALL be ignored.
+- Invalid values for known limit keys SHALL result in an error.
+- If the Feed is a Feed Action (i.e., the feed key's value is set to true), it MUST support the following parameters:
+  - **lifecycleEvent**: one of 'CREATE', 'DELETE', 'PAUSE',or 'UNPAUSE'. These operation names MAY be supplied in lowercase (i.e., 'create',
+'delete', 'pause', etc.).
+  - **triggerName**: the fully-qualified name of the trigger which contains events produced from this feed.
+  - **authKey**: the Basic auth. credentials of the OpenWhisk user who owns the trigger.
+
+### Notes
+
+- Input and output parameters are implemented as JSON Objects within the OpenWhisk framework.
+- The maximum code size for an Action currently must be less than 48 MB.
+- The maximum payload size for an Action (i.e., POST content length or size) currently must be less than 1 MB.
+- The maximum parameter size for an Action currently must be less than 1 MB.
+- if no value for runtime is supplied, the value ‘language:default’ will be assumed.
+
+### Grammar
+
+```yaml
+<actionName>[.<type>]:
+  <Entity schema>
+  version: <version>
+  function: <string>
+  runtime: <name>[@<[range of ]version>]
+  inputs:
+    <list of parameter>
+  outputs:
+    <list of parameter>
+  limits:
+    <list of limit key-values>
+  feed: <boolean> # default: false
+  web-export: <boolean>
+```
+_**Note**: the optional [.<type>] grammar is used for naming Web Actions._
+
+### Example
+
+```yaml
+my_awesome_action:
+  version: 1.0
+  description: An awesome action written for node.js
+  function: src/js/action.js
+  runtime: nodejs@>0.12<6.0
+  inputs:
+    not_awesome_input_value:
+      description: Some input string that is boring
+      type: string
+  outputs:
+    awesome_output_value:
+      description: Impressive output string
+      type: string
+  limits:
+    memorySize: 512 kB
+    logSize: 5 MB
+```
+
+### Valid Runtime names
+
+The following runtime values are currently supported by the OpenWhisk platform.
+
+Each of these runtimes also include additional built-in packages (or libraries) that have been determined be useful for Actions surveyed and tested by the OpenWhisk platform.
+
+These packages may vary by OpenWhisk release; examples of supported runtimes as of this specification version include:
+
+<html>
+<table>
+
+  <tr>
+   <th>Runtime value</th>
+   <th>OpenWhisk kind</th>
+   <th>image name</th>
+   <th>Description</th>
+  </tr>
+
+ <tr>
+  <td>nodejs</td>
+  <td>nodejs</td>
+  <td>nodejsaction:latest</td>
+  <td>Latest NodeJS runtime</td>
+ </tr>
+ <tr>
+  <td>nodejs@6</td>
+  <td>nodejs:6</td>
+  <td>nodejs6action:latest</td>
+  <td>Latest NodeJS 6 runtime</td>
+ </tr>
+ <tr>
+  <td>java, java@8</td>
+  <td>java</td>
+  <td>java8action:latest</td>
+  <td>Latest Java language runtime</td>
+ </tr>
+ <tr>
+  <td>python, python@2</td>
+  <td>python:2</td>
+  <td>python2action:latest</td>
+  <td>Latest Python 2 language runtime</td>
+ </tr>
+ <tr>
+  <td>python@3</td>
+  <td>python:3</td>
+  <td>python3action:latest</td>
+  <td>Latest Python 3 language runtime</td>
+ </tr>
+ <tr>
+  <td>swift, swift@2</td>
+  <td>swift</td>
+  <td>swiftaction:latest</td>
+  <td>Latest Swift 2 language runtime</td>
+ </tr>
+ <tr>
+  <td>swift@3</td>
+  <td>swift:3</td>
+  <td>swift3action:latest</td>
+  <td>Latest Swift 3 language runtime</td>
+ </tr>
+ <tr>
+  <td>swift@3.1.1</td>
+  <td>swift:3.1.1</td>
+  <td>action-swift-v3.1.1:latest</td>
+  <td>Latest Swift 3.1.1 language runtime</td>
+ </tr>
+ <tr>
+  <td>php</td>
+  <td>php:7.1</td>
+  <td>action-php-v7.1:latest</td>
+  <td>Latest PHP language runtime</td>
+ </tr>
+ <tr>
+  <td>language:default</td>
+  <td>N/A</td>
+  <td>N/A</td>
+  <td>Permit the OpenWhisk platform to select the correct default language runtime.</td>
+ </tr>
+</table>
+</html>
+
+#### Notes
+- If no value for runtime is supplied, the value 'language:default' will be assumed.
+
+### Recognized File extensions
+
+Although it is best practice to provide a runtime value when declaring an Action, it is not required. In those cases, that a runtime is not provided, the package tooling will attempt to derive the correct runtime based upon the the file extension for the Action's function (source code file). The
+following file extensions are recognized and will be run on the latest version of corresponding Runtime listed below:
+
+<html>
+<table>
+  <tr>
+   <th>File extension</th>
+   <th>Runtime used</th>
+   <th>Description</th>
+  </tr>
+
+ <tr>
+  <td>.js</td>
+  <td>nodejs</td>
+  <td>Latest Node.js runtime.</td>
+ </tr>
+ <tr>
+  <td>.java</td>
+  <td>java</td>
+  <td>Latest Java language runtime.</td>
+ </tr>
+ <tr>
+  <td>.py</td>
+  <td>python</td>
+  <td>Latest Python language runtime.</td>
+ </tr>
+ <tr>
+  <td>.swift</td>
+  <td>swift</td>
+  <td>Latest Swift language runtime.</td>
+ </tr>
+ <tr>
+  <td>.php</td>
+  <td>php</td>
+  <td>Latest PHP language runtime.</td>
+ </tr>
+</table>
+</html>
+
+### Valid Limit keys
+
+<html>
+<table id="TABLE_LIMIT_KEYS">
+  <tr>
+   <th>Limit Keyname</th>
+   <th>Allowed values</th>
+   <th>Default value</th>
+   <th>Valid Range</th>
+   <th>Description</th>
+  </tr>
+
+ <tr>
+  <td>timeout</td>
+  <td>scalar-unit.time</td>
+  <td>60000 ms</td>
+  <td>[100 ms, 300000 ms]</td>
+  <td>The per-invocation Action timeout. Default unit is assumed to be milliseconds (ms).</td>
+ </tr>
+ <tr>
+  <td>memorySize</td>
+  <td>scalar-unit.size</td>
+  <td>256 MB</td>
+  <td>[128 MB, 512 MB]</td>
+  <td>The per-Action memory. Default unit is assumed to be in megabytes (MB).</p>
+  </td>
+ </tr>
+ <tr>
+  <td>logSize</td>
+  <td>scalar-unit.size</td>
+  <td>10 MB</td>
+  <td>[0 MB, 10 MB]</td>
+  <td>The action log size. Default unit is assumed to be in megabytes (MB).</td>
+ </tr>
+ <tr>
+  <td>concurrentActivations</td>
+  <td>integer</td>
+  <td>1000</td>
+  <td><i>See description</i></td>
+  <td>The maximum number of concurrent Action activations allowed (per-namespace). <p><i>Note: This value is not changeable via APIs at this time.</i></p></td>
+ </tr>
+ <tr>
+  <td>userInvocationRate</td>
+  <td>integer</td>
+  <td>5000</td>
+  <td><i>See description</i></td>
+  <td>The maximum number of Action invocations allowed per user, per minute. <p><i>Note: This value is not changeable via APIs at this time.</i></p></td>
+ </tr>
+ <tr>
+  <td>codeSize</td>
+  <td>scalar-unit.size</td>
+  <td>48 MB</td>
+  <td><i>See description</i></td>
+  <td>The maximum size of the Action code.<p><i>Note: This value is not changeable via APIs at this
+  time.</i></p></td>
+ </tr>
+ <tr>
+  <td>parameterSize</td>
+  <td>scalar-unit.size</td>
+  <td>1 MB</td>
+  <td><i>See description</i></td>
+  <td>The maximum size<p><i>Note: This value is not changeable via APIs at this time.</i></p></td>
+ </tr>
+</table>
+</html>
+
+#### Notes
+
+- The default values and ranges for limit configurations reflect the defaults for the OpenWhisk platform (open source code).&nbsp; These values may be changed over time to reflect the open source community consensus.
+
+### Web Actions
+OpenWhisk can turn any Action into a 'web action' causing it to return HTTP content without use of an API Gateway. Simply supply a supported 'type' extension to indicate which content type is to be returned and identified in the HTTP header (e.g., _.json_, _.html_, _.text_ or _.http_).
+
+Return values from the Action's function are used to construct the HTTP response. The following response parameters are supported in the response object.
+
+- **headers**: a JSON object where the keys are header-names and the values are string values for those headers (default is no headers).
+- **code**: a valid HTTP status code (default is 200 OK).
+- **body**: a string which is either plain text or a base64 encoded string (for binary data).
diff --git a/specification/html/spec_index.md b/specification/html/spec_index.md
new file mode 100644
index 0000000..a0a1366
--- /dev/null
+++ b/specification/html/spec_index.md
@@ -0,0 +1,18 @@
+# OpenWhisk Package Specification (HTML)
+
+Portions of the OpenWhisk Packaging Specification, for convenience, are made available here in HTML format. The canonical source for the specification is in PDF format and can be found within this repository:
+- [https://github.com/apache/incubator-openwhisk-wskdeploy/tree/master/specification](https://github.com/apache/incubator-openwhisk-wskdeploy/tree/master/specification)
+
+# Programming Guide
+If you want to learn how to write Packages and Applications using the specification and deploy them using the ```wskdeploy``` utility, please read the step-by-step guide:
+- "[wskdeploy utility by example](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/docs/programming_guide.md#wskdeploy-utility-by-example)"
+
+## Index
+- [Parameters](spec_parameters.md#parameters) - grammar, schema and examples for input and output parameters.
+- [Parameter Types](spec_types.md#parameter-types) - supported YAML and OpenWhisk Types.
+- [Shared Entity Schema](spec_shared_entity_schema.md#shared-entity-schema) - fields that are common among entities in the programming model.
+- [Packages](spec_packages.md#packages) - grammar, schema and examples for Packages.
+- [Actions](spec_actions.md#actions) - grammar, schema and examples for Actions.
+- [Triggers and Rules](spec_trigger_rule.md#triggers-and-rules) - grammar, schema and examples for Triggers and Rules.
+- [Sequences](spec_sequences.md#sequences) - shema to compose multiple Actions into a sequence.
+- [Normative & Non-normative References](spec_normative_refs.md)
diff --git a/specification/html/spec_packages.md b/specification/html/spec_packages.md
new file mode 100644
index 0000000..6f3b5b1
--- /dev/null
+++ b/specification/html/spec_packages.md
@@ -0,0 +1,168 @@
+## Packages
+
+The Package entity schema is used to define an OpenWhisk package within a manifest.
+
+### Fields
+<html>
+<table width="100%">
+ <tr>
+  <th width="16%">
+   <p>Key Name</p>
+  </th>
+  <th width="12%">
+   <p>Required</p>
+  </th>
+  <th width="16%">
+   <p>Value Type</p>
+  </th>
+  <td width="14%">
+   <p>Default</p>
+  </th>
+  <th width="40%">
+   <p>Description</p>
+  </th>
+ </tr>
+ <tr>
+  <td>version</td>
+  <td>yes</td>
+  <td><a href="spec_types_yaml.md#yaml-types">version</a></td>
+  <td>N/A</td>
+  <td>The required user-controlled version for the Package.</td>
+ </tr>
+ <tr>
+  <td>license</td>
+  <td>no</td>
+  <td>string</td>
+  <td>N/A</td>
+  <td>The required value that indicates the type of license the Package is governed by.
+   <p>The value is required to be a valid Linux-SPDX value. See <a href="https://spdx.org/licenses/">https://spdx.org/licenses/</a>.</p></td>
+ </tr>
+ <tr>
+  <td>credential</td>
+  <td>no</td>
+  <td>string</td>
+  <td>N/A</td>
+  <td>
+   <p>The optional Credential used for all entities within the Package.</p>
+   <p>The value contains either:</p>
+   <p>A credential string.</p>
+   <p>The optional name of a credential (e.g., token) that is defined elsewhere.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>dependencies</td>
+  <td>no</td>
+  <td>list of Dependency</td>
+  <td>N/A</td>
+  <td>The optional list of external OpenWhisk packages the manifest needs deployed before it can be deployed.</td>
+ </tr>
+ <tr>
+  <td>repositories</td>
+  <td>no</td>
+  <td>list of Repository</td>
+  <td>N/A</td>
+  <td>The optional list of external repositories that contain functions and other artifacts that can be found by tooling.</td>
+ </tr>
+ <tr>
+  <td>actions</td>
+  <td>no</td>
+  <td>list of Action</td>
+  <td>N/A</td>
+  <td>Optional list of OpenWhisk Action entity definitions.</td>
+ </tr>
+ <tr>
+  <td>sequences</td>
+  <td>no</td>
+  <td>list of Sequence</td>
+  <td>N/A</td>
+  <td>Optional list of OpenWhisk Sequence entity definitions.</td>
+ </tr>
+ <tr>
+  <td>triggers</td>
+  <td>no</td>
+  <td>list of Trigger</td>
+  <td>N/A</td>
+  <td>Optional list of OpenWhisk Trigger entity definitions.</td>
+ </tr>
+ <tr>
+  <td>rules</td>
+  <td>no</td>
+  <td>list of Rule</td>
+  <td>N/A</td>
+  <td>Optional list of OpenWhisk Rule entity definitions.</td>
+ </tr>
+ <tr>
+  <td>feeds</td>
+  <td>no</td>
+  <td>list of Feed</td>
+  <td>N/A</td>
+  <td>Optional list of OpenWhisk Feed entity definitions.</td>
+ </tr>
+ <tr>
+  <td>compositions</td>
+  <td>no</td>
+  <td>list of Composition</td>
+  <td>N/A</td>
+  <td>Optional list of OpenWhisk Composition entity definitions.</td>
+ </tr>
+ <tr>
+  <td>apis</td>
+  <td>no</td>
+  <td>list of API</td>
+  <td>N/A</td>
+  <td>Optional list of API entity definitions.</td>
+ </tr>
+</table>
+</html>
+
+### Grammar
+
+```yaml
+<packageName>:
+    version: <version>
+    license: <string>
+    repositories: <list of Repository>
+    actions: <list of Action>
+    sequences: <list of Sequence>
+    triggers: <list of Trigger>
+    rules: <list of Rule>
+    feeds: <list of Feed>
+    compositions: <list of Composition>
+    apis: <list of API>
+```
+
+### Example
+
+```yaml
+my_whisk_package:
+  description: A complete package for my awesome action to be deployed
+  version: 1.2.0
+  license: Apache-2.0
+  actions:
+    my_awsome_action:
+      <Action schema>
+  triggers:
+    trigger_for_awesome_action:
+      <Trigger schema>
+  rules:
+    rule_for_awesome_action>
+      <Rule schema>
+```
+
+### Requirements
+
+- The Package name MUST be less than or equal to 256 characters.
+- The Package entity schema includes all general <a href="#SCHEMA_ENTITY">Entity Schema</a> fields in addition to any fields declared above.
+- A valid Package license value MUST be one of the <a href="#REF_LINUX_SPDX">Linux SPDX</a> license values; for example: Apache-2.0 or GPL-2.0+, or the value 'unlicensed'.
+- Multiple (mixed) licenses MAY be described using using <a href="#REF_NPM_SPDX_SYNTAX">NPM SPDX license syntax</a>.
+- A valid Package entity MUST have one or more valid Actions defined.
+
+### Notes
+
+- Currently, the 'version' value is not stored in Apache OpenWhisk, but there are plans to support it in the future.
+- Currently, the 'license' value is not stored in Apache OpenWhisk, but there are plans to support it in the future.
+- The Trigger and API entities within the OpenWhisk programming model are considered outside the scope of the Package. This means that Trigger and API information will not be returned when using the OpenWhisk Package API:
+  - ```$ wsk package list <package name>```
+- However, their information may be retrieved using respectively:</li>
+  - ```$ wsk trigger list -v```
+  - ```$ wsk api list -v```
diff --git a/specification/html/spec_parameters.md b/specification/html/spec_parameters.md
new file mode 100644
index 0000000..0537245
--- /dev/null
+++ b/specification/html/spec_parameters.md
@@ -0,0 +1,244 @@
+# Parameters
+
+- [Dollar Notation ($)](#dollar-notation--schema-for-values)
+
+## Parameter schema
+The Parameter schema is used to define input and/or output data to be used by OpenWhisk entities for the purposes of validation.
+
+### Fields
+<html>
+<table width="100%">
+  <tr>
+   <th>Key Name</th>
+   <th>Required</th>
+   <th>Value Type</th>
+   <th>Default</th>
+   <th>Description</th>
+  </tr>
+ <tr>
+  <td>
+  <p>type</p>
+  </td>
+  <td>
+  <p>no</p>
+  </td>
+  <td>
+  <p>&lt;any&gt;</p>
+  </td>
+  <td>
+  <p>string</p>
+  </td>
+  <td>
+  <p>Optional valid type name or the parameter's value for validation purposes. By default, the type is string.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>description</p>
+  </td>
+  <td>
+  <p>no</p>
+  </td>
+  <td>
+  <p>string256</p>
+  </td>
+  <td>
+  <p>N/A</p>
+  </td>
+  <td>
+  <p>Optional description of the Parameter.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>value</p>
+  </td>
+  <td>
+  <p>no </p>
+  </td>
+  <td>
+  <p>&lt;any&gt;</p>
+  </td>
+  <td>
+  <p>N/A</p>
+  </td>
+  <td>
+  <p>The optional user supplied value for the parameter.</p>
+  <p>Note: this is not the default value, but an explicit declaration which allows simple usage of the Manifest file without a Deployment file.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>required</p>
+  </td>
+  <td>
+  <p>no</p>
+  </td>
+  <td>
+  <p>boolean</p>
+  </td>
+  <td>
+  <p>true</p>
+  </td>
+  <td>
+  <p>Optional indicator to declare the parameter as required (i.e., ```true```) or optional (i.e., ```false```).</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>default</p>
+  </td>
+  <td>
+  <p>no</p>
+  </td>
+  <td>
+  <p>&lt;any&gt;</p>
+  </td>
+  <td>
+  <p>N/A</p>
+  </td>
+  <td>
+  <p>Optional default value for the optional parameters. This value <b>MUST</b> be type compatible with the value declared on the parameter's type field.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>status</p>
+  </td>
+  <td>
+  <p>no</p>
+  </td>
+  <td>
+  <p>string</p>
+  </td>
+  <td>
+  <p>supported</p>
+  </td>
+  <td>
+  <p>Optional status of the parameter (e.g., deprecated, experimental). By default a parameter is without a declared status is considered supported.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>schema</p>
+  </td>
+  <td>
+  <p>no</p>
+  </td>
+  <td>
+  <p>&lt;schema&gt;</p>
+  </td>
+  <td>
+  <p>N/A</p>
+  </td>
+  <td>
+  <p>The optional schema if the 'type' key has the value 'schema'. The value would include a <b>Schema</b> <b>Object</b> (in YAML) as defined by the <a href="See%20https:/github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject">OpenAPI Specifcation v2.0</a>. This object is based upon the href="http://json-schema.org/">JSON Schema Specification.</a></p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>properties</p>
+  </td>
+  <td>
+  <p>no</p>
+  </td>
+  <td>
+  <p>&lt;list of parameter&gt;</p>
+  </td>
+  <td>
+  <p>N/A</p>
+  </td>
+  <td>
+  <p>The optional properties if the 'type' key has the value 'object'. Its value is a listing of Parameter schema from this specification.</p>
+  </td>
+ </tr>
+</table>
+</html>
+
+### Requirements
+
+The 'schema' key's value MUST be compatible with the value provided on both the 'type'  and 'value' keys; otherwise, it is considered an error.
+
+### Notes
+
+The 'type' key acknowledges some popular schema (e.g., JSON) to use when validating the value of the parameter. In the future additional (schema) types may be added for convenience.
+
+### Grammar
+
+#### Single-line
+```yaml
+```
+
+Where <YAML type> is inferred to be a YAML type as shown in the YAML Types section above (e.g., string, integer, float, boolean, etc.).
+
+If you wish the parser to validate against a different schema, then the multi-line grammar MUST be used where the value would be supplied on the keyname 'value' and the type (e.g., 'json') and/or schema (e.g., OpenAPI) can be supplied.
+
+#### Multi-line
+```yaml
+```
+
+### Status values
+
+<table width="100%">
+  <tr>
+   <td>
+   <p>Status Value</p>
+   </td>
+   <td>
+   <p>Description</p>
+   </td>
+  </tr>
+
+ <tr>
+  <td>
+  <p>supported (default)</p>
+  </td>
+  <td>
+  <p>Indicates the parameter is supported.&nbsp; This is the
+  implied default status value for all parameters.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>experimental</p>
+  </td>
+  <td>
+  <p>Indicates the parameter MAY be removed or changed in
+  future versions.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>deprecated</p>
+  </td>
+  <td>
+  <p>Indicates the parameter is no longer supported in the
+  current version and MAY be ignored.</p>
+  </td>
+ </tr>
+</table>
+
+## Dollar Notation ($) schema for values
+
+In a Manifest or Deployment file, a parameter value may be set from the local execution environment by using the dollar ($) notation to denote names of local environment variables which supply the value to be inserted at execution time.
+
+### Syntax
+```yaml
+<parameter>: $<local environment variable name>
+```
+
+### Example
+```yaml
+...
+  inputs:
+    userName: $DEFAULT_USERNAME
+```
+
+### Requirements
+
+- Processors or tooling that encounter ($) Dollar notation and are unable to locate the value in the execution environment SHOULD resolve the value to be the default value for the type (e.g., an empty string ("") for type 'string').
+
+### Notes
+
+- Processors or tooling that encounter ($) Dollar notation for values should attempt to locate the corresponding named variables set into the local execution environment (e.g., where the tool was invoked) and assign its value to the named input parameter for the OpenWhisk entity.
+- This specification does not currently consider using this notation for other than simple data types (i.e., we support this mechanism for values such as strings, integers, floats, etc.) at this time.
diff --git a/specification/html/spec_sequences.md b/specification/html/spec_sequences.md
new file mode 100644
index 0000000..0f6d3ca
--- /dev/null
+++ b/specification/html/spec_sequences.md
@@ -0,0 +1,59 @@
+## Sequences
+
+Actions can be composed into sequences to, in effect, form a new Action. The Sequence entity allows for a simple, convenient way to describe them in the Package Manifest.
+
+### Fields
+<html>
+<table>
+  <tr>
+   <th>Key Name</th>
+   <th>Required</th>
+   <th>Value Type</th>
+   <th>Default</th>
+   <td>Description</th>
+  </tr>
+ <tr>
+  <td>
+  <p>actions</p>
+  </td>
+  <td>
+  <p>yes</p>
+  </td>
+  <td>
+  <p>list of Action</p>
+  </td>
+  <td>
+  <p>N/A</p>
+  </td>
+  <td>
+  <p>The required list of two or more actions</p>
+  </td>
+ </tr>
+</table>
+</html>
+
+### Requirements
+
+- The comma separated list of Actions on the actions key SHALL imply the order of the sequence (from left, to right).
+- There MUST be two (2) or more actions declared in the sequence.
+
+### Notes
+
+- The sequences key exists for convenience; however, it is just one possible instance of a composition of Actions. The composition entity is provided for not only describing sequences, but also for other (future) compositions and additional information needed to compose them.&nbsp; For example, the composition entity allows for more complex mappings of input and output parameters between Actions.
+
+### Grammar
+
+```yaml
+sequences:
+  <sequence name>:
+     <Entity schema>
+     actions: <ordered list of action names>
+  ...
+```
+
+### Example
+```yaml
+sequences:
+  newbot:
+    actions: newbot-create, newbot-select-persona, newbot-greeting
+```
diff --git a/specification/html/spec_shared_entity_schema.md b/specification/html/spec_shared_entity_schema.md
new file mode 100644
index 0000000..f0a3a1c
--- /dev/null
+++ b/specification/html/spec_shared_entity_schema.md
@@ -0,0 +1,90 @@
+## Shared Entity Schema
+
+The Entity Schema contains fields that are common (shared) to all OpenWhisk entities (e.g., Actions, Triggers, Rules, etc.).
+
+### Fields
+
+<html>
+<table>
+
+  <tr>
+   <th>Key Name</th>
+   <th>Required</th>
+   <th>Value Type</th>
+   <th>Default</th>
+   <th>Description</th>
+  </tr>
+
+ <tr>
+  <td>
+  <p>description</p>
+  </td>
+  <td>
+  <p>no</p>
+  </td>
+  <td>
+  <p>string256</p>
+  </td>
+  <td>
+  <p>N/A</p>
+  </td>
+  <td>
+  <p>The optional description for the Entity.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>displayName</p>
+  </td>
+  <td>
+  <p>no</p>
+  </td>
+  <td>
+  <p>string16</p>
+  </td>
+  <td>
+  <p>N/A</p>
+  </td>
+  <td>
+  <p>This is the optional name that will be displayed on small form-factor devices.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>annotations</p>
+  </td>
+  <td>
+  <p>no</p>
+  </td>
+  <td>
+  <p>map of
+  <string></p>
+  </td>
+  <td>
+  <p>N/A</p>
+  </td>
+  <td>
+  <p>The optional annotations for the Entity.</p>
+  </td>
+ </tr>
+</table>
+</html>
+
+### Grammar
+```yaml
+description: <string256>
+displayName: <string16>
+annotations: <map of <string>>
+```
+
+### Requirements
+- Non-required fields MAY be stored as ÒannotationsÓ within the OpenWhisk framework after they have been used for processing.
+- Description string values SHALL be limited to 256 characters.
+- DisplayName string values SHALL be limited to 16 characters.
+- Annotations MAY be ignored by target consumers of the Manifest file as they are considered data non-essential to the deployment of management of OpenWhisk entities themselves.
+- Target consumers MAY preserve (persist) these values, but are not required to.
+- For any OpenWhisk Entity, the maximum size of all Annotations SHALL be 256 characters.
+
+### Notes
+- Several, non-normative Annotation keynames and allowed values for (principally for User Interface (UI) design) may be defined below for optional usage.
+
diff --git a/specification/html/spec_trigger_rule.md b/specification/html/spec_trigger_rule.md
new file mode 100644
index 0000000..d37b801
--- /dev/null
+++ b/specification/html/spec_trigger_rule.md
@@ -0,0 +1,222 @@
+## Triggers and Rules
+
+- [Triggers](#triggers)
+- [Rules](#rules)
+
+## Triggers
+
+The Trigger entity schema contains the necessary information to describe the stream of events that it represents. For more information, see the document "[Creating Triggers and Rules](https://github.com/apache/incubator-openwhisk/blob/master/docs/triggers_rules.md)".
+
+### Fields
+<html>
+<table>
+  <tr>
+   <th>Key Name</th>
+   <th>Required</th>
+   <th>Value Type</th>
+   <th>Default</th>
+   <th>Description</th>
+  </tr>
+
+ <tr>
+  <td>
+  <p>feed</p>
+  </td>
+  <td>
+  <p>no</p>
+  </td>
+  <td>
+  <p>string</p>
+  </td>
+  <td>
+  <p>N/A</p>
+  </td>
+  <td>
+  <p>The optional name of the Feed associated with the Trigger.
+  </p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>credential</p>
+  </td>
+  <td>
+  <p>no</p>
+  </td>
+  <td>
+  <p>Credential</p>
+  </td>
+  <td>
+  <p>N/A</p>
+  </td>
+  <td>
+  <p>The optional credential used to acces the feed service.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>inputs</p>
+  </td>
+  <td>
+  <p>no</p>
+  </td>
+  <td>
+  <p>list of</p>
+  <p>parameter</p>
+  </td>
+  <td>
+  <p>N/A</p>
+  </td>
+  <td>
+  <p>The optional ordered list inputs to the feed.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>events</p>
+  <p><i>&nbsp;</i></p>
+  </td>
+  <td>
+  <p>no</p>
+  </td>
+  <td>list of Event</td>
+  <td>
+  <p>N/A</p>
+  </td>
+  <td>The optional list of valid Event schema the trigger supports. OpenWhisk would validate incoming Event data for conformance against any Event schema declared under this key.
+  <p><b><i>Note</i></b><i>: This feature is <u>not supported at
+  this time</u>. This is viewed as a possible feature that may be
+  implemented along with configurable options for handling of invalid events.</i></p></td>
+ </tr>
+</table>
+</html>
+
+### Requirements
+
+The Trigger name (i.e., <triggerName> MUST be less than or equal to 256 characters.
+
+The Trigger entity schema includes all general [Entity Schema](#TBD) fields in addition to any fields
+declared above.
+
+### Notes
+
+- The 'events' key name is not supported at this time.</p>
+- The Trigger entity within the OpenWhisk programming model is considered outside the scope of the Package (although there are discussions about changing this in the future). This means that Trigger and API information will not be returned when using the OpenWhisk Package API:
+  -  ```$ wsk package list <package name>```
+- However, it may be obtained using the Trigger API:
+  - ```$ wsk trigger list -v
+
+### Grammar
+```yaml
+<triggerName>:
+  <Entity schema>
+  feed: <feed name>
+  credential: <Credential>
+  inputs:
+    <list of parameter>
+```
+
+### Example
+```yaml
+triggers:
+  everyhour:
+    feed: /whisk.system/alarms/alarm
+```
+
+---
+
+## Rules
+
+The Rule entity schema contains the information necessary to associates one trigger with one action, with every firing of the trigger causing the corresponding action to be invoked with the trigger event as input. For more information, see the document "[Creating Triggers and Rules](https://github.com/apache/incubator-openwhisk/blob/master/docs/triggers_rules.md)".
+
+### Fields
+<html>
+<table>
+  <tr>
+   <th>Key Name</th>
+   <th>Required</th>
+   <th>Value Type</th>
+   <th>Default</th>
+   <th>Description</th>
+  </tr>
+
+ <tr>
+  <td>
+  <p>trigger</p>
+  </td>
+  <td>
+  <p>yes</p>
+  </td>
+  <td>
+  <p>string</p>
+  </td>
+  <td>
+  <p>N/A</p>
+  </td>
+  <td>
+  <p>Required name of the Trigger the Rule applies to.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>action</p>
+  </td>
+  <td>
+  <p>yes</p>
+  </td>
+  <td>
+  <p>string</p>
+  </td>
+  <td>
+  <p>N/A</p>
+  </td>
+  <td>
+  <p>Required name of the Action the Rule applies to.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>rule</p>
+  </td>
+  <td>
+  <p>no</p>
+  </td>
+  <td>
+  <p>regex</p>
+  </td>
+  <td>
+  <p>true</p>
+  </td>
+  <td>
+  <p>The optional regular expression that determines if the Action is fired.</p>
+  <p><i>Note: In this version of the specification, only the expression 'true' is currently supported.</i></p>
+  </td>
+ </tr>
+</table>
+</html>
+
+### Requirements
+- The Rule name (i.e., <ruleName>) MUST be less than or equal to 256 characters.
+- The Rule entity schema includes all general [Entity Schem](#TBD) fields in addition to any fields
+declared above.
+
+### Notes
+- OpenWhisk only supports a value of '```true```' for the '```rule```' key's value at this time.
+
+### Grammar
+```yaml
+<ruleName>:
+  description: <string>
+  trigger: <string>
+  action: <string>
+  rule: <regex>
+```
+
+### Example
+
+```yaml
+my_rule:
+  description: Enable events for my Action
+  trigger: my_trigger
+  action: my_action
+```
diff --git a/specification/html/spec_types.md b/specification/html/spec_types.md
new file mode 100644
index 0000000..3f621d8
--- /dev/null
+++ b/specification/html/spec_types.md
@@ -0,0 +1,391 @@
+# Parameter Types
+
+- [YAML Types](#yaml-types)
+- [OpenWhisk Types](#openwhisk-types)
+  - [scalar-unit Types](#scalar-unit-types)
+
+<!--
+********************************
+  YAML Types
+********************************
+-->
+
+## YAML Types
+
+Many of the types we use in this profile are <i>built-in</i> types from the [YAML 1.2 specification](http://www.yaml.org/spec/1.2/spec.html) (i.e., those identified by the 'tag:yaml.org,2002' version tag).
+
+The following table declares the valid YAML type URIs and aliases that SHALL be used when defining parameters or properties within an
+OpenWhisk package manifest:
+
+<html>
+<table width="100%">
+ <tr>
+  <th width=20%>Type Name</th>
+  <th width=30%>Type URI</th>
+  <th width=50%>Notes</th>
+ </tr>
+ <tr>
+  <td>
+  <p><a>string</a></p>
+  </td>
+  <td>
+  <p>tag:yaml.org,2002:str (default)</p>
+  </td>
+  <td>
+  <p>Default type if no type provided</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p><a>integer</a></p>
+  </td>
+  <td>
+  <p>tag:yaml.org,2002:int</p>
+  </td>
+  <td>
+  <p>Signed. Includes large integers (i.e., long type)</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p><a>float</a></p>
+  </td>
+  <td>
+  <p>tag:yaml.org,2002:float</p>
+  </td>
+  <td>
+  <p>Signed. Includes large floating point values (i.e., double type)</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p><a>boolean</a></p>
+  </td>
+  <td>
+  <p>tag:yaml.org,2002:bool</p>
+  </td>
+  <td>
+  <p>This specification uses lowercase 'true' and lowercase 'false'</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p><a>timestamp</a></p>
+  </td>
+  <td>
+  <p>tag:yaml.org,2002:timestamp (see <a href="spec_normative_refs.md#normative-references">YAML-TS-1.1</a>)</p>
+  </td>
+  <td>
+  <p>ISO 8601 compatible.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p><a>null</a></p>
+  </td>
+  <td>
+  <p>tag:yaml.org,2002:null</p>
+  </td>
+  <td>
+  <p>Different meaning than an empty string, map, list, etc.</p>
+  </td>
+ </tr>
+</table>
+</html>
+
+### Requirements
+- The 'string' type SHALL be the default type when not specified on a parameter or property declaration.
+- All 'boolean' values SHALL be lowercased (i.e., 'true' or 'false').
+
+<!--
+********************************
+  OpenWhisk Types
+********************************
+-->
+
+## OpenWhisk Types
+In addition to the YAML built-in types, OpenWhisk supports the types listed in the table below. A complete description of each of these types is provided below.
+
+<html>
+<table width="100%">
+ <tr>
+  <th width=20%>Type Name</th>
+  <th width=30%>Description</th>
+  <th width=50%>Notes</th>
+ </tr>
+ <tr>
+  <td>
+  <p>version</p>
+  </td>
+  <td>
+  <p>tag:maven.apache.org:version (see <a href="spec_normative_refs.md#normative-references">Maven version</a>)</p>
+  </td>
+  <td>
+  <p>Typically found in modern tooling (i.e., 'package@version' or 'package:version' format).</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p><a>string256</a></p>
+  </td>
+  <td>
+  <p>long length strings (e.g., descriptions)</p>
+  </td>
+  <td>
+  <p>A string type limited to 256 characters.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p><a>string64</a></p>
+  </td>
+  <td>
+  <p>medium length strings (e.g., abstracts, hover text)</p>
+  </td>
+  <td>
+  <p>A string type limited to 64 characters.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p><a>string16</a></p>
+  </td>
+  <td>
+  <p>short length strings (e.g., small form-factor list displays)</p>
+  </td>
+  <td>
+  <p>A string type limited to 16 characters.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>json</p>
+  </td>
+  <td>
+  <p>The parameter value represents a JavaScript Object Notation (JSON) data object.</p>
+  </td>
+  <td>
+  <p>The deploy tool will validate the corresponding parameter value against JSON schema.</p>
+  <p>Note: The implied schema for JSON the JSON Schema (see <a href="http://json-schema.org/)">http://json-schema.org/</a>).</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>scalar-unit</p>
+  </td>
+  <td>
+  <p>Convenience type for declaring common scalars that have an associated unit. For example, '10 msec.', '2 Gb', etc.)</p>
+  </td>
+  <td>
+  <p>Currently, the following scalar-unit subtypes are supported:</p>
+  <ul>
+  <li>scalar-unit.size</li>
+  <li>scalar-unit.time</li>
+  </ul>
+  <p>See description below for details.</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>schema</p>
+  </td>
+  <td>
+  <p>The parameter itself is an OpenAPI Specifcation v2.0 <b>Schema
+  Object</b> (in YAML formatt) with self-defining schema.</p>
+  </td>
+  <td>
+  <p>The schema declaration follows the <a href="#REF_SWAGGER_2_0">OpenAPI</a> v2.0 specification for Schema Objects (YAML format).</p>
+  <p>Specifically, see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schemaObject</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>object</p>
+  </td>
+  <td>
+  <p>The parameter itself is an object with the associated
+  defined Parameters (schemas). </p>
+  </td>
+  <td>
+  <p>Parameters of this type would include a declaration of its
+  constituting Parameter schema.</p>
+  </td>
+ </tr>
+</table>
+</html>
+
+<!--
+********************************
+  scalar-unit types
+********************************
+-->
+### scalar-unit types
+Scalar-unit types can be used to define scalar values along with a unit from the list of recognized units (a subset of GNU units) provided below.
+
+### Grammar
+```yaml
+<scalar> <unit>
+```
+
+### Example
+```yaml
+inputs:
+  max_storage_size:
+    type: scalar-unit.size
+    default: 10 GB
+  archive_period:
+    type: scalar-unit.time
+    default: 30 d
+```
+
+### Requirements
+
+- **Whitespace**: any number of spaces (including zero or none) SHALL be allowed between the scalar value and the unit value.
+- It SHALL be considered an error if either the scalar or unit portion is missing on a property or attribute declaration derived from any scalar-unit type.
+
+### scalar-unit.size
+
+### Recognized units for sizes (i.e., scalar-unit.size)
+<html>
+<table width="100%">
+
+  <tr>
+   <th>Unit</th>
+   <th>Description</th>
+  </tr>
+
+ <tr>
+  <td>
+  <p>B</p>
+  </td>
+  <td>
+  <p>byte</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>kB</p>
+  </td>
+  <td>
+  <p>kilobyte (1000 bytes)</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>MB</p>
+  </td>
+  <td>
+  <p>megabyte (1000000 bytes)</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>GB</p>
+  </td>
+  <td>
+  <p>gigabyte (1000000000 bytes)</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>TB</p>
+  </td>
+  <td>
+  <p>terabyte (1000000000000 bytes)</p>
+  </td>
+ </tr>
+</table>
+</html>
+
+### Example
+```yaml
+inputs:
+  memory_size:
+    type: scalar-unit.size
+    value: 256 MB
+```
+
+### scalar-unit.time
+
+#### Recognized units for times (i.e., scalar-unit.time)
+<html>
+<table>
+  <tr>
+   <th width="20%">
+   <p>Unit</p>
+   </th>
+   <th width="80%">
+   <p>Description</p>
+   </th>
+  </tr>
+
+ <tr>
+  <td>
+  <p>d</p>
+  </td>
+  <td>
+  <p>days</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>h</p>
+  </td>
+  <td>
+  <p>hours</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>m</p>
+  </td>
+  <td>
+  <p>minutes</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>s</p>
+  </td>
+  <td>
+  <p>seconds</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>ms</p>
+  </td>
+  <td>
+  <p>milliseconds</p>
+  </td>
+ </tr>
+ <tr>
+  <td>
+  <p>us</p>
+  </td>
+  <td>
+  <p>microseconds</p>
+  </td>
+ </tr>
+</table>
+
+</html>
+
+### Example
+```yaml
+inputs:
+  max_execution_time:
+    type: scalar-unit.time
+    value: 600 s
+```
+
+### Object type example
+
+The Object type allows for complex objects to be declared as parameters with an optional validatable schema.
+
+```yaml
+inputs:
+  person:
+    type: object
+    parameters: <schema>
+```
diff --git a/specification/html/spec_types_yaml.md b/specification/html/spec_types_yaml.md
deleted file mode 100644
index 9cb7fd8..0000000
--- a/specification/html/spec_types_yaml.md
+++ /dev/null
@@ -1,139 +0,0 @@
-<h2>YAML Types</H2>
-
-<p>Many of the types we use in this profile are <i>built-in</i> types from the <a
-href="http://www.yaml.org/spec/1.2/spec.html">YAML 1.2 specification</a>
-(i.e., those identified by the 'tag:yaml.org,2002' version tag). </p>
-
-<p>The following table declares the valid YAML type URIs and
-aliases that SHALL be used when defining parameters or properties within an
-OpenWhisk package manifest:<a> </a></p>
-
-<table width="100%">
- <th>
-  <th>
-  <p>Type Name</p>
-  </th>
-  <th>
-  <p>Type URI</p>
-  </th>
-  <th>
-  <p>Notes</p>
-  </th>
- </tr>
- <tr>
-  <td>
-  <p><a>string</a></p>
-  </td>
-  <td>
-  <p>tag:yaml.org,2002:str (default)</p>
-  </td>
-  <td>
-  <p>Default type if no type provided</p>
-  </td>
- </tr>
- <tr>
-  <td>
-  <p><a>integer</a></p>
-  </td>
-  <td>
-  <p>tag:yaml.org,2002:int</p>
-  </td>
-  <td>
-  <p>Signed. Includes large integers (i.e., long type)</p>
-  </td>
- </tr>
- <tr>
-  <td>
-  <p><a>float</a></p>
-  </td>
-  <td>
-  <p>tag:yaml.org,2002:float</p>
-  </td>
-  <td>
-  <p>Signed. Includes large floating point values (i.e., double type)</p>
-  </td>
- </tr>
- <tr>
-  <td>
-  <p><a>boolean</a></p>
-  </td>
-  <td>
-  <p>tag:yaml.org,2002:bool</p>
-  </td>
-  <td>
-  <p>This specification uses lowercase 'true' and lowercase 'false'</p>
-  </td>
- </tr>
- <tr>
-  <td>
-  <p><a>timestamp</a></p>
-  </td>
-  <td>
-  <p>tag:yaml.org,2002:timestamp (see <a href="spec_normative_refs.md">YAML-TS-1.1</a>)</p>
-  </td>
-  <td>
-  <p>ISO 8601 compatible.</p>
-  </td>
- </tr>
- <tr>
-  <td>
-  <p><a>null</a></p>
-  </td>
-  <td>
-  <p>tag:yaml.org,2002:null</p>
-  </td>
-  <td>
-  <p>Different meaning than an empty string, map, list, etc.</p>
-  </td>
- </tr>
- <tr>
-  <td>
-  <p>version</p>
-  </td>
-  <td>
-  <p>tag:maven.apache.org:version (see <a href="spec_normative_refs.md">Maven version</a>)</p>
-  </td>
-  <td>
-  <p>Typically found in modern tooling (i.e., 'package@version' or 'package:version' format).</p>
-  </td>
- </tr>
- <tr>
-  <td>
-  <p><a>string256</a></p>
-  </td>
-  <td>
-  <p>long length strings (e.g., descriptions)</p>
-  </td>
-  <td>
-  <p>A string type limited to 256 characters.</p>
-  </td>
- </tr>
- <tr>
-  <td>
-  <p><a>string64</a></p>
-  </td>
-  <td>
-  <p>medium length strings (e.g., abstracts, hover text)</p>
-  </td>
-  <td>
-  <p>A string type limited to 64 characters.</p>
-  </td>
- </tr>
- <tr>
-  <td>
-  <p><a>string16</a></p>
-  </td>
-  <td>
-  <p>short length strings (e.g., small form-factor list displays)</p>
-  </td>
-  <td>
-  <p>A string type limited to 16 characters.</p>
-  </td>
- </tr>
-</table>
-
-<h4>Requirements</h4>
-<ul>
-<li>The 'string' type SHALL be the default type when not specified on a parameter or property declaration.</li>
-<li>All 'boolean' values SHALL be lowercased (i.e., 'true' or 'false').</li>
-</ul>

-- 
To stop receiving notification emails like this one, please contact
['"commits@openwhisk.apache.org" <commits@openwhisk.apache.org>'].

Mime
View raw message