From 16ba236418670970ba5b03f393569260909b5f2f Mon Sep 17 00:00:00 2001 From: "Jens W. Klein" Date: Tue, 17 Oct 2023 10:58:53 +0200 Subject: [PATCH] overhaul --- source/architecture/semanticmodel.md | 72 +++++++++++++++++----------- 1 file changed, 43 insertions(+), 29 deletions(-) diff --git a/source/architecture/semanticmodel.md b/source/architecture/semanticmodel.md index 6b8be6c..34fa509 100644 --- a/source/architecture/semanticmodel.md +++ b/source/architecture/semanticmodel.md @@ -1,57 +1,71 @@ # Semantic Pass Models +## Overview + Here we provide semantic pass models primarily vendor-neutral. -There is no direct one-to-one mapping from semantic pass models to vendor-specific pass models, beecause of differences between different vendors with their proprietary pass models. +There is no direct one-to-one mapping from semantic pass models to vendor-specific pass models, because of differences between different vendors with their proprietary pass models. [mapping between existing vendor pass models](https://notificare.com/blog/2023/02/17/how-to-create-digital-passes-for-all/) [google pass converter](https://github.com/google-wallet/pass-converter) -Important: these semantic pass models are from user-centric view and not technical aspect. +```{attention} +These semantic pass models are from user-centric view and not technical aspect. +``` We shall provide: - registry of pass models - base classes for semantic pass models - declarative definition of pass models -- transformation engine from semantic model to vendor-specific pass models, where the trafos are defined declaratively - - trafos concern json data and file data +- transformation engine from semantic model to vendor-specific pass models, where the transformations are defined declaratively + - transformations concern json data and file data + +## Terminology of Semantic Model and Logic: + +### Pass Schema**: +- contains the information which fields have to or can be provided for a concrete pass template +- contains the transformation specification for the different target platforms +- validation information + +### Pass Definition** +- contains the data definition for a specific pass e.g. LMU Library Pass, but still vendor independent. -Terminology: +### ModelEngine** +- based on the fields and their constraints given in the Pass Schema, the ModelEngine validates the Pass Definition. +- based on the transformation definition given in the Pass Schema, the ModelEngine transforms the Pass Definition into a vendor specific pass models. + +### Vendor specific: + +This is not part of the sematic model, but the vendor specific packages. +Anyway, we need to know the terminology to be able to map the semantic model to the vendor specific models. + +```{hint} +Explanation of the [Google Terminology](https://developers.google.com/wallet/generic/resources/terminology) +``` -[google terminology](https://developers.google.com/wallet/generic/resources/terminology) +#### Google +- **Pass Class** like a template of a specific pass domain, i.e. the *LMU Library Cards**. +- **Pass Object** the specific pass of a person, like an instance of the Pass Class, referencing it, downloadable to the wallet on the tappers device. -- Pass Schema: - - contains the information which fields have to or can be provided for a concrete pass template - - contains the transformation specification for the different target platforms - - validation information -- Pass Definition: - contains the data definition for a specific pass e.g. LMU Library Pass, but still vendor independent. +#### Apple -- ModelEngine(TraraTrara) - based on the transformation definition given in the Pass Schema, the ModelEngine transforms the Pass Template into a vendor specific pass model and validates. +The differentiation into Pass Class and Pass Object as its done as Google is not relevant. +Apple follows a different approach to habdle passes. +Apple contains only passes stored in a `*.pkpass` file which is a .zip file with checksums and a manifest signed by certificates to make it manipulation-safe. -Vendor specific: +However, to work efficiently with passes, internally at eduTAP we decided to introduce pass templates differentiate between them and and passes as well. +We have: -- Google - - Pass Class - - Pass Object -- Apple - - Pass +- Pass Template: a pass definition that can be used to create a pass object by copy and modify. +- Pass: a pass object that can be used to create a `*.pkpass` file to be downloaded/ sent to the tapper. - the differentiation into Pass Class and Pass Object is not relevant since Apple contains only passes - stored in a .pkpass file which is a .zip file containing certificates and a manifest to make it manipulation-safe. - Internally we split it into - - Pass Template - a pass definition that can be used to create a pass object by copy&modify - - Pass - a pass object that can be used to create a .pkpass file and be sent to the user +## Sematic Model and Transformation Overview -- ```{figure} SemanticPassModel.svg :alt: semantic pass model and transformation to vendor specific passes. -Core Overview. +Sematic Model and Transformation Overview ```