Merge pull request #2 from COVESA/akm-doc-update

Add initial version of akm documentation

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "akm/documentation/themes/learn"]
+	path = akm/documentation/themes/learn
+	url = https://github.com/matcornic/hugo-theme-learn.git

akm/documentation/README.md

@@ -0,0 +1,62 @@
+# 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 static webpage is generated automatically after every PR merged to master
+and deployed into a branch called `gh-pages`.
+
+
+### Dependencies
+
+The static page is generated with:
+
+- [HUGO](https://gohugo.io/)
+- [Learn Theme](https://themes.gohugo.io/hugo-theme-learn/)
+
+Please follow the [documentation](https://gohugo.io/documentation/) for installation and further questions around the framework.
+
+### Run the documentation server locally
+
+Once hugo is installed please follow the following steps:
+
+#### Check that HUGO is working:
+```
+hugo version
+```
+The following outcome is expected:
+
+```
+Hugo Static Site Generator v0.xx.xx ...
+```
+
+#### Clone the submodule containing the theme
+
+Run the following git commands to init and fetch the submodules:
+
+```
+git submodule init
+git submodule update
+```
+
+Reference: [Git Documentation](https://git-scm.com/book/en/v2/Git-Tools-Submodules).
+
+#### Test locally on your server:
+
+Within the repository
+
+```
+hugo server -D -s akm/documentation
+```
+
+Optional ```-D:``` include draft pages as well. Afterwards, you can access the
+page under http://localhost:1313/Automotive_Knowledge_Model/
+
+### Contribute
+
+If you want to contribute, do the following:
+
+1. **Change documentation in ```/documentation```**
+
+1. **Test your changes locally, as described above**
+
+1. **Create Pull Request for review**

akm/documentation/config.toml

@@ -0,0 +1,27 @@
+baseURL = "https://localhost/Automotive_Knowledge_Model/"
+languageCode = "en-us"
+title = "Automotive Knowledge Model"
+theme = "learn"
+publishDir = "../docs"
+[params]
+  # Change default color scheme with a variant one. Can be "red", "blue", "green".
+  themeVariant = "blue"
+  disableInlineCopyToClipBoard = true
+  editURL = "https://localhost/automotive_knowledge_model/edit/master/docs-gen/content/"
+  disableLandingPageButton = true
+
+
+[[menu.shortcuts]]
+name = "<i class='fab fa-github'></i> Github repo"
+identifier = "ds"
+url = "https://github.com/COVESA/akm"
+weight = 10
+
+[[menu.shortcuts]]
+name = "<i class='fas fa-download'></i> Releases"
+url = "https://github.com/COVESA/akm/releases"
+weight = 12
+
+# Generation of JSON index to allow search
+[outputs]
+home = [ "HTML", "RSS", "JSON"]

akm/documentation/content/_index.md

@@ -0,0 +1,13 @@
+---
+title: "Automotive Knowledge Model"
+---
+
+# Automotive Knowledge Model (AKM)
+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 here [AKM github repository](https://github.com/COVESA/akm).
+
+
+
+

akm/documentation/content/ecosystem/_index.md

@@ -0,0 +1,6 @@
+---
+title: "Ecosystem"
+chapter: true
+weight: 60
+---
+

akm/documentation/content/ecosystem/tools.md

@@ -0,0 +1,11 @@
+---
+title: "Tools"
+weight: 1
+---
+
+The AKM can be transformed into other formats or integrate with other tooling environments and ecosystems.
+
+AKM-tools provide tooling to generate data model artifacts in different formats.
+
+
+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/governance/_index.md

@@ -0,0 +1,7 @@
+---
+title: Governance
+weight: 100
+chapter: false
+---
+
+    TBD

akm/documentation/content/license/_index.md

@@ -0,0 +1,7 @@
+---
+title: License
+weight: 70
+chapter: false
+---
+
+    TBD

akm/documentation/content/overview/_index.md

@@ -0,0 +1,24 @@
+
+---
+title: Overview
+weight: 10
+chapter: true
+---
+
+# Overview
+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.
+ - It provides built-in support for creating an expressive schema with such things as objects, properties, references, arrays,  enumerations, extensions, and regular expressions.
+ - It is self-documenting
+
+ ### Diagram
+ The diagram below captures most of the classes and their relationships.
+
+![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

@@ -0,0 +1,67 @@
+
+---
+title: "Principles"
+chapter: true
+weight: 20
+---
+
+# Principles
+
+This page covers some of the principles that guided the creation of the AKM and that should be followed when contributing to it.
+
+
+## Data-Centric
+A layered design that separates data from algorithms increases opportunities for extension, reuse, and independent development.  The AKM is intended to represent the things that exist in the vehicle information domain with no bias toward any particular use by vehicle or software components. The following practices support this principle:
+- Every entry within the AKM has an explicit unique identifier so it can be directly accessed
+- References from one entry to another are explicitly expressed rather than encoded within a field or implied by other means such as its position in a file or folder.
+- The AKM makes no assumptions about query patterns and is expressive enough to derive graphs, tables, trees, various types of files, and other derived structures deemed useful.
+
+## Connected 
+Vehicle information is highly connected, so the AKM allows objects to refer to related objects.  Examples include:
+- Part-to-Whole relationships using the ***partOf*** property
+  - The driver's seatbelt can refer to the driver's seat that contains it.
+  - The radio can indicate that it is part of the infotainment system.
+- Generalization inheritance using the ***isA*** property
+  - 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 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
+An atomic concept is the smallest unit of meaning that can be modeled.   Separating concepts into their atomic components allows for more flexibility, accuracy, and efficiency in storing and querying data.  The AKM maintains separate objects for metrics, features of interest, data and object properties, units of measurement, and data types.  It includes embedded objects for deprecation facts and mappings to other schemas.  Separating objects and properties by their atomic meanings provides several advantages.
+
+- Reduce errors in software and database development by ensuring that data is consistent and valid.
+- Increase consistency in documentation and system design by using common terms, patterns, and standards.
+- Improve application and database performance by minimizing data redundancy and optimizing data structures.
+- Ease data mapping and improve communication between data providers and consumers.
+
+## Extensible
+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: 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.
+
+## Standardized
+Standards allow information to flow seamlessly between systems and organizations.  AKM is designed to promote internal consistency by providing a well-defined set of objects that represent vehicle metrics.  
+### Internal Standards
+AKM employs standards to ensure its quality and consistency.
+
+- Objects inherit from a standard ***Entity*** that defines common properties such as name, definition, comment, etc.
+- All objects and properties fields include their definition using the JSON Schema ***description*** keyword.
+### External Standards
+AKM is also designed to utilize external standards.
+#### Standard Schema Language
+[JSON Schema](https://json-schema.org/)  is a well-known vocabulary that enables JSON data consistency, validity, and interoperability at scale.
+#### Common Terms and Vocabularies
+AKM tries to appropriate established terms where possible, and its main classes provide an example:
+- **Feature of Interest** is a common term in IoT vocabularies, including:
+ >- [SOSA](https://www.w3.org/TR/vocab-ssn/) - the Sensor, Observation, Sample, and Actuator Ontology
+ >- [SAREF](https://saref.etsi.org/core/v3.1.1/) - the Smart Applications REFerence ontology
+ >- The [OGC SensorThings API](https://www.ogc.org/standard/sensorthings/)
+ >
+- **Property** is a term used in many programming languages to indicate an attribute that can be observed (read) or manipulated (written).
+- **Metric** is a common business intelligence term to indicate something that is measured but doesn't include the measurements themselves.

akm/documentation/content/schema/_index.md

@@ -0,0 +1,17 @@
+---
+title: Schema
+weight: 30
+chapter: true
+---
+
+# JSON Schema Files
+AKM uses JSON schema files files that express the format of AKM data objects. 
+([JSON Schema](https://json-schema.org/)) 
+
+ It is the intent that this schema can be used to:
+
+- Document the types and structure of AKM objects and properties
+- 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 file: automotive_knowledge_model.json