Updated to version 0.3.0

Documentation

.vscode/settings.json

@@ -0,0 +1,12 @@
+{
+    "cSpell.words": [
+        "cmdb",
+        "initialisation",
+        "Qaskx",
+        "rediops",
+        "synchronised"
+    ],
+    "cSpell.ignoreWords": [
+        "apip"
+    ]
+}

background.md

@@ -1,9 +1,4 @@
+# Background
 
+_This document is under construction_
 
-
-```mermaid
-
-mindmaps
-    
-
-```

docs/analysis_start.md

@@ -0,0 +1,94 @@
+# Analysis flow (start)
+
+
+The assumptions for this documents are:
+
+* the Git repository has been created and contains little content
+* a new API is required to be exposed
+* no OpenAPI definition exists
+* no API coding has commenced
+* ApiCurio is the OpenAPI editor, and this has been linked to GitHub
+
+It is beneficial if the objectives for the API and its high level
+service domain scope have already been agreed before starting 
+to define the API.
+
+Knowing the information to fetch or tasks that need to be performed
+will assist in completing the API specification.  This information 
+could be captured in the API specification so as to avoid duplicate 
+sources of information that needs to be synchronised.
+
+Information in the OpenAPI specification can be extracted and rendered
+into various formats, such as CSV lists of fields, their types,
+size and description.
+
+## Sequence Diagram
+
+```mermaid
+---
+title: Business Analyst task flow
+---
+sequenceDiagram
+
+    actor ba as Business Analyst
+    participant ide as ApiCurio
+    participant git as Github
+    participant oas3f as OpenAPI file
+
+    Note over git, oas3f: The OpenAPI file is stored in Git
+
+    ba ->>+ ide: start IDE
+
+    ide ->> ide: Create new API
+    Note over ba, oas3f: New API is to meet naming standards for services
+    ide ->> ide: Create new data structures
+    Note over ba, oas3f: Data structures include requests and responses
+    ide ->> ide: Create new paths and methods
+    Note over ba, oas3f: Includes non 200 response handling, headers and security
+    
+    ide ->>+ git: Commit to git
+    git ->>+ oas3f: OpenAPI file under Git
+    oas3f -->>- git: Saved
+    git --) git: Trigger GitActions for lint
+    git -->>- ide: 
+
+    ide -->>- ba: close
+
+```
+
+When creating the OpenAPI specification the information to include:
+* Summary and abstract
+* Version
+* Descriptions for fields
+* Field attributes including mandatory, type, enumeration and rules such as size
+* Descriptions for paths
+
+A lint process will be run over the OpenAPI specification to ensure adherence
+to styling standards.
+
+# End Status of flow
+
+At the end of this flow the OpenAPI (and/or AsyncAPI) specification will 
+be in a stable state so that coding can commence.  Minor changes to the 
+specification can still occur, and completely new paths can be added.
+
+When the specification changes the version will change according
+to semantic versioning rules.  
+
+The OpenAPI definition generated is next used in the 
+[developer client start](developer_client_start.md) or
+[developer server start](developer_server_start.md) flow.
+
+The client will need to consume a mock service until the
+server code is built.
+
+# Reading Notes
+
+Further automation can be achieved by GitActions calling
+qaskx-cli, such as registering the OpenAPI specification in the 
+devops file.
+
+The ApiCurio and Github components can be substituted for 
+other software products uch as Swagger Editor and Bitbucket 
+that provide similar capabilities.
+

docs/config/dot_qaskx.md

@@ -0,0 +1,29 @@
+# .qaskx file
+
+The .qaskx (dotqaskx) file is normally located in 
+your home directory. The file is a basic, short
+configuration file for items that are shared 
+across projects, such as your Git details.
+
+A sample file is:
+
+```json
+{
+    "GitProvider": "git",
+    "GitHost": "https://tea.example.com",
+    "GitApi": "https://tea.example.com/api/v1",
+    "GitOrg": "Wardrobe",
+    "GitRepoUser": "meerkat",
+    "GitBranch": "main",
+    "GitUserEmail": "meerkat@example.com",
+    "Organisation": "Witch & Wardrobe",
+    "TemplateHost": "",
+    "TemplateFolder": "Xtreme/Folder/Template",
+    "Name": "Sir Meerkat",
+    "ServiceOwner": "Meerkat team, Sydney",
+    "ServiceOwnerEmail": "Meerkat.Team@example.com",
+    "PrimaryProgramLanguage": "go",
+    "LintApiLevel": ""
+}
+```
+

docs/developer_client_start.md

@@ -0,0 +1,210 @@
+# Front end client developer flow (start)
+
+This is the initialisation of the front end 
+client code.  Coding the server is covered in document
+[developers server start](developers_server_start.md)
+
+The [analysis start](analysis_start.md) is a pre-requisite for
+this flow.
+
+The assumptions for this documents are:
+
+* the Git repository has been created
+* a new API is required to be exposed
+* an OpenAPI definition exists in Git
+* no API coding has commenced
+* Visual Studio Code has been installed
+* Developer has access to the API editor viewer for the OpenAPI specification
+
+## Sequence Diagram
+
+### Automation
+
+The sequence of automation activity using **devops** file and **qaskx-cli** is 
+as follows.
+
+The Qaskx command line tool needs to be installed on the developer machine
+
+```mermaid
+---
+title: Client development task flow
+---
+sequenceDiagram
+
+    actor dev as Developer
+    participant vsc as Visual Studio Code
+    participant term as Terminal
+    participant qaskx as qaskx-cli
+    participant cmdb as CMDB
+    participant git as Github
+    link git: GitHub @ https://github.com/meerkat-manor/devops
+    participant oas3f as OpenAPI file
+    participant devops as devops file
+    participant apip as API portal
+
+    dev ->>+ vsc: start IDE
+
+    Note over vsc, term: Clone existing git for project
+    vsc ->>+ git : 
+    git -->>- vsc : Cloned, project opened
+
+    Note over git, devops: The OpenAPI and devops files are stored in Git
+
+    alt If no OpenAPI dependency linked
+    vsc -) devops: Update OpenAPI dependency entry
+    end
+
+    vsc ->>+ term: start
+    term ->>+ qaskx: New CMDB CI
+    qaskx ->>+ devops: Read 
+    devops -->>- qaskx: Contents
+    loop Read called dependencies
+    qaskx ->>+ oas3f: Read dependency
+    oas3f -->>- qaskx: Contents
+    end
+    Note over cmdb, git: qaskx-cli rediops cmdb cmd
+    qaskx ->>+ cmdb: 
+    cmdb -->>- qaskx: New CMDB CI value
+    qaskx -) devops: Update CMDB CI entry
+    qaskx -->>- term: Success
+
+    term ->>+ qaskx: Generate code
+    Note over qaskx, cmdb: qaskx-cli gen client cmd
+    qaskx ->>+ devops: Read dependency list
+    devops -->>- qaskx: Contents
+    loop Read called dependencies
+    qaskx ->>+ oas3f: Read dependency
+    oas3f -->>- qaskx: Contents
+    qaskx -) qaskx: Auto generate client code
+    end
+    qaskx -) qaskx: Auto generate sequence diagram
+    qaskx -) qaskx: Auto generate feature flags
+    qaskx -) devops: Auto update entries, including build, test
+    qaskx -->>- term: Success
+
+    alt Register using API dependencies if not already done
+
+    term ->>+ qaskx: Register API dependencies
+    Note over cmdb, git: qaskx-cli rediops register cmd
+    qaskx ->>+ devops: Read 
+    devops -->>- qaskx: Contents
+    loop Read called dependencies
+    qaskx ->>+ oas3f: Read 
+    oas3f -->>- qaskx: Contents
+    qaskx ->>+ apip: 
+    apip -->>- qaskx: Registered as consumer
+    end
+    qaskx -) devops: Auto update API entry
+    qaskx -->>- term: Success
+
+    end
+
+    term -->- vsc: close
+
+    rect lightgrey
+    Note over vsc, qaskx: Developer codes to use the OpenAPI definition, with base code in place
+    vsc -->> vsc: Code update
+    vsc -->> vsc: Local build
+    vsc -->> vsc: Local test
+    end 
+
+    vsc ->>+ git: Commit
+    git --) git: Trigger GitActions for lint, gateway, features, etc 
+    git ->>- vsc: Success
+
+    vsc -->>- dev: close
+
+```
+
+### Manual
+
+The equivalent sequence of manual activity, non qaskx actions is as follows.
+The **devops** file is still used.  Without **devops** file you will 
+follow whatever your existing process is and recorded the necessary 
+details in various documents
+
+The OpenAPI tool needs to be installed on the developer machine.
+
+```mermaid
+---
+title: Client development task flow
+---
+sequenceDiagram
+
+    actor dev as Developer
+    participant vsc as Visual Studio Code
+    participant cmdb as CMDB
+    link vsc: Visual Studio @ https://code.visualstudio.com/
+    participant term as Terminal
+    participant git as Github
+    link git: GitHub @ https://github.com/meerkat-manor/devops
+    participant oas3f as OpenAPI file
+    participant devops as devops file
+    participant oas3 as OpenAPI tool
+    participant apip as API portal
+
+
+    Note over cmdb, vsc: Create new CMDB CI entry for Client  
+    dev ->>+ cmdb: Access UI
+    cmdb -->> cmdb: Create CMDB CI entry
+    cmdb -->>- dev: Close, noting CI value
+
+    Note over git, devops: The devops file is stored in Git
+
+    dev ->>+ vsc: start IDE
+
+    Note over cmdb, vsc: Clone existing git for project
+    vsc ->>+ git : 
+    git -->>- vsc : Cloned, project opened
+
+    vsc -) devops: Update CMDB CI entry
+
+    vsc ->>+ term: start
+    Note over git, oas3: Set generation parameters
+    term ->>+ oas3: Generate code cmd
+    oas3 ->>+ oas3f: Read 
+    oas3f -->>- oas3: Contents
+    oas3 -->>- term: Success
+    term -->- vsc: close
+
+    vsc -) vsc: Update client code with defaults
+    vsc -) vsc: Manually write sequence diagrams
+    vsc -) vsc: Manually write Gateway infra
+    vsc -) vsc: Manually write feature flags
+
+    alt Register using API dependencies if not already done
+
+    dev ->>+ apip: Register as consuming APIs
+    apip -->>- dev: Registered
+
+    end
+
+    vsc -) devops: Manually update entries
+
+    vsc ->>+ git: Commit
+    git --) git: Trigger GitActions for lint, gateway, features, etc 
+    git ->>- vsc: Success
+
+    vsc -->>- dev: Done
+
+
+```
+
+# End Status of flow
+
+At the end of this flow the basic code stubs exist and have been committed
+to Github.  The code can execute and will return not implemented
+response results if the client is a non UI, headless consumer of the API.
+
+For clients that will have a UI, the code will not work as no UI coding is
+expected to have been done.
+
+
+# Reading Notes
+
+For automation, some activities can be performed by GitActions calling
+qaskx-cli.
+
+The Visual Studio Code, CMDB and Github components can be substituted for 
+other software products such IntelliJ and Bitbucket.
+

