From 006a01aa0474b92b51d37ad5a602c20b3940faa7 Mon Sep 17 00:00:00 2001 From: Kindson The Genius <35315234+KindsonTheGenius@users.noreply.github.com> Date: Mon, 10 Jul 2023 12:19:54 +0000 Subject: [PATCH] Updated decorations documentations. Replaced Cadl with Typespec --- docs/cadl-doc.md | 72 +++++++++++++-------------- docs/custom-attributes.md | 89 ---------------------------------- docs/decorators-users-guide.md | 15 +++++- docs/faqs.md | 4 +- website/sidebars.js | 3 +- 5 files changed, 52 insertions(+), 131 deletions(-) delete mode 100644 docs/custom-attributes.md diff --git a/docs/cadl-doc.md b/docs/cadl-doc.md index 9d30f1dd8..f30e5570e 100644 --- a/docs/cadl-doc.md +++ b/docs/cadl-doc.md @@ -1,16 +1,16 @@ --- -id: morphir-cadl-mapping -title: Morphir-Cadl Mapping +id: morphir-typespec-mapping +title: Morphir-TypeSpec Mapping --- -# Morphir-Cadl Mapping -## [Morphir](https://package.elm-lang.org/packages/finos/morphir-elm/18.1.0/Morphir-IR-Type) to [Cadl Type](https://microsoft.github.io/cadl/docs/language-basics/type-relations/) Mappings -This is a documentation of the mapping strategy from Morphir types to Cadl types. This document describes how types in Morphir Models are represented in Cadl. +# Morphir-Typespec Mapping +## [Morphir](https://package.elm-lang.org/packages/finos/morphir-elm/18.1.0/Morphir-IR-Type) to [TypeSpec Type](https://microsoft.github.io/typespec/language-basics/type-relations/) Mappings +This is a documentation of the mapping strategy from Morphir types to Typespec types. This document describes how types in Morphir Models are represented in Typespec. Below is a quick overview of the mapping in the table: -| | Type | Cadl Type | Comment | +| | Type | TypeSpec Type | Comment | |-------------------------------------------------------|--------------------------------------------|-----------------------------------|-----------------------------------------------------| | [Basic Types](#basic-types) | | | | | | `Bool` | `boolean` | | @@ -47,7 +47,7 @@ Elm: type alias IsApplicable = Bool ``` -Cadl +TypeSpec ``` alias IsApplicable = boolean; ``` @@ -61,13 +61,13 @@ Elm: type alias Foo = Int ``` -Cadl: +TypeSpec: ```cadl alias Foo = int64; ``` ***Note:*** -The `integer` type assignment is valid in Cadl but would default to **object** when dealing with the **OAS emitters**. +The `integer` type assignment is valid in TypeSpec but would default to **object** when dealing with the **OAS emitters**. ##### [Float](https://package.elm-lang.org/packages/elm/core/latest/Basics#Float) The `Float` type; floating point number, in morphir maps directly to the `float` type in CADL. @@ -77,13 +77,13 @@ Elm: type alias Pi = Float ``` -Cadl: +TypeSpec: ```cadl alias Pi = float64; ``` ***Note:***> -The `float` type assignment is valid in Cadl but would default to **object** when dealing with the **OAS emitters**. +The `float` type assignment is valid in TypeSpec but would default to **object** when dealing with the **OAS emitters**. ##### [String](https://package.elm-lang.org/packages/finos/morphir-elm/18.1.0/Morphir-SDK-String) The `String` type; a sequence of characters, in morphir maps directly to `string` type in CADL. @@ -93,20 +93,20 @@ Elm: type alias Address = String ``` -Cadl: +TypeSpec: ```cadl alias Address = string ; ``` ##### [Char](https://package.elm-lang.org/packages/elm/core/latest/Char) -The `char` type is a single character type in morphir and doesn't exist in Cadl. An alternative mapping is the `string` type. +The `char` type is a single character type in morphir and doesn't exist in TypeSpec. An alternative mapping is the `string` type. Elm: ``` elm type alias AccountGroup = Char ``` -Cadl: +TypeSpec: ```cadl alias AccountGroup = string; ``` @@ -122,7 +122,7 @@ import Morphir.SDK.Decimal exposing (Decimal) type alias Price = Decimal ``` -Cadl: +TypeSpec: ```cadl alias Price = string ``` @@ -136,7 +136,7 @@ import Morphir.SDK.LocalDate exposing (LocalDate) type alias DateOfBirth = LocalDate ``` -Cadl: +TypeSpec: ```cadl alias dateOfBirth = plainDate; ``` @@ -150,7 +150,7 @@ import Morphir.SDK.LocalTime exposing (LocalTime) type alias CurrentTime = LocalTime ``` -Cadl: +TypeSpec: ```cadl alias currentTime = plainTime; ``` @@ -166,13 +166,13 @@ import Morphir.SDK.Month exposing (Month) type alias CurrentMonth = Month ``` -Cadl: +TypeSpec: ```cadl alias purchaseMonth = string; ``` ##### [Optional Values(Maybe)](https://package.elm-lang.org/packages/elm/core/latest/Maybe) -The `maybe` type in morphir represents a type that may or may not exist. The type could exist as a standalone type or a field type in a record and both scenarios are supported directly in Cadl. +The `maybe` type in morphir represents a type that may or may not exist. The type could exist as a standalone type or a field type in a record and both scenarios are supported directly in TypeSpec. 1. `maybe` as a standalone type, is presented in cadl as a union of the type or null using the pipe `|` syntax. @@ -181,12 +181,12 @@ The `maybe` type in morphir represents a type that may or may not exist. The typ type alias Foo = Maybe Int ``` - Cadl: + TypeSpec: ```cadl alias Foo = int64 | null ``` -2. `maybe` as a field type in a record, is represented as `optional field` in a model in cadl using `optional field` `?:` syntax. +2. `maybe` as a field type in a record, is represented as `optional field` in a model in TypeSpec using `optional field` `?:` syntax. Elm: ```elm @@ -196,7 +196,7 @@ The `maybe` type in morphir represents a type that may or may not exist. The typ , baz: Maybe String } ``` - Cadl: + TypeSpec: ```cadl model FooBarBaz { foo : int64; @@ -215,7 +215,7 @@ The `maybe` type in morphir represents a type that may or may not exist. The typ , baz: Maybe (Maybe String) } ``` - Cadl: + TypeSpec: ```cadl model FooBarBaz { foo : int64; @@ -238,7 +238,7 @@ type alias Foo = type alias Bar a = List a ``` -Cadl: +TypeSpec: ```cadl alias Foo = Array; @@ -256,7 +256,7 @@ type alias Foo = type alias Bar a = Set a ``` -Cadl: +TypeSpec: ```cadl alias Foo = Array; @@ -275,7 +275,7 @@ type alias Foo = type alias Bar a b = Dict a b ``` -Cadl +TypeSpec ```cadl alias Foo = Array<[string,int64]>; @@ -291,7 +291,7 @@ Elm: type alias Foo e v= Result e v ``` -Cadl: +TypeSpec: ```cadl alias Foo = ["Err", E] | ["Ok", V]; ``` @@ -308,7 +308,7 @@ type alias Foo = type alias Bar a b = ( a, b ) ``` -Cadl: +TypeSpec: ```cadl alias Foo = [string, int64]; @@ -326,7 +326,7 @@ type alias FooBarBaz = , baz: Float } ``` -Cadl: +TypeSpec: ```cadl model FooBarBaz { foo: integer, @@ -348,7 +348,7 @@ type FooBarBaz | Bar ``` -Cadl: +TypeSpec: ```cadl alias FooBarBaz = ["Foo", int64] | ["Bar", string] | "Baz"; ``` @@ -362,7 +362,7 @@ type Currency | GBP | GHS ``` -Cadl: +TypeSpec: ``` enum Currency { USD, @@ -372,20 +372,20 @@ enum Currency { ``` -# Mapping [Cadl feature concepts](https://microsoft.github.io/cadl/language-basics/overview) to [Morphir](https://package.elm-lang.org/packages/finos/morphir-elm/18.1.0/Morphir-IR-Type) +# Mapping [TypeSpec feature concepts](https://microsoft.github.io/typespec/language-basics/overview) to [Morphir](https://package.elm-lang.org/packages/finos/morphir-elm/18.1.0/Morphir-IR-Type) --- | | CADL Type | Morphir Type | Comment | |----------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Namespaces](https://microsoft.github.io/cadl/language-basics/namespaces) | `namespace Petstore` | `module PetStore exposing (...)` | Namespaces in CADL map to [Modules](https://package.elm-lang.org/packages/Morgan-Stanley/morphir-elm/latest/Morphir-IR-Module) in Morphir | -| [Models](https://microsoft.github.io/cadl/language-basics/models) | `model Dog { name: string; age: number}` | `type alias Dog = { name: string, age: int}` | Models in CADL map to [Records](https://package.elm-lang.org/packages/finos/morphir-elm/18.1.0/Morphir-IR-Value#record) in Morphir | -| [Enums](https://microsoft.github.io/cadl/language-basics/enums) | `enum Direction {East; West; North; South}` | `type Direction `
`= East` | `West` | `North` | `South` | Enums in CADL map to [Union Types](https://package.elm-lang.org/packages/finos/morphir-elm/18.1.0/Morphir-IR-Type) in Mophir | +| [Namespaces](https://microsoft.github.io/typespec/language-basics/namespaces) | `namespace Petstore` | `module PetStore exposing (...)` | Namespaces in CADL map to [Modules](https://package.elm-lang.org/packages/Morgan-Stanley/morphir-elm/latest/Morphir-IR-Module) in Morphir | +| [Models](https://microsoft.github.io/typespec/language-basics/models) | `model Dog { name: string; age: number}` | `type alias Dog = { name: string, age: int}` | Models in CADL map to [Records](https://package.elm-lang.org/packages/finos/morphir-elm/18.1.0/Morphir-IR-Value#record) in Morphir | +| [Enums](https://microsoft.github.io/typespec/language-basics/enums) | `enum Direction {East; West; North; South}` | `type Direction `
`= East` | `West` | `North` | `South` | Enums in CADL map to [Union Types](https://package.elm-lang.org/packages/finos/morphir-elm/18.1.0/Morphir-IR-Type) in Mophir | | [Union Type](https://package.elm-lang.org/packages/finos/morphir-elm/18.1.0/Morphir-IR-Type) ||| | | - Unnamed Union
`alias Breed = Breagle` | `GermanShepherd` | `GoldenRetriever`
- Named Union
`union Breed {`
  `beagle: Beagle,`
  `shepherd: GermanShepherd.`
  `retiever: GoldenRetriever`
`}` | `type Breed`
  `= Beagle Beagle`
    | `Shepherd GermanShepherd `
    | `Retriever GoldenRetriever` | Named unions in CADL maps to a Custom Type with a `type parameter` in Morphir. Any other detail of the type is captured in Morphir's `Decorators(Custom Attributes).`
NB: unnamed Unions are currently not supported in morphir | -## [Type Relations](https://microsoft.github.io/cadl/language-basics/type-relations) +## [Type Relations](https://microsoft.github.io/typespec/language-basics/type-relations) ##### Boolean Boolean in CADL, maps to [`bool`](https://package.elm-lang.org/packages/elm/core/latest/Basics#Bool), a `true` or `false` value in Morphir. diff --git a/docs/custom-attributes.md b/docs/custom-attributes.md deleted file mode 100644 index 9fc064b99..000000000 --- a/docs/custom-attributes.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -id: custom-attributes-users-guide ---- - -# Custom attributes user guide - -The contents of this document detail how to structure and load optional "sidecar" files for the purposes of adding custom attributes to Morphir types and values. Custom attributes can assign extra information to business concepts that is otherwise not included in the Morphir IR. - -**Contents:** - -- [File format and naming convention](#file-format-and-naming-convention) - - [Config file](#config-file) - - [Attribute file](#attribute-file) -- [Loading and updating the attribute files](#loading-and-updating-the-attribute-files) - -## File format, and naming convention - -To define a custom attribute, we need at least three JSON files. - -1. A config file named `attribute.conf.json` that lists the attribute ID's, and maps them to display names. -2. At least one attribute file named `.json` in the `attributes`. -3. An IR containing a type definitions - -### Config file - -``` -{ - "test-id-1": { - "displayName" : "MS.Sensitivity" - , "entryPoint" : "Morphir.Attribute.Model.Sensitivity.Sensitivity" - , "ir" : "attributes/sensitivity.ir.json" - } - "test-id-2": { - ... - } -} -``` - -The above example is a sample config file structure. The config file should contain key-value pairs in a JSON format, where the key is the attribute name, and the value is the attribute description. -The attribute description should include an entrypoint in the form of an [FQName](https://package.elm-lang.org/packages/finos/morphir-elm/latest/Morphir.IR.FQName) (this is the type describing your custom attribute), a display name, and a path to the IR file containing your type model - -### Attribute file - -``` -{ - "Morphir.Reference.Model.Issues.Issue401:bar": { - "MNPI": false, - "PII": true - }, - "Morphir.Reference.Model.Issues.Issue401:foo": { - "MNPI": false, - "PII": false - } -} -``` - -The above example is a sample attribute file structure. The attribute file should be a dictionary in a JSON format, where the keys are Morphir [FQName](https://package.elm-lang.org/packages/finos/morphir-elm/latest/Morphir.IR.FQName)s, and the values are any valid JSON object. - -## Loading and updating the attribute files - -We currently provide the following APIs. - -**_GET /server/attributes/_** -Returns the a JSON file with a very similar structure to the config file, but amended with `data` fields containing the actual custom attribute values, and the `ir` field containing the actual IR instead of a path pointing to it - -``` -{ - "test-id-1": { - "displayName" : - , "entryPoint" : - , "ir" : "" - , "data" : - } - "test-id-2": { - ... - } -} -``` - -**_POST /server/updateattribute/\_** - -``` -{ - "nodeId" : , - "newAttribute: -} -``` - -Updates the given node with the given new attribute. diff --git a/docs/decorators-users-guide.md b/docs/decorators-users-guide.md index 32ce262f0..e6fce872e 100644 --- a/docs/decorators-users-guide.md +++ b/docs/decorators-users-guide.md @@ -12,11 +12,13 @@ format that all Morphir tools integrate with. Now let's see how you can set them up. This can be done in a few easy steps: -- [Create or find the Morphir IR that describes the decoration](#create-or-find-the-morphir-ir-that-describes-the-decoration) +- [Create or find a Decoration Schema](#create-or-find-a-decoration-schema) - [Set up the decoration for your model](#set-up-the-decoration-for-your-model) - [Start adding decorations](#start-adding-decorations) +- [Using the morphir decoration-setup Command](#using-the-morphir-decoration-setup-command) -## Create or find the Morphir IR that describes the decoration + +## Create or find a Decoration Schema The first thing you will need is a Morphir IR that describes the shape of the decoration. If you want to use an existing decoration you just need to make sure you have access to the `morphir-ir.json` for it. If you want to create your own @@ -54,6 +56,10 @@ Each decoration section should include: - there is a type in that module that matches the third part of the entry point - a storage location that specifies where the decoration data will be saved +## Using the morphir decoration-setup Command +The above step can be automated using the `morphir decoration-setup` command from the location containing the decoration IR. +You can also provide the path to the decoration IR using the `-i` flag + ## Start adding decorations Once this is all set up you can use Morphir Web to start adding decorations on your model. First you need to run @@ -73,3 +79,8 @@ If you open the file you should see something like this: It's an object with a node id that identifies the part of the model that you put the decoration on, and a value that you specified in the UI. + +## Consuming Existing Decoration Schemas +You may also want to use existing decoration schema available in the NPM repository. +Once you've found and installed the decoration schema, you can run the `morphir decoration-setup` command to set up the decorations. +Then you can [start adding decorations](#start-adding-decorations) \ No newline at end of file diff --git a/docs/faqs.md b/docs/faqs.md index a29680fb1..a2119556c 100644 --- a/docs/faqs.md +++ b/docs/faqs.md @@ -6,7 +6,7 @@ title: FAQs # Frequently Asked Questions ### How Do I Generate the Scala Codecs? -Run the command `morphir-elm gen -s` +Run the command `morphir scala-gen -s` ### How Do I Generate the JSON Schema for my model -Run the `morphir json-schema-gen` command \ No newline at end of file +Run the command `morphir json-schema-gen` \ No newline at end of file diff --git a/website/sidebars.js b/website/sidebars.js index a5a53afe8..d537dc83f 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -114,8 +114,7 @@ const sidebars = { 'springboot-generator', 'json-codecs-doc', 'decorations-users-guide', - 'custom-attributes-users-guide', - 'morphir-cadl-mapping', + 'morphir-typespec-mapping', 'insight-api-guide', ] },