Documentation updates

Signed-off-by: Venkatesh Raikar <[email protected]>

akm/documentation/README.md

@@ -1,7 +1,7 @@
 # AKM Documentation
 
 The AKM documentation is realized with GitHub Pages. It is generated from
-the markdown files in the ```/Documentation``` directory of this repository.
+the markdown files in the ```/documentation``` directory of this repository.
 The static webpage is generated automatically after every PR merged to master
 and deployed into a branch called `gh-pages`.
 
@@ -45,7 +45,7 @@ Reference: [Git Documentation](https://git-scm.com/book/en/v2/Git-Tools-Submodul
 Within the repository
 
 ```
-hugo server -D -s ./documentation
+hugo server -D -s akm/documentation
 ```
 
 Optional ```-D:``` include draft pages as well. Afterwards, you can access the

akm/documentation/config.toml

@@ -14,12 +14,12 @@ publishDir = "../docs"
 [[menu.shortcuts]]
 name = "<i class='fab fa-github'></i> Github repo"
 identifier = "ds"
-url = "https://localhost/automotive_knowledge_model"
+url = "https://github.com/COVESA/akm"
 weight = 10
 
 [[menu.shortcuts]]
 name = "<i class='fas fa-download'></i> Releases"
-url = "https://localhost/automotive_knowledge_model/releases"
+url = "https://github.com/COVESA/akm/releases"
 weight = 12
 
 # Generation of JSON index to allow search

akm/documentation/content/_index.md

@@ -3,10 +3,10 @@ title: "Automotive Knowledge Model"
 ---
 
 # Automotive Knowledge Model (AKM)
-This repo contains the Automotive Knowledge Model (AKM), an open-source data model and metadata catalog
- for transmitting vehicle signals in a consistent manner. 
+This repo contains the Automotive Knowledge Model (AKM), an expressive and extensible semantics and 
+standards-based vocabulary and data model for automobiles. 
 
-The source code and releases can be found in the [AKM github repository](<TDB>).
+The source code and releases can be found in here [AKM github repository](https://github.com/COVESA/akm).
 
 
 

akm/documentation/content/ecosystem/tools.md

@@ -6,10 +6,7 @@ weight: 1
 
 The AKM can be transformed into other formats or integrate with other tooling environments and ecosystems.
 
-AKM-tools is a project that provide tooling to generate data model artifcats from AKM to different formats such as yaml,json.
-Fig 1 shows the schematics of the top-level process.
+AKM-tools provide tooling to generate data model artifacts in different formats.
 
-![AKM Graphical View](/tdb.png)<br>
 
-
-AKM-tools [akm-tools project](TBD).
+The source code for akm-tools can be found here [akm-tools](https://github.com/COVESA/akm/tree/main/akm_tools).

akm/documentation/content/extensions/_index.md

@@ -0,0 +1,57 @@
+
+---
+title: Extensions
+weight: 50
+chapter: true
+---
+
+# Extensions
+Extensions enable organizations to append new schema elements and data to the AKM.  Schema extensions are added to the akm/extensions/schema folder and data extensions are added to the akm/extensions/data folder.
+
+The AKM adheres to the Open/Closed principle and does not provide a mechanism for overriding or redefining entries in the public AKM, which would invalidate the nature of a shared vocabulary.
+
+
+## Example
+The following example demonstrates how the Data Type is extended to include the corresponding json and xsd data types.
+#### akm/extensions/schema/data_type.json
+ ```JSON
+{
+  "$id": "akm.extension.DataType",
+  "type": "object",
+  "description": "Extended properties for DataType",
+  "properties": {
+    "jsonDataType": {
+      "type": "string",
+      "description": "The JSON data type as that correlates to this data type"
+    },
+    "xsdDataType": {
+      "type": "string",
+      "description": "The XML Schema data type as that correlates to this data type"
+    }
+  },
+  "required": []
+}
+```
+#### akm/extensions/data_types.json
+ ```JSON
+{
+  "id": "boolean",
+  "name": "boolean",
+  "definition": "A binary data type that represents two possible values- true or false",
+  "entityTypeID": "DataType",
+  "jsonDataType": "boolean",
+  "xsdDataType": "xsd:boolean"
+}
+```
+ ```JSON
+{
+  "id": "int16",
+  "name": "int16",
+  "definition": "16-bit signed integer for range -32768 to 32767",
+  "entityTypeID": "DataType",
+  "jsonDataType": "json:integer",
+  "xsdDataType": "xsd:short",
+  "min": -32768,
+  "max": 32767
+}
+```

akm/documentation/content/overview/_index.md

@@ -1,13 +1,14 @@
+
 ---
 title: Overview
 weight: 10
 chapter: true
 ---
 
 # Overview
-The Automotive Knowledge Model (AKM) introduces a data model and metadata catalog for transmitting vehicle signals in a consistent manner.  AKM comprises two major sections:
-## Data Model
-The data model ensures that objects are described by a standard set of well-defined structures and properties.  The schema is represented in [JSON Schema](https://json-schema.org/) which provides many benefits:
+The Automotive Knowledge Model (AKM) is an expressive and extensible semantics and standards-based vocabulary and data model for automobiles.  It is defined in two major sections:
+## Schema
+The schema describes the AKM data model.  The schema is represented in [JSON Schema](https://json-schema.org/) which provides many benefits:
 
  - The standard is well-known, documented, and easy to read
  - It has a large ecosystem of [tools and implementations](https://json-schema.org/implementations) such as validators, code generators, and format converters.
@@ -19,3 +20,5 @@ The data model ensures that objects are described by a standard set of well-defi
 
 ![alt text](images/Model.PNG "Data Model")
 
+## Data
+The data includes json files that contain reference data such as standard data types and units, as well as common and generally useful master data such as metrics, features of interest, and properties.

akm/documentation/content/principles/_index.md

@@ -1,3 +1,4 @@
+
 ---
 title: "Principles"
 date: 2021-07-05T15:12:25+02:00
@@ -25,7 +26,7 @@ Vehicle information is highly connected, so the AKM allows objects to refer to r
   - The front passenger HVAC station can indicate that it is a HVAC station.
   - The rear driver-side door can indicate that it is a cabin door.
 - Peer-to-peer associations
-  - The Vehicle.Speed metric can indicate that its feature of interest is the Vehicle, and that its property is Speed.
+  - The VehicleTravel.Speed metric can indicate that its feature of interest is VehicleTravel, and that its property is Speed.
   - The Speed property can indicate that its default unit of measurement is kilometer per hour, and that its data type is float.
 
 ## Atomic
@@ -37,11 +38,11 @@ An atomic concept is the smallest unit of meaning that can be modeled.   Separat
 - Ease data mapping and improve communication between data providers and consumers.
 
 ## Extensible
-Extensibility is the ability to add capabilities without rewriting code or changing its basic architecture.   Extensibility allows users and their software systems to quickly adapt to dynamic market and technology conditions.  The AKM is designed so that users can extend the schema with new classes, objects, properties, and attributes without breaking existing code.  Generally useful extensions can be submitted to the repository for review and acceptance. 
+Extensibility is the ability to add capabilities without rewriting code or changing the basic architecture.   Extensibility allows users and their software systems to quickly adapt to dynamic market and technology conditions.  The AKM is designed so that users can extend the schema with new classes, objects, properties, and attributes without breaking existing code.  Generally useful extensions can be submitted to the repository for review and acceptance. 
 
 Some ways that AKM provides extensibility are:
 - The model eschews enumerations in favor of explicit objects.  Instead of an enumeration of data types, for instance, the model defines a DataType class whose members are stored as json objects.
-- The model discourages the use of discrete identifiers (sometimes called "magic numbers").  For instance, rather than encode metric information in a field value as *Vehicle.Speed.KilometerPerHour.UInt8*, the metric explicitly articulates that information as *featureOfinterest: Vehicle, property: Speed, Unit: km/h*, and *dataType: uInt8*.
+- The model discourages the use of discrete identifiers (sometimes called "magic numbers").  For instance, rather than encode metric information in a field value as *Vehicle.Speed.KilometerPerHour.UInt8*, the metric explicitly articulates that information as *featureOfinterest: VehicleTravel, property: Speed, Unit: kilometer_per_hour*, and *dataType: uint8*.
 - Custom extensions are ignored by any validation or tools provided in the public repository.
 - The information is expressive and articulate enough to support the inference and automation enabled by formal knowledge systems like ontologies.
 

akm/documentation/content/schema/_index.md

@@ -14,11 +14,4 @@ AKM uses JSON schema files files that express the format of AKM data objects.
 - Validate the structures and values in AKM data objects
 - Leverage widely-available JSON and JSON Schema tooling
 
-At this stage, all document types and properties are contained in a single **DRAFT** file: automotive_knowledge_model.json
-
-Remaining work includes:
-
-- Ensure the JSON Schema documents can be used to validate JSON files.
-- Organize the JSON Schema documents into the most efficient, extensible, and understandable set of files and folders
-
-
+At this stage, all document types and properties are contained in a single file: automotive_knowledge_model.json