docs/developer_server_start.md

@@ -0,0 +1,239 @@
+# Back end server developer flow (start)
+
+This is the initialisation of the back end 
+code.  Coding the client is covered in document
+[developers client start](developers_client_start.md)
+
+The [analysis start](analysis_start.md) is a pre-requisite for
+this flow.
+
+The assumptions for this documents are:
+
+* the Git repository has been created
+* a new API is required to be exposed
+* an OpenAPI definition exists in Git
+* no API coding has commenced
+* Visual Studio Code has been installed
+* Developer has access to the API editor viewer for the OpenAPI specification
+
+
+## Sequence Diagram
+
+### Automation
+
+The sequence of automation activity using **devops** file and **qaskx-cli** is 
+as follows.
+
+**A server can also be a consumer of other APIs in which case it needs to generate
+when downstream API specifications client code.**
+
+The Qaskx command line tool needs to be installed on the developer machine
+
+```mermaid
+---
+title: Server development task flow
+---
+sequenceDiagram
+
+    actor dev as Developer
+    participant vsc as Visual Studio Code
+    participant term as Terminal
+    participant qaskx as qaskx-cli
+    participant cmdb as CMDB
+    participant git as Github
+    link git: GitHub @ https://github.com/meerkat-manor/devops
+    participant oas3f as OpenAPI file
+    participant devops as devops file
+    participant apip as API portal
+
+    dev ->>+ vsc: start IDE
+
+    Note over vsc, term: Clone existing git for project
+    vsc ->>+ git : 
+    git -->>- vsc : Cloned, project opened
+
+    Note over git, devops: The OpenAPI and devops files are stored in Git
+
+    vsc ->>+ term: start
+    term ->>+ qaskx: New CMDB CI
+    qaskx ->>+ devops: Read 
+    devops -->>- qaskx: Contents
+
+    alt If no OpenAPI linked
+    qaskx ->>+ git:  
+    Note over oas3f, devops: qaskx-cli rediops scan cmd
+    Note over oas3f, devops: Scan for OpenAPI file in Git
+    git -->>- qaskx: 
+    qaskx -) devops: Update OpenAPI entry
+    end
+
+    qaskx ->>+ oas3f: Read 
+    oas3f -->>- qaskx: Contents
+    Note over cmdb, git: qaskx-cli rediops cmdb cmd
+    qaskx ->>+ cmdb: 
+    cmdb -->>- qaskx: New CMDB CI value
+    qaskx -) devops: Update CI entry
+    qaskx -->>- term: Success
+
+    term ->>+ qaskx: Generate code
+    Note over qaskx, cmdb: qaskx-cli gen server cmd
+    qaskx ->>+ devops: Read 
+    devops -->>- qaskx: Contents
+
+    alt If no OpenAPI linked
+    qaskx ->>+ git:  
+    Note over oas3f, devops: qaskx-cli rediops scan cmd
+    Note over oas3f, devops: Scan for OpenAPI file in Git
+    git -->>- qaskx: 
+    qaskx -) devops: Update OpenAPI entry
+    end
+
+    qaskx ->>+ oas3f: Read 
+    oas3f -->>- qaskx: Contents
+    qaskx -) qaskx: Auto generate server code
+    qaskx -) qaskx: Auto generate sequence diagram
+    qaskx -) qaskx: Auto generate gateway infra
+    qaskx -) qaskx: Auto generate feature flags
+    qaskx -) devops: Auto update entries, including build, test
+    qaskx -->>- term: Success
+
+    opt
+
+    term ->>+ qaskx: Generate code
+    Note over qaskx, cmdb: qaskx-cli gen client cmd
+    qaskx ->>+ devops: Read dependency list
+    devops -->>- qaskx: Contents
+    loop Read called dependencies
+    qaskx ->>+ oas3f: Read dependency
+    oas3f -->>- qaskx: Contents
+    qaskx -) qaskx: Auto generate client code
+    end
+    qaskx -->>- term: Success
+
+    end
+
+    rect lightgrey
+    Note over vsc, qaskx: Developer codes to use the OpenAPI definition, with base code in place
+    vsc -->> vsc: Code update
+    vsc -->> vsc: Local build
+    vsc -->> vsc: Local test
+    end 
+
+    alt Register API if not already done
+
+    term ->>+ qaskx: Register API
+    Note over cmdb, git: qaskx-cli rediops register cmd
+    qaskx ->>+ devops: Read 
+    devops -->>- qaskx: Contents
+    qaskx ->>+ oas3f: Read 
+    oas3f -->>- qaskx: Contents
+    qaskx ->>+ apip: 
+    apip -->>- qaskx: Registered
+    qaskx -) devops: Auto update API entry
+    qaskx -->>- term: Success
+
+    end
+
+    term -->- vsc: close
+
+    vsc ->>+ git: Commit
+    git --) git: Trigger GitActions for lint, gateway, features, etc 
+    git ->>- vsc: Success
+
+    vsc -->>- dev: close
+
+```
+
+### Manual
+
+The equivalent sequence of manual activity, non qaskx actions is as follows.
+The **devops** file is still used. Without **devops** file you will 
+follow whatever your existing process is and recorded the necessary 
+details in various documents
+
+The OpenAPI tool needs to be installed on the developer machine.
+
+```mermaid
+---
+title: Server development task flow
+---
+sequenceDiagram
+
+    actor dev as Developer
+    participant vsc as Visual Studio Code
+    participant cmdb as CMDB
+    link vsc: Visual Studio @ https://code.visualstudio.com/
+    participant term as Terminal
+    participant git as Github
+    link git: GitHub @ https://github.com/meerkat-manor/devops
+    participant oas3f as OpenAPI file
+    participant devops as devops file
+    participant oas3 as OpenAPI tool
+    participant apip as API portal
+
+
+    Note over cmdb, vsc: Create new CMDB CI entry for API 
+    dev ->>+ cmdb: Access UI
+    cmdb -->> cmdb: Create CI entry
+    cmdb -->>- dev: Close, noting CI value
+
+    Note over git, devops: The OpenAPI and devops files are stored in Git
+
+    dev ->>+ vsc: start IDE
+
+    Note over cmdb, vsc: Clone existing git for project
+    vsc ->>+ git : 
+    git -->>- vsc : Cloned, project opened
+
+    vsc -) devops: Update CMDB CI entry
+
+    alt If no OpenAPI linked
+    vsc -) devops: Update OpenAPI entry
+    end
+
+    vsc ->>+ term: start
+    Note over git, oas3: Set generation parameters
+    term ->>+ oas3: Generate code cmd
+    oas3 ->>+ oas3f: Read 
+    oas3f -->>- oas3: Contents
+    oas3 -->>- term: Success
+    term -->- vsc: close
+
+    vsc -) vsc: Update server code with defaults
+    vsc -) vsc: Manually write sequence diagrams
+    vsc -) vsc: Manually write Gateway infra
+    vsc -) vsc: Manually write feature flags
+
+    alt Register API if not already done
+
+    dev ->>+ apip: Register API
+    apip -->>- dev: Registered
+
+    end
+
+    vsc -) devops: Manually update entries
+
+    vsc ->>+ git: Commit
+    git --) git: Trigger GitActions for lint, gateway, features, etc 
+    git ->>- vsc: Success
+
+    vsc -->>- dev: Done
+
+
+```
+
+# End Status of flow
+
+At the end of this flow the basic code stubs exist and have been committed
+to Github.  The code can execute and will return not implemented
+response results.
+
+
+# Reading Notes
+
+For automation, some activities can be performed by GitActions calling
+qaskx-cli.
+
+The Visual Studio Code, CMDB and Github components can be substituted for 
+other software products such IntelliJ and Bitbucket.
+

