You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@openwhisk.apache.org by GitBox <gi...@apache.org> on 2018/06/01 20:35:23 UTC
[GitHub] houshengbo closed pull request #948: Transition specification to
markdown/html and move all PDFs under archive dir.
houshengbo closed pull request #948: Transition specification to markdown/html and move all PDFs under archive dir.
URL: https://github.com/apache/incubator-openwhisk-wskdeploy/pull/948
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/specification/README.md b/specification/README.md
index 4f088e36..f15176c8 100644
--- a/specification/README.md
+++ b/specification/README.md
@@ -21,52 +21,59 @@
[](http://www.apache.org/licenses/LICENSE-2.0)
-Current version (link): [openwhisk_v0.9.1.pdf](https://github.com/apache/incubator-openwhisk-wskdeploy/blob/master/specification/openwhisk_v0.9.1.pdf)
-
## Purpose
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.
+The ```wskdeploy``` utility is the reference implementation of this specification for the Apache OpenWhisk project.
+
+---
+
# 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](../docs/programming_guide.md#wskdeploy-utility-by-example)"
-# OpenWhisk Package Specification (HTML)
+---
+
+# Package Specification
-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.
+The majority of the OpenWhisk Packaging Specification, for convenience, is made available here in Markdown/HTML format. The canonical source for all versions is in PDF format and can be found within the [archive](archive) directory.
-## Index
+#### Notational Conventions
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC
+2119](http://www.ietf.org/rfc/rfc2119.txt).
+
+### Index
+
+#### Overview
+- [Introduction](html/spec_intro.md#introduction) - an overview of the goals for the packaging specification.
+- [Compatibility](html/spec_intro.md#compatibility) - describes intent to be compatible with other standards.
+- [Programming model](html/spec_programming_model.md#programming-model) - an overview of the OpenWhisk programming model.
+- [Package processing](html/spec_package_processing.md#package-processing) - describes how the developers can use Package Manifests and Deployment files with the ```wskdeploy``` utility.
+- [Grammar](html/spec_grammar.md#grammar) - describes the YAML grammar the specification builds upon.
+
+#### Schema
+- [Parameter Types](html/spec_parameter_types.md#parameter-types) - supported YAML and OpenWhisk Types.
- [Parameters](html/spec_parameters.md#parameters) - grammar, schema and examples for input and output parameters.
-- [Parameter Types](html/spec_types.md#parameter-types) - supported YAML and OpenWhisk Types.
-- [Shared Entity Schema](html/spec_shared_entity_schema.md#shared-entity-schema) - fields that are common among entities in the programming model.
+- [Entity Schema](html/spec_shared_entity_schema.md#shared-entity-schema) - keys that are common to all entities in the programming model.
+- [Entity Naming & Namespacing](html/spec_entity_naming_and_namespacing.md#naming-and-namespacing) - describes what characters can be used to name Packages, Actions, Triggers and Rules and how to manage them with namespaces.
- [Packages](html/spec_packages.md#packages) - grammar, schema and examples for Packages.
- [Actions](html/spec_actions.md#actions) - grammar, schema and examples for Actions.
- [Triggers and Rules](html/spec_trigger_rule.md#triggers-and-rules) - grammar, schema and examples for Triggers and Rules.
- [Sequences](html/spec_sequences.md#sequences) - shema to compose multiple Actions into a sequence.
-- [Normative & Non-normative References](html/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 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:
+#### References
+- [Normative & Non-normative References](html/spec_normative_refs.md)
+- [Definitions](html/spec_definitions.md#definitions) - defines terms that are used in the specification.
+- [Revision History](html/spec_history.md#revision-history) - lists changes to specification by version/revision.
-#### Conceptual Manifest file creation
-
+#### License
+The OpenWhisk packaging specification is licensed under [The Apache License,
+Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).
---
-### Conceptual Manifest file deployment
-
+### Disclaimer
+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.
diff --git a/specification/openwhisk_v0.9.1.pdf b/specification/archive/openwhisk_v0.9.1.pdf
similarity index 100%
rename from specification/openwhisk_v0.9.1.pdf
rename to specification/archive/openwhisk_v0.9.1.pdf
diff --git a/specification/openwhisk_v0.9.2.pdf b/specification/archive/openwhisk_v0.9.2.pdf
similarity index 100%
rename from specification/openwhisk_v0.9.2.pdf
rename to specification/archive/openwhisk_v0.9.2.pdf
diff --git a/specification/images/OpenWhisk - Conceptual Manifest File Creation.png b/specification/html/images/conceptual_manifest_file_creation.png
similarity index 100%
rename from specification/images/OpenWhisk - Conceptual Manifest File Creation.png
rename to specification/html/images/conceptual_manifest_file_creation.png
diff --git a/specification/images/OpenWhisk - Conceptual Manifest File Deployment.png b/specification/html/images/conceptual_manifest_file_deployment.png
similarity index 100%
rename from specification/images/OpenWhisk - Conceptual Manifest File Deployment.png
rename to specification/html/images/conceptual_manifest_file_deployment.png
diff --git a/specification/html/images/conceptual_programming_model.png b/specification/html/images/conceptual_programming_model.png
new file mode 100644
index 00000000..f6595932
Binary files /dev/null and b/specification/html/images/conceptual_programming_model.png differ
diff --git a/specification/images/images.md b/specification/html/images/images.md
similarity index 100%
rename from specification/images/images.md
rename to specification/html/images/images.md
diff --git a/specification/html/spec_definitions.md b/specification/html/spec_definitions.md
new file mode 100644
index 00000000..0e3236c9
--- /dev/null
+++ b/specification/html/spec_definitions.md
@@ -0,0 +1,47 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+### Definitions
+
+#### Activation
+
+An invocation or “run” of an action results in an activation record that
+is identified by a unique activation ID. The term Activation is
+short-hand for the creation of this record and its information.
+
+#### Repository
+
+A location that provides storage for sets of files, as well as the
+history of changes made to those files.
+
+#### Project
+
+A description of a software application which enables management of its
+design, implementation, source control, monitoring and testing.
+
+#### Application
+
+A computer program designed to perform a group of coordinated functions,
+tasks, or activities to achieve some result or user benefit.
+
+#### \[Cloud\] Service
+
+Any resource, including a functional task, that is provided over the
+Internet. This includes delivery models such as *Platform as a Service*
+(PaaS), *Infrastructure as a* Service (IaaS), as well as *Serverless*.
diff --git a/specification/html/spec_entity_naming_and_namespacing.md b/specification/html/spec_entity_naming_and_namespacing.md
new file mode 100644
index 00000000..6c7c8f30
--- /dev/null
+++ b/specification/html/spec_entity_naming_and_namespacing.md
@@ -0,0 +1,65 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## Naming and Namespacing
+
+### Namespacing
+
+Every OpenWhisk entity (i.e., Actions, Feeds, Triggers), including
+packages, belongs in a *namespace.*
+
+The fully qualified name of any entity has the format:
+
+ -------------------------------------------------------------------
+ /<namespaceName>\[/<packageName>\]/<entityName>
+ -------------------------------------------------------------------
+
+The namespace is typically provided at bind-time by the user deploying
+the package to their chosen OpenWhisk platform provider.
+
+#### Requirements
+
+- The “/whisk.system“ namespace is reserved for entities that are
+ distributed with the OpenWhisk system.
+
+### Entity Names
+
+The names of all entities, including actions, triggers, rules, packages,
+and namespaces, are a sequence of characters that follow the following
+format:
+
+- The first character SHALL be an alphanumeric character, a digit, or
+ an underscore.
+
+- The subsequent characters MAY be alphanumeric, digits, spaces, or
+ any of the following:
+
+> \_, @, ., -
+
+- The last character SHALL NOT be a space.
+
+- The maximum name length of any entity name is 256 characters (i.e.,
+ ENTITY\_NAME\_MAX\_LENGTH = 256).
+
+Valid entity names are described with the following regular expression
+(Java metacharacter syntax):
+
+ -------------------------------------------------------------------------------------
+ "\\A(\[\\w\]|\[\\w\]\[\\w@ .-\]{0,\${ENTITY\_NAME\_MAX\_LENGTH - 2}}\[\\w@.-\])\\z"
+ -------------------------------------------------------------------------------------
diff --git a/specification/html/spec_grammar.md b/specification/html/spec_grammar.md
new file mode 100644
index 00000000..c17bff97
--- /dev/null
+++ b/specification/html/spec_grammar.md
@@ -0,0 +1,22 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## Grammar
+
+This specification utilizes the [YAML language](#REF_YAML_1_2), a superset of JSON, which supports key features for packaging descriptors and configuration information such as built-in data types, complex data types, anchors (relational information), files, comments and can embed other data formats such as JSON and XML easily.
diff --git a/specification/html/spec_history.md b/specification/html/spec_history.md
new file mode 100644
index 00000000..a1dd8d23
--- /dev/null
+++ b/specification/html/spec_history.md
@@ -0,0 +1,130 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## Revision History
+
+ ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ Version Date Notes
+ --------- ------------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+ 0.8.1 2016-11-03 Initial public point draft, Working Draft 01
+
+ 0.8.2 2016-12-12 Working Draft 02, Add. Use cases, examples
+
+ 0.8.3 2017-02-02 Working Draft 03, Add use cases, examples, \$ notation
+
+ 0.8.4 2017-04-18 Working Draft 04,
+
+ Support JSON parameter type;
+
+ Clarify use of Parameter single-line grammar and inferred types.
+
+ Add support for API Gateway mappings.
+
+ Add support for Web Actions
+
+ 0.8.5 2017-04-21 Add support for “dependencies”, that is allow automatic deployment of other OpenWhisk packages (from GitHub) that the current package declares as a dependency.
+
+ 0.8.6 2017-07-25 - Clarified requirements for \$ dollar notation.
+
+ - Updated conceptual Manifest/Deployment File processing images.
+
+
+ 0.8.7 2017-08-24 - Added explicit Application entity and grammar.
+
+ - Added API listing to Package entity.
+
+ - Cleaned up pseudo-grammar which contained various uses of credentials in places not intended.
+
+ - Fixed Polygon Tracking example (indentation incorrect).
+
+
+ 0.8.8 2017-08-29 - Created a simplified API entity (i.e., “api”) grammar that allows multiple sets of named APIs for the same basepath.
+
+ - Acknowledge PHP as supported runtime (kind).
+
+ - Added “sequences” entity as a convenient way to declare action sequences in the manifest. Updated supported runtime values.
+
+
+ 0.8.9, 2017-09-22 - Clarified “version” key requirements for Package (required) and Action (optional); removed from shared entity schema.
+
+ 0.8.9.1 2017-09-29 - Made “license” key optional for package.
+
+ - keyword “package” (singular) and “packages” (plural) both allowed.
+
+ - Adjusted use case examples to reflect these changes.
+
+ - Rework of schema use cases into full, step-by-step examples.
+
+ - Spellcheck, fixed bugs, update examples to match web-based version.
+
+
+ 0.8.9.1 2017-10-06 - Added grammar and example for concatenating string values on input parameters using environment variables.
+
+
+ 0.9.0, 2017-11-23, - Identified new user scenarios including: clean, refresh, sync, pre/post processing
+
+ 0.9.1 2017-11-30 - Clarified “runtime” field on Action is equivalent to “kind” parameter used on the Apache OpenWhisk CLI for Actions.
+
+ - Added “project” key as an synonym name for “application”.” key, moving application to become deprecated. Project name made required.
+
+ - Support “public” (i.e., publish) key on Package.
+
+ - Documented support for the “raw-http” annotation under Action.
+
+ - Documented support for the “final” annotation under Action.
+
+ - Documented support for the “main” field under Action.
+
+ - Dollar Notation section becomes Interpolation / updates
+
+ - Supported beyond Parameter values
+
+ - Package names can be interpolated
+
+ - Annotations values can be interpolated
+
+ - Multiple replacements supported in same value
+
+ - Usage scenarios 6-8 added, i.e., Clean, Project Sync, Tool chain support.
+
+
+ 0.9.2 2018-02-05 - Fixed and clarified the allowed values for “web-export” on Action.
+
+ - Clarified use of “final” on Action.
+
+ - Added support (planned) for “web-custom-options” and “require-whisk-auth. ” flags on Actions (annotations)
+
+ - Deprecate ‘application’ and ‘package’ completely (no longer supported).
+
+
+ 0.9.2.2 2018-04-04 - Allow “web” key as an overload for “web-export” key for to indicate Web Actions.
+
+ - Added Web Sequences, specify a sequence is a Web Action.
+
+ - Added support for Conductor Actions, to align with OpenWhisk CLI support.
+
+ - Added “docker” and “native” binary support under Action.
+
+ - Added in-line “code” support under Action.
+
+ - Support \$\$, double-dollar notation for string literals on parameter values.
+
+ - Added support for “default” package (allowing all entities to be assigned directly under the user’s default namespace), that is not requiring a package name to be created.
+
+ ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
diff --git a/specification/html/spec_intro.md b/specification/html/spec_intro.md
new file mode 100644
index 00000000..9b1b2ff8
--- /dev/null
+++ b/specification/html/spec_intro.md
@@ -0,0 +1,58 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+# Introduction
+
+Apache OpenWhisk™ is an open source, distributed Serverless computing
+project.
+
+Specifically, it is able to execute application logic (*Actions*) in
+response to events (*Triggers*) from external sources (*Feeds*) governed
+by simple conditional logic (*Rules*) around the event data.
+
+It provides a programming model for registering and managing *Actions*,
+*Triggers* and *Rules* supported by a REST-based Command Line Interface
+(CLI) along with tooling to support packaging and catalog services.
+
+The project includes a catalog of built-in system and utility *Actions*
+and *Feeds*, along with a robust set of samples that demonstrate how to
+integrate OpenWhisk with various external service providers (e.g.,
+GitHub, Slack, etc.) along with several platform and run-time Software
+Development Kits (SDKs).
+
+The code for the Actions, along with any support services implementing
+*Feeds*, are packaged according to this specification to be compatible
+with the OpenWhisk catalog and its tooling. It also serves as a means
+for architects and developers to model OpenWhisk package Actions as part
+of full, event-driven services and applications providing the necessary
+information for artifact and data type validation along with package
+management operations.
+
+### Compatibility
+
+This specification is intended to be compatible with the following
+specifications:
+
+- *OpenWhisk API which is defined as an OpenAPI document: *
+
+ - <https://raw.githubusercontent.com/openwhisk/openwhisk/master/core/controller/src/main/resources/whiskswagger.json>
+
+- *OpenAPI Specification when defining REST APIs and parameters:*
+
+ - <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md>
diff --git a/specification/html/spec_package_processing.md b/specification/html/spec_package_processing.md
new file mode 100644
index 00000000..26b7bdb8
--- /dev/null
+++ b/specification/html/spec_package_processing.md
@@ -0,0 +1,55 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## Package processing
+
+This document defines two file artifacts that are used to deploy
+Packages to a target OpenWhisk platform; these include:
+
+- ***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*** (optional): 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.
+
+#### Notes
+
+- _Deployment files are optional_. Deployment can be fully accomplished
+ with simply a Manifest File.
+
+
+### Conceptual Package creation and publishing
+
+The following diagram illustrates how a developer would create OpenWhisk
+code artifacts and associate a Package Manifest file that describes them
+for deployment and reuse.
+
+
+
+### Conceptual tooling integration and deployment
+
+The following diagram illustrates how Package manifests can be leveraged
+by developer tooling to integrate OpenWhisk Serverless functions.
+
+
diff --git a/specification/html/spec_parameter_types.md b/specification/html/spec_parameter_types.md
new file mode 100644
index 00000000..b1e86e8c
--- /dev/null
+++ b/specification/html/spec_parameter_types.md
@@ -0,0 +1,165 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+# Parameter Types
+
+- [YAML Types](#yaml-types)
+- [OpenWhisk Types](#openwhisk-types)
+ - [scalar-unit Types](#scalar-unit-types)
+
+---
+
+#### YAML Types
+
+Many of the types we use in this profile are *built-in* 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:
+
+| Type Name | Type URI | Notes |
+|:---|:---|:---|
+| string | tag:yaml.org,2002:str (default) | Default type if no type provided |
+| integer | tag:yaml.org,2002:int | Signed. Includes large integers (i.e., long type) |
+| float | tag:yaml.org,2002:float | Signed. Includes large floating point values (i.e., double type) |
+| boolean | tag:yaml.org,2002:bool | This specification uses lowercase ‘true’ and lowercase ‘false’ |
+| timestamp | tag:yaml.org,2002:timestamp | ISO 8601 compatible timestamp. See [YAML-TS-1.1](spec_normative_refs.md) |
+| null | tag:yaml.org,2002:null | Different meaning than an empty string, map, list, etc. |
+
+#### 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’).
+- The case (lower, upper) of the Unit’s value is considered significant and SHALL be preserved. For example, the Unit value “kB” is not the same as “KB” or “kb”.
+
+### 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.
+
+| Type Name | Description | Notes |
+|:---|:---|:---|
+| version | tag:maven.apache.org:version | Typically found in modern tooling (i.e., 'package@version' or 'package:version' format). Aligns with Maven format principles, but is a simplification of Maven spec. considerations. See [Maven version](spec_normative_refs.md#normative-references"). |
+| string256 | long length strings (e.g., descriptions) | A string type limited to 256 characters. |
+| string64 | medium length strings (e.g., abstracts, hover text) | A string type limited to 64 characters. |
+| string16 | short length strings (e.g., small form-factor list displays) | A string type limited to 16 characters. |
+| json | The parameter value represents a JavaScript Object Notation (JSON) data object. | The deploy tool will validate the corresponding parameter value against JSON schema.</br></br>Note: The implied schema for JSON the JSON Schema (see http://json-schema.org/). |
+| scalar-unit | Convenience type for declaring common scalars that have an associated unit. For example, “10 msec.”, “2 Gb”, etc.) | Currently, the following scalar-unit subtypes are supported: ```scalar-unit.size```, ```scalar-unit.time```. |
+| schema | The parameter itself is an OpenAPI Specification v2.0 **Schema Object** (in YAML format) with self-defining schema. | The schema declaration follows the [OpenAPI](spec_normative_refs.md#normative-references") v2.0 specification for Schema Objects (YAML format). |
+| object | The parameter itself is an object with the associated defined Parameters (schemas). | Parameters of this type would include a declaration of its constituting Parameter schema. |
+
+#### 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
+
+```
+<scalar> <unit>
+```
+
+In the above grammar, the pseudo values that appear in angle brackets
+have the following meaning:
+- scalar: is a *required* scalar value (e.g., integer).
+- unit: is a *required* unit value. The unit value MUST be
+ type-compatible with the scalar value.
+
+##### 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.
+
+##### Recognized units for sizes (i.e., scalar-unit.size)
+
+
+| Unit | Description |
+|:---|:---|
+| B | byte |
+| kB | kilobyte (1000 bytes) |
+| MB | megabyte (1000000 bytes) |
+| GB | gigabyte (1000000000 bytes) |
+| TB | terabyte (1000000000000 bytes) |
+
+##### Example
+
+```yaml
+inputs:
+ memory_size:
+ type: scalar-unit.size
+ value: 256 MB
+```
+
+##### Recognized units for times (i.e., scalar-unit.time)
+
+| Unit | Description |
+|:---|:---|
+| d | days |
+| h | hours |
+| m | minutes |
+| s | seconds |
+| ms | milliseconds |
+| us | microseconds |
+
+##### 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 validateable schema.
+
+```yaml
+inputs:
+ person:
+ type: object
+ parameters:
+ <Parameter schema>
+```
+
+<!--
+ Bottom Navigation
+-->
+---
+<html>
+<div align="center">
+<table align="center">
+ <tr>
+ <!-- <td><a href=""><< previous</a></td> -->
+ <td><a href="spec_index.md#openwhisk-package-specification-html">Specification Index</a></td>
+ <!-- <td><a href="">next >></a></td> -->
+ </tr>
+</table>
+</div>
+</html>
diff --git a/specification/html/spec_programming_model.md b/specification/html/spec_programming_model.md
new file mode 100644
index 00000000..2476357c
--- /dev/null
+++ b/specification/html/spec_programming_model.md
@@ -0,0 +1,92 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## Programming model
+
+### OpenWhisk Entities
+
+OpenWhisk uses the following entities to describe its programming model:
+
+#### Action
+
+A stateless, relatively short-running function (*on the order of seconds
+or even milliseconds*) invoked as an event handler.
+
+#### Trigger
+
+The name for a class of events. Triggers represent the events (and their
+data) themselves without any concept of how they were generated.
+
+#### Rule
+
+A mapping from a Trigger to an Action which may contain simple
+conditional logic. OpenWhisk evaluates incoming events (that belong to a
+Trigger) and invokes the assigned Action (event handler).
+
+#### Event Source
+
+An Event Source is the descriptor (edge) for an Event Producer (or
+provider). It describes the Event Format(s) produced, as well as any
+configuration and subscription capabilities.
+
+#### Feed
+
+A Feed is an optional service that represents and controls the stream
+which all belong to a Trigger. A feed provides operations called **feed
+actions** which handle creating, deleting, pausing, and resuming the
+stream of events. The feed action typically interacts with external
+services which produce the events
+
+#### Package
+
+A named, shared collection of Actions and Feeds. The goal of this
+specification is to describe OpenWhisk packages and their component
+entities and resources to enable an open-ecosystem.
+
+*Packages are designed to be first-class entities within the OpenWhisk
+platform to be used by tooling such as catalogs (repositories),
+associated package managers, installers, etc.*
+
+*Note: Not all actions must belong to packages, but can exist under a
+namespace.*
+
+### Action Composition
+
+#### Action Sequence
+
+An Action that is a sequenced composition of 2 or more existing Actions.
+The Action Sequence can be viewed as a named pipe where OpenWhisk can
+automatically take the output of a first Action ‘A’ in a declared
+sequence and provides it as input to the next Action ‘B’ in the sequence
+and so on until the sequence completes.
+
+*Note: This composition technique allows the reuse of existing action
+implementations treating them as “building blocks” for other Actions.*
+
+### Cardinality
+
+#### Trigger to Action
+
+With the appropriate set of Rules, it's possible for a single Trigger
+(event) to invoke multiple Actions, or for an Action to be invoked as a
+response to events from multiple Triggers.
+
+### Conceptual representation
+
+
diff --git a/specification/html/spec_types.md b/specification/html/spec_types.md
deleted file mode 100644
index 5b0bdbd5..00000000
--- a/specification/html/spec_types.md
+++ /dev/null
@@ -1,426 +0,0 @@
-<!--
-#
-# Licensed to the Apache Software Foundation (ASF) under one or more
-# contributor license agreements. See the NOTICE file distributed with
-# this work for additional information regarding copyright ownership.
-# The ASF licenses this file to You under the Apache License, Version 2.0
-# (the "License"); you may not use this file except in compliance with
-# the License. You may obtain a copy of the License at
-#
-# http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-#
--->
-
-# 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>
-```
-
-<!--
- Bottom Navigation
--->
----
-<html>
-<div align="center">
-<table align="center">
- <tr>
- <!-- <td><a href=""><< previous</a></td> -->
- <td><a href="spec_index.md#openwhisk-package-specification-html">Specification Index</a></td>
- <!-- <td><a href="">next >></a></td> -->
- </tr>
-</table>
-</div>
-</html>
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
With regards,
Apache Git Services