docs/developer_update.md

@@ -0,0 +1,198 @@
+# Developer update flow
+
+_This document is intended to cover the scenario where the **devops** 
+file contents change including references to OpenAPI specifications._
+
+## Update the OpenAPI specification
+
+The OpenAPI specification as linked to the publishing server
+is updated first.
+
+```mermaid
+---
+title: Business Analyst update task flow
+---
+sequenceDiagram
+
+    actor ba as Business Analyst
+    participant ide as ApiCurio
+    participant git as Github
+    participant oas3f as OpenAPI file
+
+    Note over git, oas3f: The OpenAPI file is stored in Git
+
+    ba ->>+ ide: start IDE
+
+    ide ->> ide: Update API specification
+    ide ->> ide: Create / alter data structures
+    Note over ba, oas3f: Data structures include requests and responses
+    ide ->> ide: Create / alter new paths and methods
+    Note over ba, oas3f: Includes non 200 response handling, headers and security
+    ide ->> ide: Update the specification version
+    
+    ide ->>+ git: Commit to git
+    git ->>+ oas3f: OpenAPI file under Git
+    oas3f -->>- git: Saved
+    git --) git: Trigger GitActions for lint
+    git -->>- ide: 
+
+    ide -->>- ba: close
+
+```
+
+## Server update
+
+Once the OpenAPI definition has been updated the server code needs to be
+re-generated as the publisher of the API.
+
+**A server can also be a consumer of other APIs in which case it needs updating
+when downstream API specifications change.**
+
+```mermaid
+---
+title: Server development update task flow
+---
+sequenceDiagram
+
+    actor dev as Developer
+    participant vsc as Visual Studio Code
+    participant term as Terminal
+    participant qaskx as qaskx-cli
+    participant git as Github
+    link git: GitHub @ https://github.com/meerkat-manor/devops
+    participant oas3f as OpenAPI file
+    participant devops as devops file
+    participant apip as API portal
+
+    dev ->>+ vsc: start IDE
+
+    Note over vsc, term: Clone existing git for project
+    vsc ->>+ git : 
+    git -->>- vsc : Cloned, project opened
+
+    Note over git, devops: The OpenAPI and devops files are stored in Git
+
+    vsc ->>+ term: start
+
+    term ->>+ qaskx: Generate code
+    Note over qaskx, cmdb: qaskx-cli gen server cmd
+    qaskx ->>+ devops: Read 
+    devops -->>- qaskx: Contents
+
+    qaskx ->>+ oas3f: Read 
+    oas3f -->>- qaskx: Contents
+    qaskx -) qaskx: Auto generate server code
+    opt
+    qaskx -) qaskx: Auto generate sequence diagram
+    end
+    qaskx -->>- term: Success
+
+    opt
+
+    term ->>+ qaskx: Generate code
+    Note over qaskx, cmdb: qaskx-cli gen client cmd
+    qaskx ->>+ devops: Read dependency list
+    devops -->>- qaskx: Contents
+    loop Read called dependencies
+    qaskx ->>+ oas3f: Read dependency
+    oas3f -->>- qaskx: Contents
+    qaskx -) qaskx: Auto generate client code
+    end
+    qaskx -->>- term: Success
+
+    end
+
+    term -->- vsc: close
+
+    rect lightgrey
+    Note over vsc, qaskx: Code updates to use the updated OpenAPI definition
+    vsc -->> vsc: Code update
+    vsc -->> vsc: Local build
+    vsc -->> vsc: Local test
+    end
+
+    vsc ->>+ git: Commit
+    git --) git: Trigger GitActions for lint, gateway, features, etc 
+    git ->>- vsc: Success
+
+    vsc -->>- dev: close
+
+```
+
+
+## Client update
+
+Once the OpenAPI definition has been updated the client code needs to be
+re-generated as the consumer of the API.
+
+
+```mermaid
+---
+title: Client development update task flow
+---
+sequenceDiagram
+
+    actor dev as Developer
+    participant vsc as Visual Studio Code
+    participant term as Terminal
+    participant qaskx as qaskx-cli
+    participant git as Github
+    link git: GitHub @ https://github.com/meerkat-manor/devops
+    participant oas3f as OpenAPI file
+    participant devops as devops file
+
+    dev ->>+ vsc: start IDE
+
+    Note over vsc, term: Clone existing git for project
+    vsc ->>+ git : 
+    git -->>- vsc : Cloned, project opened
+
+    vsc ->>+ term: start
+
+    term ->>+ qaskx: Generate code
+    Note over qaskx, cmdb: qaskx-cli gen client cmd
+    qaskx ->>+ devops: Read dependency list
+    devops -->>- qaskx: Contents
+    loop Read called dependencies
+    qaskx ->>+ oas3f: Read dependency
+    oas3f -->>- qaskx: Contents
+    qaskx -) qaskx: Auto generate client code
+    end
+    opt
+    qaskx -) qaskx: Auto generate sequence diagram
+    end
+    qaskx -->>- term: Success
+
+    term -->- vsc: close
+
+    rect lightgrey
+    Note over vsc, qaskx: Code updates to use the updated OpenAPI definition
+    vsc -->> vsc: Code update
+    vsc -->> vsc: Local build
+    vsc -->> vsc: Local test
+    end
+
+    vsc ->>+ git: Commit
+    git --) git: Trigger GitActions for lint, gateway, features, etc 
+    git ->>- vsc: Success
+
+    vsc -->>- dev: close
+
+```
+
+The code is now updated with the latest OpenAPI definition
+
+# End Status of flow
+
+At the end of this flow the code has been updated with latest 
+definitions.
+
+# Reading Notes
+
+Using code generators will break the code in many situations and
+therefore using Git and diff tools will help in identifying
+what has changed and perform impact analysis.
+
+In many situations with specification changes the compiler
+will pick up the changes. Some changes can only be detected
+at run time if there is a high level of abstraction.

docs/project_start.md

@@ -0,0 +1,93 @@
+# Project flow (start)
+
+The project inception is when the scope of the project is
+defined, but design and coding does not start immediately.
+
+**Pause and reflect before starting to design and pause again
+to reflect on the design before starting to code.**
+
+With experience you will find that many times your initial gut instinct
+on design is correct, but **many is not the same as always**.  With the right
+tools, refactoring does allow you to change designs/code quickly - but a 
+pause over lunch or a night's sleep  costs little and can help
+you organise your approach.
+
+The sequence diagram below starts when you have an idea that you need
+new code and existing code cannot be modified to suit your needs.
+
+## Sequence diagram
+
+```mermaid
+
+sequenceDiagram
+
+
+    actor person as Team Member
+    participant term as Terminal
+    participant qaskx as qaskx-cli
+    participant git as Github
+
+    person ->>+ term: start
+
+    Note over term, git: Allocate repo name for server
+
+    term ->>+ qaskx: 
+    Note over git: qaskx-cli rediops git (*) cmd
+    qaskx ->>+ git: 
+    git -->>- qaskx: New git created
+    qaskx -->>- term: Success
+
+    term ->>+ git: git clone
+    git -->>- term: 
+
+    term ->>+ qaskx: qaskx-cli rediops configure cmd
+    qaskx -->>- term: 
+
+    term ->>+ git: git commit & push
+    git -->>- term: 
+
+    opt Only applicable for new clients (web, mobile)
+    Note over term, git: Allocate repo name for client
+
+    term ->>+ qaskx: 
+    Note over git: qaskx-cli rediops git (*) cmd
+    qaskx ->>+ git: 
+    git -->>- qaskx: New git created
+    qaskx -->>- term: Success
+
+    term ->>+ git: git clone
+    git -->>- term: 
+
+    term ->>+ qaskx: qaskx-cli rediops configure cmd
+    qaskx -->>- term: 
+
+    term ->>+ git: git commit & push
+    git -->>- term: 
+    end
+
+    term -->>- person: 
+
+```
+
+The git repositories are now primed and ready for API specification.
+
+The tasks in the sequence diagram is provisioning the required repositories.  
+The client repo may already exist for other functionality in which cas it is not
+created, but will be used in the [developer client start](developer_client_start.md)
+
+# End Status of flow
+
+At the end of this flow the scope of the API delivery and the service domain
+will be understood.
+
+The project information is next used in the 
+[analysis start](analysis_start.md) flow.
+
+# Reading Notes
+
+A well defined service domain that is understood and agreed by all parties
+will reduce rework effort, though with automation tools the manual effort
+can be better managed.
+
+A service domain can only return information or action requests that are 
+within its ability to fetch or remit to complete.

docs/readme.md

@@ -0,0 +1,22 @@
+# Contents
+
+This is the location for documentation associated with
+suggested the **rediops** process.  The objective is to increase
+the velocity of feature development by using tools to reduce
+the repetitious tasks or at least reduce the number of keystrokes.
+
+The documents should be read in the following sequence:
+
+* [setup](setup.md) Once off desktop setup
+* [project start](project_start.md) Starting a new project or initiative
+* [analysis start](analysis_start.md) Focus on technical API analysis
+* [developer server_start](developer_server_start.md) Initial server coding
+* [developer client_start](developer_client_start.md) Initial client coding
+* [developer update](developer_update.md) API updates during the development lifecycle
+
+The process above is in the context of exposing functionality defined in 
+API service that can be consumed by clients - commonly a web or app user
+interface.
+
+**All flows are high level process depictions and can
+be adjusted to suit your tools**

docs/setup.md

@@ -0,0 +1,94 @@
+# Setup desktop (start)
+
+This is the setup desktop tasks that is performed by 
+the developers, though others that are updating code
+including documentation can also perform the setup. 
+
+This task is expected to be done only once for a desktop
+environment, and the environment can be used for 
+multiple projects and deliveries.
+
+## Software installation
+
+Please ensure the following tools or equivalents are
+installed or you have access to servers with the
+associated capabilities.
+
+* A Git repository server - Github, Gitea
+* Rights to create a Git repo and push content to the remote Git repo
+* Git installed on local desktop
+* Integrated development environment (IDE) software on local desktop - Visual Studio Code, IntelliJ
+* Access to an OpenAPI editor - ApiCurio, Swagger UI
+* Installed **qaskx-cli** tool on local desktop - download from *TBA* 
+* Access to a Configuration Management Database (CMDB) - ServiceNow, Zenoss
+* Access to an API registry portal - Apiman.io, Redocly
+
+The server based software above could be executed as docker images
+on your local desktop, but this would be only for
+demonstration purposes.
+
+Configuring and initialising the software above is left for you to follow
+any existing standards you may have.  The qaskc-cli setup is below.
+
+## Sequence diagram
+
+The qaskx-cli has a setup command that creates the basic configuration
+files that it uses.  If or when you need to change the defaults, you will
+commonly make the changes permanent by changing the configuration files.
+
+This includes items such as:
+
+* Your details and your organisation
+* Your git details
+* Preferred programming language
+* Template (remote) locations
+
+You can read further information on each file in documents:
+
+* [.qaskx](config/dotaskx.md)
+
+Now have a look at the steps below to setup the files.
+
+```mermaid
+
+sequenceDiagram
+
+
+    actor person as Team Member
+    participant term as Terminal
+    participant qaskx as qaskx-cli
+    participant home as home dir
+    participant prj as projects dir
+
+    person ->>+ term: start
+
+    Note over term, qaskx: Setup qaskx-cli tool
+
+    term ->>+ qaskx: 
+    Note over qaskx, home: qaskx-cli setup configure cmd
+    qaskx ->>+ home: 
+    home -->>- qaskx: New .qaskx file created
+    qaskx ->>+ prj: 
+    prj -->>- qaskx: New config file created
+    qaskx -->>- term: Success
+
+    Note over term, home: You can rerun the configure or modify config file
+
+    term -->>- person: 
+
+```
+
+# End Status of flow
+
+At the end of the above setup steps the desktop will have the base tools
+that are mentioned in subsequent documents, and you will have
+access to the server features.
+
+The next step in the process is covered in [project_start](project_start.md)
+
+# Reading Notes
+
+The suggested tools are only that, suggestions.  You can substitute 
+your own preferred tools as appropriate.  The concept is still valid
+and your mileage may vary.
+

specification/rediops.json

@@ -2,8 +2,8 @@
     "openapi": "3.0.0",
     "info": {
         "title": "Rediscover DevOps configuration",
-        "version": "0.0.4",
-        "description": "This document describes the specification of the \nproposed file **.well-known/devops.json** that can \nbe used in the DevOps CI/CD as identifier for\ninformation required by the tools.\n\nBy using the .well-known location, assumptions are\nreduced if not eliminated by the automation tools.\n\nThe end result is a design using HATEOS principles where further\ninformation on a resource can be obatined by following the bread crumbs of the \nrelationships in the **.well-known/devops.json** file.\n\nAutomation tools can also validate the information during \nsource commit to confirm the engineers are providing the necessary \ninformation and that it is valid.\n\nThe **devops.json** file has been defined using OpenAPI but that does not imply that\na real API needs to be deployed or used.  On the contrary it is unlikely that the main\ncopy stored on Git is accessed via a API service.  The **devops.json** file can also\ninclude a AsyncOpen definition, so the one definition **devops.json** definition\ncan support a single compute resource that handles both synchronous and asynchronous\nservice models for a subject domain.\n\nYou could build a catalogue service of all your **devops.json** definitions linked to\nGit definitions, but that is not a specification requirement.\n\nFor further information see https://github.com/meerkat-manor/rediOps",
+        "version": "0.3.0",
+        "description": "This document describes the specification of the \nproposed file **.well-known/devops.json** that can \nbe used in the DevOps CI/CD as identifier for\ninformation required by the tools. \n\nBy using the .well-known location, assumptions are\nreduced if not eliminated by the automation tools.\n\nThe end result is a design using HATEOS principles where further\ninformation on a resource can be obatined by following the bread crumbs of the \nrelationships in the **.well-known/devops.json** file.\n\nAutomation tools can also validate the information during \nsource commit to confirm the engineers are providing the necessary \ninformation and that it is valid.\n\nThe **devops.json** file has been defined using OpenAPI but that does not imply that\na real API needs to be deployed or used.  On the contrary it is unlikely that the main\ncopy stored on Git is accessed via a API service.  The **devops.json** file can also\ninclude a AsyncOpen definition, so the one definition **devops.json** definition\ncan support a single compute resource that handles both synchronous and asynchronous\nservice models for a subject domain.\n\nYou could build a catalogue service of all your **devops.json** definitions linked to\nGit definitions, but that is not a specification requirement.\n\nFor further information see https://github.com/meerkat-manor/rediOps",
         "contact": {
             "name": "Meerkat",
             "url": "https://github.com/meerkat-manor/rediOps",
@@ -217,6 +217,13 @@
                         "description": "Errors with request"
                     },
                     "404": {
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/error-model"
+                                }
+                            }
+                        },
                         "description": "The required Devops recor with the requested identity wasnot found."
                     },
                     "500": {
@@ -243,7 +250,7 @@
                         "content": {
                             "application/json": {
                                 "schema": {
-                                    "$ref": "#/components/schemas/healthbase-model"
+                                    "$ref": "#/components/schemas/error-model"
                                 }
                             }
                         },
@@ -512,6 +519,7 @@
             ]
         },
         "/.well-known/devops.json": {
+            "summary": "Fetch the \"devops\" file for the service",
             "description": "This fetches the **devops.json** file for this service,\n\nThis definition is only applicable if the **deveops** is\npublished as a service outside of the source code.",
             "get": {
                 "tags": [
@@ -564,43 +572,42 @@
                 "properties": {
                     "email": {
                         "description": "The email adress of the owner.\n\nThe email address could be a distribution list.",
+                        "maxLength": 100,
                         "minLength": 6,
                         "type": "string",
                         "example": "emilia.jackson@devops.example.com"
                     },
                     "web": {
                         "description": "A web page URL for the owner.\n\nThe web page could refer to a team page.",
+                        "maxLength": 300,
+                        "minLength": 10,
                         "type": "string"
                     },
-                    "slack": {
-                        "description": "Slack address of the owner.",
-                        "type": "string"
-                    },
-                    "twitter": {
-                        "description": "Twitter handle for the contact",
-                        "type": "string"
-                    },
-                    "matrix": {
-                        "description": "The matrix IM identifier of the owner",
-                        "type": "string",
-                        "example": "@devops:meerkat-manor.org"
-                    },
                     "name": {
                         "description": "The name of the owner.\n\nThis may be persons or teams name.",
+                        "maxLength": 100,
+                        "minLength": 1,
                         "type": "string"
+                    },
+                    "contacts": {
+                        "description": "List of contacts\n\nThe list is allowed to contain duplicates of electronic \ncontact names (types) but not addresses. ",
+                        "maxItems": 10,
+                        "uniqueItems": true,
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/econtact-model"
+                        }
                     }
                 },
                 "example": {
+                    "name": "Head of RediOps",
                     "email": "devops@meerkatmanor-tech.org",
-                    "web": "meerkatmanor-tech.org",
-                    "slack": "",
-                    "twitter": "",
-                    "matrix": "@devops:meerkat-manor.org"
+                    "web": "meerkatmanor-tech.org"
                 }
             },
             "activity-model": {
                 "title": "activity",
-                "description": "",
+                "description": "Describes the activity that the engine will perform",
                 "required": [
                     "activity"
                 ],
@@ -608,6 +615,7 @@
                 "properties": {
                     "guide": {
                         "description": "Link to documentation",
+                        "maxLength": 500,
                         "type": "string",
                         "example": "https://github.com/meerkat-manor/rediOps/blob/main/guide/activity.md"
                     },
@@ -616,7 +624,8 @@
                         "type": "string"
                     },
                     "script": {
-                        "description": "A script file that is executed to perform the activity.\n\nThe choice of processing engine is up to the organisation, or \nsome assumptions can be made based on file extension.\n\nFor example:\n\n* .sh = Bash\n* .ps1 = PowerShell\n* .bat = MS DOS command",
+                        "description": "A command or script file that is executed to perform the activity.\n\nThe choice of activity processing engine is up to the organisation, or \nsome assumptions can be made based on file extension.\n\nFor example:\n\n* .sh = Bash\n* .ps1 = PowerShell\n* .bat = MS DOS command\n\nThe activity engine name along with catageory can link to\nconfiguration item for qualifying the processing engine.\n\nThe directory where the command is executed is\nbased on the root of the repository and if not found\nthen the current directory is used.\n\nThere is a maximum length of the string that can be stored.",
+                        "maxLength": 200,
                         "type": "string",
                         "example": "/build/builder.sh"
                     },
@@ -625,6 +634,15 @@
                         "description": "Engine used for activties.\n\nFor example the engine name can be:\n\n* azure-pipeline\n* circle-ci\n* jenkins\n\n_Note_: The engine category can be **BUILD**, **DEPLOY**,\n**INSTALL**",
                         "maxLength": 20,
                         "example": "{\n    \"category\": \"BUILD\",\n    \"name\": \"Jenkins\",\n    \"url\": \"some text\"\n}"
+                    },
+                    "platform": {
+                        "description": "The platform that the activity is configured for.\n\nA platform is an evironment such as Windows, Linux, iOS, Android, etc\n\nAn empty value is considered as executable on any platform.  For example\na .PS1 PowerShell script could execute on Winows and Linux. If you always\nexpect to execute on a specific platform then there is no need to supply a value.\n\nThe special value of **\"any\"** is hardcoded into processing.\n\nMinimum suggested values are:\n\n* linux\n* winodws\n* darwin\n\nYou could also qualify further to align with your CI/CD\nsoftware, using such values as:\n\n* Windows-10\n* Windows-11\n* Linux-Redhat\n* Windows-desktop\n \nand so on",
+                        "type": "string"
+                    },
+                    "id": {
+                        "description": "Unique identifier for record",
+                        "maxLength": 40,
+                        "type": "string"
                     }
                 },
                 "example": {
@@ -645,6 +663,8 @@
                 "properties": {
                     "guide": {
                         "description": "Link to documentation on repositories used by this component",
+                        "maxLength": 500,
+                        "minLength": 5,
                         "type": "string",
                         "example": "https://github.com/meerkat-manor/rediOps/blob/main/guide/repository.md"
                     },
@@ -653,9 +673,13 @@
                         "description": "Source control version engine.\n\nThis can be used by tools to retreive source code using binary executables.\n\nSome common tools are \"Git\", \"TFS\", \"Mercurial\", \"CVS\".\n\n_Note_: The engine category is **SOURCE** or **CUSTOM**",
                         "example": "Git"
                     },
-                    "artifact": {
-                        "$ref": "#/components/schemas/engine-model",
-                        "description": "Artifact engine\n\nSome common engines are:\n\n* Artifactory\n* Archiva\n\nCI servers can also have their own repository for generated artifact \n\n_Note_: The engine category is **ARTIFACT** or **CUSTOM**\n"
+                    "artifacts": {
+                        "description": "Artifact definition and type\n\nSome common engine namess are:\n\n* Artifactory\n* Archiva (archiva)\n* Docker hub (docker)\n* Nuget\n* PowerShell Gallery\n* Executable (executable)\n* Binary (binary).  For binary objects the extension can give a clue as to type\n\nCI servers can also have their own repository for generated artifact \n\n_Note_: The engine category is **ARTIFACT** or **CUSTOM**\n",
+                        "uniqueItems": true,
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/engine-model"
+                        }
                     }
                 },
                 "example": {
@@ -665,11 +689,18 @@
                         "name": "some text",
                         "url": "some text"
                     },
-                    "artifact": {
-                        "category": "ARTIFACT",
+                    "artifacts": [
+                        {
+                            "category": "CUSTOM",
+                            "name": "some text",
+                            "url": "some text"
+                        },
+                        {
+                            "category": "CUSTOM",
                             "name": "some text",
                             "url": "some text"
                         }
+                    ]
                 }
             },
             "tools-model": {
@@ -679,10 +710,13 @@
                 "properties": {
                     "guide": {
                         "description": "Link to documentation for the tool in the context of this DevOps",
+                        "maxLength": 500,
+                        "minLength": 5,
                         "type": "string",
                         "example": "https://github.com/meerkat-manor/rediOps/blob/main/guide/tool.md"
                     },
                     "playbook": {
+                        "description": "Playbook link as URI",
                         "type": "string"
                     },
                     "commands": {
@@ -713,6 +747,10 @@
                         "$ref": "#/components/schemas/engine-model",
                         "description": "The processor to execute the commands.\n\nFor example you can define it as \"powershell\" to execute script file with extension .ps1\n\nYou cannot combine different commands for different processors in the one tools set.  If you have different\nprocessors you can define multiple tools. \n\n_Note_: The engine category is **TOOL**",
                         "example": ""
+                    },
+                    "service_id": {
+                        "description": "A unique identifier (CI or UUID) for the tool definition.\nThis is not the instance identifier, such as the host name or IP (v4/v6)\nof the computing resource.\n\nThis can be something like the conguration item defned in a CMDDB\n",
+                        "type": "string"
                     }
                 },
                 "example": {
@@ -735,7 +773,7 @@
                 "type": "object",
                 "properties": {
                     "id": {
-                        "description": "An external identifier for this rsource.",
+                        "description": "An external identifier for this resource.",
                         "maxLength": 50,
                         "type": "string"
                     },
@@ -745,6 +783,7 @@
                     },
                     "url": {
                         "description": "An URL to the resource in the asset (CMDB) registry.",
+                        "maxLength": 500,
                         "type": "string"
                     }
                 },
@@ -764,11 +803,13 @@
                 "properties": {
                     "guide": {
                         "description": "Link to documentation for the topic",
+                        "maxLength": 500,
                         "type": "string",
                         "example": "https://github.com/meerkat-manor/rediOps/blob/main/guide/deploy.md"
                     },
                     "playbook": {
                         "description": "Playbook parameters",
+                        "maxLength": 500,
                         "type": "string"
                     },
                     "commands": {
@@ -796,6 +837,11 @@
                         "$ref": "#/components/schemas/engine-model",
                         "description": "The processor to understand and execute the commands or playbook.\n\nThe engine category depends on the parent of \nthis model. \n\nFor __test__ it can be:\n\n* COMMAND\n* TEST or\n* CUSTOM",
                         "example": ""
+                    },
+                    "id": {
+                        "description": "Unique identifier for record",
+                        "maxLength": 40,
+                        "type": "string"
                     }
                 },
                 "example": {
@@ -819,80 +865,6 @@
                     }
                 }
             },
-            "commands-model": {
-                "title": "commands",
-                "description": "Commands are executed by the engine.  The commands need to be constructed in a format compatible with the engine. ",
-                "type": "object",
-                "properties": {
-                    "pre": {
-                        "description": "Commands if any that are executed before the script and post items.",
-                        "type": "array",
-                        "items": {
-                            "type": "string"
-                        }
-                    },
-                    "script": {
-                        "description": "A single script thais executed after the \"pre\" and before the \"post\" commands.\nThe script can be an URL or a file within the version control (e.g. Git) repository.",
-                        "type": "string"
-                    },
-                    "post": {
-                        "description": "Commands if any that are executed after the script.",
-                        "type": "array",
-                        "items": {
-                            "type": "string"
-                        }
-                    }
-                },
-                "example": {
-                    "pre": [
-                        "hostname",
-                        "whoami"
-                    ],
-                    "script": "/deploy/install.sh",
-                    "post": [
-                        "echo Bye Bye"
-                    ]
-                }
-            },
-            "engine-model": {
-                "title": "engine",
-                "description": "Engine details as used for apis, build, testing, configuration and deployment\n\nIf a tool is used and the URL is an input then it is expected that the \ntool will understand the content/format of the input.",
-                "required": [
-                    "category"
-                ],
-                "type": "object",
-                "properties": {
-                    "category": {
-                        "description": "Category of the engine",
-                        "enum": [
-                            "BUILD",
-                            "TEST",
-                            "DEPLOY",
-                            "UNINSTALL",
-                            "SOURCE",
-                            "API",
-                            "CONFIG",
-                            "ARTIFACT",
-                            "COMMAND",
-                            "CUSTOM"
-                        ],
-                        "type": "string"
-                    },
-                    "name": {
-                        "description": "A common name for the tool, such as:\n\n* makefile\n* teamcity\n* azure-pipeline\n\nThe choice is up to you but you should keep it consistent.",
-                        "type": "string"
-                    },
-                    "url": {
-                        "description": "Link to engine or its configuration\n\nThe format of the URL will depend on the engine",
-                        "type": "string"
-                    }
-                },
-                "example": {
-                    "category": "CONFIG",
-                    "name": "some text",
-                    "url": "/asset.conf"
-                }
-            },
             "devopsbrief-model": {
                 "title": "devops-brief",
                 "description": "Used only for services and not part of the \n**rediops** definition ",
@@ -919,6 +891,7 @@
                     },
                     "guide": {
                         "description": "Link to the guide of the devops definition",
+                        "maxLength": 500,
                         "type": "string"
                     },
                     "self": {
@@ -941,6 +914,7 @@
                 "properties": {
                     "guide": {
                         "description": "Link to documentation describing the health check",
+                        "maxLength": 500,
                         "type": "string",
                         "example": "https://github.com/meerkat-manor/rediOps/blob/main/guide/health.md"
                     },
@@ -969,17 +943,23 @@
                 "type": "object",
                 "properties": {
                     "status": {
+                        "description": "Error status code, which is not the same as HTTP status code",
                         "type": "string"
                     },
                     "message": {
+                        "description": "Error details",
+                        "maxLength": 300,
+                        "minLength": 10,
                         "type": "string"
                     },
                     "resolution": {
-                        "description": "",
+                        "description": "Resolution instructions for the error situation if these exists.",
                         "type": "string"
                     },
                     "technical": {
                         "description": "Technical information for the error.\n\nThis must not contain sensitive information",
+                        "maxLength": 300,
+                        "minLength": 10,
                         "type": "string"
                     }
                 },
@@ -997,6 +977,7 @@
                 "properties": {
                     "guide": {
                         "description": "Link to documentation on dependencies",
+                        "maxLength": 500,
                         "type": "string",
                         "example": "https://github.com/meerkat-manor/rediOps/blob/main/guide/dependency.md"
                     },
@@ -1008,9 +989,11 @@
                         }
                     },
                     "tools": {
+                        "description": "Dependency is not only the APIs or services \nthe asset depends on.  It can also be the \ntools or deployment chain.",
+                        "maxItems": 100,
                         "type": "array",
                         "items": {
-                            "$ref": "#/components/schemas/tools-model"
+                            "$ref": "#/components/schemas/deploy-model"
                         }
                     }
                 },
@@ -1018,52 +1001,76 @@
                     "guide": "some text",
                     "apis": [
                         {
-                            "guide": "some text",
+                            "release_id": "some text",
+                            "service_id": "some text",
                             "url": "some text",
                             "format": "Custom",
+                            "guide": "some text",
                             "api": {
-                                "category": "DEPLOY",
+                                "category": "CONFIG",
                                 "name": "some text",
                                 "url": "some text"
-                            }
+                            },
+                            "name": "some text"
                         },
                         {
-                            "guide": "some text",
+                            "release_id": "some text",
+                            "service_id": "some text",
                             "url": "some text",
-                            "format": "AsyncAPI",
+                            "format": "WSDL",
+                            "guide": "some text",
                             "api": {
-                                "category": "API",
+                                "category": "ARTIFACT",
                                 "name": "some text",
                                 "url": "some text"
-                            }
+                            },
+                            "name": "some text"
                         }
                     ],
                     "tools": [
                         {
                             "guide": "some text",
                             "playbook": "some text",
-                            "commands": [
+                            "commands": {
+                                "pre": [
                                     "some text",
                                     "some text"
                                 ],
-                            "tool": {
+                                "script": "some text",
+                                "post": [
+                                    "some text",
+                                    "some text"
+                                ],
+                                "platform": "some text"
+                            },
+                            "deploy": {
                                 "category": "DEPLOY",
                                 "name": "some text",
                                 "url": "some text"
-                            }
+                            },
+                            "id": "some text"
                         },
                         {
                             "guide": "some text",
                             "playbook": "some text",
-                            "commands": [
+                            "commands": {
+                                "pre": [
                                     "some text",
                                     "some text"
                                 ],
-                            "tool": {
-                                "category": "ARTIFACT",
+                                "script": "some text",
+                                "post": [
+                                    "some text",
+                                    "some text"
+                                ],
+                                "platform": "some text"
+                            },
+                            "deploy": {
+                                "category": "CUSTOM",
                                 "name": "some text",
                                 "url": "some text"
-                            }
+                            },
+                            "id": "some text"
                         }
                     ]
                 }
@@ -1075,6 +1082,7 @@
                 "properties": {
                     "url": {
                         "description": "URL for health check path.  The path if supplied must\nmatch a path in the service definition (OpenAPI)\n\nUsing the URL path the details of the health check can\nbe found in the service definition.\n\nNormally a human coud make an intelligent assumption on\nwhat the name of the health check but a machine will find it\nmore difficult.  Also consider how you would identify it \nin a foreign language.",
+                        "maxLength": 500,
                         "type": "string"
                     },
                     "status": {
@@ -1101,11 +1109,6 @@
                 ],
                 "type": "object",
                 "properties": {
-                    "devops_version": {
-                        "description": "**devops** specification version\n\nMajor versions may not be compatible with minor versions.\n\nThis is not the version of the application or source.\n\nThe value here is the OpenAPI version of this specification\nand is not your version of your specifications.  This is analogous\nto the \"openapi\" field in the OpenAPI document.",
-                        "type": "string",
-                        "example": "0.1.34"
-                    },
                     "unique_id": {
                         "description": "Unique identifier \n\nThis is only applicable when the definition is serviced from a catalogue\nthat requires unique identifers.\n\nDo not use the Git repository URL as the unique identifier because\nto retrieve the file you would have to know the location. ",
                         "type": "string",
@@ -1167,7 +1170,7 @@
                     },
                     "repository": {
                         "$ref": "#/components/schemas/repository-model",
-                        "description": "Repository links\n\nRepositories includes:\n\n* Source version control management.  Examples include:\n    - Git\n    - Mercurial\n    - TFS\n* Artefact repositories. Examples include:\n    - Archiva\n    - Artifactory\n* Package managers. Exmaples include:\n    - npm\n    - NuGet\n    - Powershell Gallery\n    - Maven\n    - Apt \n    - Dnf ",
+                        "description": "Repository links\n\nRepositories includes:\n\n* Source version control management.  Examples include:\n    - Git\n    - Mercurial\n    - TFS\n* Artefact repositories. Examples include:\n    - Archiva\n    - Artifactory\n* Package managers. Exmaples include:\n    - npm\n    - NuGet\n    - Powershell Gallery\n    - Maven\n    - Apt \n    - Dnf \n     \nRepositories are managed in forges, such as:\n\n* GitHub\n* Gitlab\n* Gitea\n",
                         "properties": {
                             "guide": {
                                 "type": "string"
@@ -1220,7 +1223,7 @@
                         }
                     },
                     "test": {
-                        "description": "Describes the test process, tools and script",
+                        "description": "Describes the test process, tools and script.\n\nTesting includes verification activities lie code scans, security reviews, code risk analysis, \ntest coverage and other compliance activities.",
                         "type": "array",
                         "items": {
                             "$ref": "#/components/schemas/activity-model"
@@ -1253,44 +1256,12 @@
                             }
                         }
                     },
-                    "install": {
-                        "$ref": "#/components/schemas/deploy-model",
-                        "description": "The Install section gives information on installing the resource onto a server\nfor the first time.  The detection on whether the resource is already\ninstalled is not defined in the specifications.\n\nThe information can be in the form of an Ansibe playbook or commands to \nbe executed on the server.  You can also execute \ncommaonds from a script file that is found on the Git repo.",
-                        "properties": {
-                            "guide": {
-                                "type": "string"
-                            },
-                            "engine": {
-                                "type": "string"
-                            },
-                            "playbook": {
-                                "type": "string"
-                            },
-                            "commands": {
-                                "type": "object",
-                                "properties": {
-                                    "pre": {
-                                        "type": "array",
-                                        "items": {
-                                            "type": "string"
-                                        }
-                                    },
-                                    "script": {
-                                        "type": "string"
-                                    },
-                                    "post": {
-                                        "type": "array",
-                                        "items": {
-                                            "type": "string"
-                                        }
-                                    }
-                                }
-                            }
-                        }
-                    },
                     "refresh": {
-                        "$ref": "#/components/schemas/deploy-model",
                         "description": "The Refresh section gives information on refreshing the resource on the server.  \nThe instructions can be the same as for installing the first time.\n\nThe information can be in the form of a Ansibe playbook or commands to \nbe executed on the server with the component installed.  You can also execute \ncommaonds from a script file that is found on the Git repo.",
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/deploy-model"
+                        },
                         "properties": {
                             "guide": {
                                 "type": "string"
@@ -1324,8 +1295,11 @@
                         }
                     },
                     "uninstall": {
-                        "$ref": "#/components/schemas/deploy-model",
                         "description": "The Uninstall section gives information on uninstalling the component.\n\nThe information can be in the form of an Ansibe playbook or commands to \nbe executed on the server with the component installed.  You can also execute \ncommaonds from a script file that is found on the Git repo.",
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/deploy-model"
+                        },
                         "properties": {
                             "guide": {
                                 "type": "string"
@@ -1359,22 +1333,74 @@
                         }
                     },
                     "apis": {
-                        "description": "List of OpenAPI and/or AsyncAPI definitions.\n\nThe list can include Git and REST versions, because before build the API might not be available\nas a REST service.\n\nA resource may have multiple definitions files or even different versions.",
+                        "description": "List of OpenAPI and/or AsyncAPI definitions.\n\nThe list can include Git and REST versions, because before build the API might not be available\nas a REST service.\n\nA resource may have multiple definitions files or even different versions.\n\nThere is also the ability to use WSDL specifications.",
                         "type": "array",
                         "items": {
                             "$ref": "#/components/schemas/api-model"
                         }
                     },
                     "tags": {
-                        "description": "A list of free format tags for the root of the **devops** definition.\n\nThe tags can be used for things such as:\n* identify appication type\n* additional tools applicable",
+                        "description": "A list of free format tags for the root of the **devops** definition.\n\nThe tags can be used for things such as:\n* identify application type\n* additional tools applicable",
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
+                    "governance": {
+                        "$ref": "#/components/schemas/governance-model",
+                        "description": "Governance details for the asset described \nby the RediOps definiton."
+                    },
+                    "deploy": {
+                        "description": "The Deploy section gives information on installing the resource onto a server.\nThe detection on whether the resource is already\ninstalled is not defined in the specifications.\n\nThe information can be in the form of an Ansible playbook or commands to \nbe executed on the server.  You can also execute \ncommands from a script file that is found on the Git repo.\n\nThe deploy section can also conain release information and \nactivities.",
+                        "maxItems": 100,
+                        "uniqueItems": false,
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/deploy-model"
+                        },
+                        "properties": {
+                            "guide": {
+                                "type": "string"
+                            },
+                            "engine": {
+                                "type": "string"
+                            },
+                            "playbook": {
+                                "type": "string"
+                            },
+                            "commands": {
+                                "type": "object",
+                                "properties": {
+                                    "pre": {
+                                        "type": "array",
+                                        "items": {
+                                            "type": "string"
+                                        }
+                                    },
+                                    "script": {
+                                        "type": "string"
+                                    },
+                                    "post": {
                                         "type": "array",
                                         "items": {
                                             "type": "string"
                                         }
                                     }
+                                }
+                            }
+                        }
+                    },
+                    "metadata_url": {
+                        "description": "A URL to additional, custom metadata.\n\nThis metadata in the file, probably in JSON or YAML, format\ncan have any custom schema.  The data in the metadata file\ncan be used by process as required.\n\nOne use case is as template data for generating code,\nconfigurations, scripts or commands.\n\nThe **qaskx-cli** tool is able to parse and use\nJSON, YAML, and YML formatted files as input\ndata to templating.\n\nFor qaskx-cli the URL can be an internet file\nor local file.\n",
+                        "type": "string"
+                    },
+                    "schema": {
+                        "$ref": "#/components/schemas/schema-model",
+                        "description": "The rediOPs schema.\n\nThis includes the version of the schema that\nyour definition represents."
+                    }
                 },
                 "example": {
-                    "devops_version": "some text",
+                    "devops_version": "0.1",
                     "unique_id": "some text",
                     "created_on": "2018-02-10T09:30:00Z",
                     "updated_on": "2018-02-10T09:30:00Z",
@@ -1613,6 +1639,7 @@
                 "type": "object",
                 "properties": {
                     "status": {
+                        "maxLength": 50,
                         "type": "string"
                     },
                     "output": {
@@ -1668,10 +1695,12 @@
                 "properties": {
                     "href": {
                         "description": "URL for the resources",
+                        "maxLength": 300,
                         "type": "string"
                     },
                     "rel": {
                         "description": "The relationships for the resource as hypermedia link.\n\nThe common values are:\n\n* self : this resource.  Normally used in lists,\n* first : the first resource in a list, \n* last : the last resource in a list, \n* next : the next resource or page in a list, \n* prev : the previous resource or page in a list\n* parent: the parent resource for the item\n* collection: list of children of the resource\n* buy: link to purchase the investment\n* sell: link to sell the invetsment, assuming the investor has holdings\n* quote: link to quote for the asset\n* icon : URL to the icon for the resource\n* video : URL to a video\n* external : URL to external content\n* content : inline (HTML or markdonw) content related to the resource\n* price : link to resource (product) unit price\n* price+collection : link to list of historical unit prices\n \nThe \"rel\" value is also dependent on context.  There is no prices or ability to buy/sell marketplace itself and therefore these resources will not provide a \"buy\" link for instance.\n\nA buy/sell link are expected to be POST requests and therefore the \"operation\" will need to be considered.  If perdforming a \"POST\" then the caller will need to know the JSON model for the POST, if the media type is \"application/json\" as an example.",
+                        "maxLength": 50,
                         "type": "string"
                     },
                     "operation": {
@@ -1688,10 +1717,12 @@
                     },
                     "media_type": {
                         "description": "The type of resource media type that the link refers to.\n\nExamples are:\n\n* application/json\n* text/html",
+                        "maxLength": 50,
                         "type": "string"
                     },
                     "caption": {
-                        "description": "A caption that can be displaye dfor the link",
+                        "description": "A caption that can be displayed for the link",
+                        "maxLength": 100,
                         "type": "string"
                     }
                 },
@@ -1726,6 +1757,7 @@
                     },
                     "notes": {
                         "description": "Array of notes relevant to current state of health",
+                        "maxItems": 200,
                         "type": "array",
                         "items": {
                             "type": "string"
@@ -1737,6 +1769,7 @@
                     },
                     "description": {
                         "description": "A human-friendly description of the\r\nservice.\r\n",
+                        "maxLength": 500,
                         "type": "string"
                     },
                     "checks": {
@@ -1887,9 +1920,11 @@
                         "type": "string"
                     },
                     "status": {
+                        "maxLength": 50,
                         "type": "string"
                     },
                     "message": {
+                        "maxLength": 500,
                         "type": "string"
                     }
                 },
@@ -1904,20 +1939,21 @@
                 "required": [
                     "api",
                     "url",
-                    "format"
+                    "format",
+                    "name"
                 ],
                 "type": "object",
                 "properties": {
                     "release_id": {
-                        "description": "In well-designed APIs, backwards-compatible\r\nchanges in the service should not update a version number.  APIs\r\nusually change their version number as infrequently as possible, to\r\npreserve stable interface.  However, implementation of an API may\r\nchange much more frequently, which leads to the importance of having\r\nseparate \"release number\" or \"releaseId\" that is different from the\r\npublic version of the API.\r\n\r\nThe release identifier is required for dependencies in recognition\r\nthat under source versioning, the same API may have multiple\r\nversions rercoded - such as in the past and the curent version.\r\n",
+                        "description": "In well-designed APIs, backwards-compatible\r\nchanges in the service should not update a version number.  APIs\r\nusually change their version number as infrequently as possible, to\r\npreserve stable interface.  However, implementation of an API may\r\nchange much more frequently, which leads to the importance of having\r\nseparate \"release number\" or \"releaseId\" that is different from the\r\npublic version of the API.\r\n\r\nThe release identifier is required for dependencies in recognition\r\nthat under source versioning, the same API may have multiple\r\nversions recorded - such as in the past and the curent version.\r\n",
                         "type": "string"
                     },
                     "service_id": {
-                        "description": "A unique identifier (CI or UUID) for the service definition.\nThis is not the instance identifier, such as the host name or IP (v4/v6)\nof the computing rsource.\n\nThis can be something like the coguration item defned in a CMD definitiontring\n",
+                        "description": "A unique identifier (CI or UUID) for the service definition.\nThis is not the instance identifier, such as the host name or IP (v4/v6)\nof the computing resource.\n\nThis can be something like the conguration item defned in a CMDB\n",
                         "type": "string"
                     },
                     "url": {
-                        "description": "A full URL for the API specification or if the value is partial\nthen the location is assumed to be on the Git repo.  That is the host name and\nGit name are the same as for the \"devops.json\" file.\n\nIf the resource details are being supplied by a catalogue service\nthen the value in the \"repository\" section will be used.\n\nThis is not the URL for the API implementation as that \nvalue is expected to be stored with the deployment information\nsuch as a CMDB.",
+                        "description": "A full URL for the API specification or if the value is partial\nthen the location is assumed to be on the Git repo.  That is the host name and\nGit name are the same as for the \"devops.json\" file.  The URL should also\naccount for API version.\n\nIf the resource details are being supplied by a catalogue service\nthen the value in the \"repository\" section will be used.\n\nThis is not the URL for the API implementation as that \nvalue is expected to be stored with the deployment information\nsuch as a CMDB.",
                         "maxLength": 500,
                         "type": "string",
                         "example": "/config/openapi.json"
@@ -1935,12 +1971,17 @@
                     },
                     "guide": {
                         "description": "Link to documentation for the topic",
+                        "maxLength": 500,
                         "type": "string",
                         "example": "https://github.com/meerkat-manor/rediOps/blob/main/guide/api.md"
                     },
                     "api": {
                         "$ref": "#/components/schemas/engine-model",
                         "description": "The engine that the Url refers to.  As the Url format is used by various \nprocessors, an engine value is required for proper processing.\n\nThe acceptable values will depend on the organisation, but the\nminimal values that need to be supported are:\n\n* GIT for Git located resources.  For this case the Git resource is assumed \n  to be in the Git repository for this DevOps resource if the prefix is not\n  HTTPS\n* REST for HTTP/S based web pages that are no explicitly handled by other engines\n\nOther possible values might be:\n\n* FILE for local or LAN based resources \n* S/FTP for FTP based URL resources\n \n_Note_: The engine category is **API**"
+                    },
+                    "name": {
+                        "description": "A short name for the API.  This is best auto populated\nfrom a CMDB based on the CI, but alternatively can be\nmanually entered.",
+                        "type": "string"
                     }
                 },
                 "example": {
@@ -1953,6 +1994,165 @@
                         "url": "some text"
                     }
                 }
+            },
+            "econtact-model": {
+                "description": "Electronic contact model\n\nThis type can be used to defined additional contact\nmethods such as Slack or Mastodon or Microsoft Teams.",
+                "required": [
+                    "name",
+                    "address"
+                ],
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "description": "This is the name of the electronic name used for the contact.\n\nThe names have not been enumerated so as to allow additions and new\nentrants.\n\nFor example Slack might be defined as SLACK.\n\nThe choice of names are set by the consumer, though the recommended names\nfor common contact names are:\n\n* SMS\n* SLACK\n* TWITTER\n* MASTODON\n* MATRIX\n* MSTEAMS\n* JABBER\n* THREADS\n\n_Note_: Uppercase name have been selected to denote these constants",
+                        "maxLength": 100,
+                        "type": "string"
+                    },
+                    "address": {
+                        "description": "The electronic address",
+                        "maxLength": 50,
+                        "type": "string"
+                    }
+                },
+                "example": {
+                    "name": "MSTEAMS",
+                    "address": "meerkat@merebox.com"
+                }
+            },
+            "governance-model": {
+                "description": "Governance details for the resouce being\ndescribed by the RediOps definition",
+                "type": "object",
+                "properties": {
+                    "data_classification": {
+                        "description": "Rating for data.\n\nThe higher the number the data integrity controls and assurance is required.\nIt is up to the organisation to\nselect their ratings scheme, but it is important it is consistent across all assets.",
+                        "maxLength": 100,
+                        "minLength": 1,
+                        "type": "string"
+                    },
+                    "availability_rating": {
+                        "description": "Rating for availability.\n\nThe higher the number the more available the asset is.  It is up to the organisation to\nselect their ratings scheme, but it is important it is consistent across all assets.",
+                        "type": "number"
+                    },
+                    "resiliency_rating": {
+                        "description": "Rating for resiliency.\n\nThe higher the number the more resiliant the asset needs to be to failure.  \nIt is up to the organisation to\nselect their ratings scheme, but it is important it is consistent across all assets.",
+                        "type": "number"
+                    },
+                    "cyber_rating": {
+                        "description": "Rating for cyber.\n\nThe higher the number the more cyber controsl are required for the asset.  \nIt is up to the organisation to\nselect their ratings scheme, but it is important it is consistent across all assets.",
+                        "type": "number"
+                    }
+                }
+            },
+            "commands-model": {
+                "title": "commands",
+                "description": "Commands are executed by the engine.  The commands need to be constructed in a format compatible with the engine. ",
+                "type": "object",
+                "properties": {
+                    "pre": {
+                        "description": "Commands if any that are executed before the script and post items.",
+                        "maxItems": 50,
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
+                    "script": {
+                        "description": "A single script thais executed after the \"pre\" and before the \"post\" commands.\nThe script can be an URL or a file within the version control (e.g. Git) repository.",
+                        "maxLength": 500,
+                        "type": "string"
+                    },
+                    "post": {
+                        "description": "Commands if any that are executed after the script.",
+                        "maxItems": 50,
+                        "type": "array",
+                        "items": {
+                            "type": "string"
+                        }
+                    },
+                    "platform": {
+                        "description": "The platform that the activity is configured for.\n\nA platform is an evironment such as Windows, Linux, iOS, Android, etc\n\nAn empty value is considered as executable on any platform.  For example\na .PS1 PowerShell script could execute on Winows and Linux. If you always\nexpect to execute on a specific platform then there is no need to supply a value.\n\nThe special value of **\"any\"** is hardcoded into processing.\n\nMinimum suggested values are:\n\n* linux\n* winodws\n* darwin\n\nYou could also qualify further to align with your CI/CD\nsoftware, using such values as:\n\n* Windows-10\n* Windows-11\n* Linux-Redhat\n* Windows-desktop\n \nand so on",
+                        "maxLength": 50,
+                        "type": "string"
+                    }
+                },
+                "example": {
+                    "pre": [
+                        "hostname",
+                        "whoami"
+                    ],
+                    "script": "/deploy/install.sh",
+                    "post": [
+                        "echo Bye Bye"
+                    ]
+                }
+            },
+            "engine-model": {
+                "title": "engine",
+                "description": "Engine details as used for apis, build, testing, configuration and deployment\n\nIf a tool is used and the URL is an input then it is expected that the \ntool will understand the content/format of the input.",
+                "required": [
+                    "category"
+                ],
+                "type": "object",
+                "properties": {
+                    "category": {
+                        "description": "Category of the engine\n\nThe category value is dependant on the context\nof the engine model.",
+                        "enum": [
+                            "BUILD",
+                            "TEST",
+                            "VERIFY",
+                            "RELEASE",
+                            "DEPLOY",
+                            "UNINSTALL",
+                            "SOURCE",
+                            "API",
+                            "CONFIG",
+                            "ARTIFACT",
+                            "COMMAND",
+                            "CUSTOM"
+                        ],
+                        "type": "string"
+                    },
+                    "name": {
+                        "description": "A common name for the engine or tool, such as:\n\n* make\n* teamcity\n* jenkins\n* Gitlab\n* Bamboo\n* Travis\n* azure-pipeline\n* go-build\n* dotnet\n* docker\n* concourse\n* circle-ci\n* drone-ci\n* woodpecker-ci\n\nThe choice is up to you but you should keep it consistent.\n\nTools such as the **qaskx-cli** will understood some names and be\nable to execute the script or commands.  Please refer to **qaskx-cli**\ndocumentation at https://docs.qaskx.one/qaskx-cli/",
+                        "maxLength": 50,
+                        "minLength": 5,
+                        "type": "string"
+                    },
+                    "url": {
+                        "description": "Link to engine or its configuration\n\nThe format of the URL will depend on the engine.\n\nCommonly the format will be of a URL such that \nit begins with \"https\" but some categories such as \na docket repository does not expect the the \"https\"\nprefix.\n\nAn executable ARTIFACT may also describe a file system\nobject and not a Uniform Resource Locator of the common format.",
+                        "maxLength": 500,
+                        "minLength": 5,
+                        "type": "string"
+                    }
+                },
+                "example": {
+                    "category": "BUILD",
+                    "name": "make",
+                    "url": "/src/makefile"
+                }
+            },
+            "schema-model": {
+                "description": "Representaionn of the rediOps schema\nversion and definition link",
+                "required": [
+                    "name",
+                    "version",
+                    "link"
+                ],
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "description": "The rediOps schema name",
+                        "type": "string"
+                    },
+                    "version": {
+                        "description": "The rediOps version",
+                        "type": "string"
+                    },
+                    "link": {
+                        "description": "The rediOps schema link for detailed information",
+                        "type": "string"
+                    }
+                }
             }
         },
         "securitySchemes": {

templates/default/.qaskx

@@ -0,0 +1,17 @@
+{
+    "GitProvider": "git",
+    "GitHost": "https://tea.example.com",
+    "GitApi": "https://tea.merebox.com/api/v1",
+    "GitOrg": "Wardrobe",
+    "GitRepoUser": "meerkat",
+    "GitBranch": "main",
+    "GitUserEmail": "meerkat@example.com",
+    "Organisation": "Witch & Wardrobe",
+    "TemplateHost": "",
+    "TemplateFolder": "Xtreme/Folder/Template",
+    "Name": "Sir Meerkat",
+    "ServiceOwner": "Meerkat team, Sydney",
+    "ServiceOwnerEmail": "Meerkat.Team@example.com",
+    "PrimaryProgramLanguage": "go",
+    "LintApiLevel": ""
+}

templates/default/devops.json

@@ -0,0 +1,134 @@
+{
+    "apis": [
+        {
+            "api": {
+                "category": "API",
+                "name": "",
+                "url": ""
+            },
+            "format": "OpenAPI",
+            "guide": "",
+            "release_id": "",
+            "service_id": "",
+            "name": "AService",
+            "url": ""
+        },
+        {
+            "api": {
+                "category": "API",
+                "name": "",
+                "url": ""
+            },
+            "format": "AsyncAPI",
+            "guide": "",
+            "release_id": "",
+            "service_id": "",
+            "name": "BService",
+            "url": ""
+        }
+    ],
+    "asset": {
+        "id": "b6775b43-659d-4426-b012-3226a7cfdd56",
+        "name": "",
+        "url": ""
+    },
+    "build": [
+        {
+            "activity": {
+                "category": "BUILD",
+                "name": "Lint",
+                "url": ""
+            },
+            "config": "",
+            "guide": ""
+        },
+        {
+            "activity": {
+                "category": "BUILD",
+                "name": "Compile",
+                "url": ""
+            },
+            "config": "",
+            "guide": ""
+        }
+    ],
+    "created_on": "2023-07-09T07:05:38.8634596+10:00",
+    "dependency": {
+        "apis": [
+            {
+                "api": {
+                    "category": "API",
+                    "name": "",
+                    "url": ""
+                },
+                "format": "OpenAPI",
+                "guide": "",
+                "release_id": "v1",
+                "service_id": "Customer.Details.CI00001",
+                "url": ""
+            }
+        ],
+        "guide": "",
+        "tools": [
+            {
+                "commands": null,
+                "guide": "",
+                "playbook": "",
+                "tool": {
+                    "category": "CUSTOM",
+                    "name": "",
+                    "url": ""
+                }
+            }
+        ]
+    },
+    "devops_version": "0.0.1",
+    "guide": "",
+    "install": {
+        "commands": {
+            "script": ""
+        },
+        "deploy": {
+            "category": "DEPLOY",
+            "name": "rpm",
+            "url": ""
+        },
+        "guide": "",
+        "playbook": ""
+    },
+    "name": "Wardrobe",
+    "organisation": "Witch & Wardrobe",
+    "owner": {
+        "email": "",
+        "matrix": "",
+        "name": "",
+        "slack": "",
+        "twitter": "",
+        "web": ""
+    },
+    "tags": [
+        ""
+    ],
+    "test": [
+        {
+            "activity": {
+                "category": "TEST",
+                "name": "",
+                "url": ""
+            },
+            "config": "",
+            "guide": ""
+        },
+        {
+            "activity": {
+                "category": "TEST",
+                "name": "LoadRunner",
+                "url": ""
+            },
+            "config": "",
+            "guide": ""
+        }
+    ],
+    "unique_id": "48913292-dc8a-4fb6-99cd-c22ab445e0ee",
+    "updated_on": "2023-07-09T07:05:38.8634596+10:00"
+}