Skip to content

LINGO_MAPP_SPEC.md

Latest commit

 

History

History
401 lines (317 loc) · 8.38 KB

LINGO_MAPP_SPEC.md

File metadata and controls

401 lines (317 loc) · 8.38 KB

MAPP Spec

The mtemplate system uses JSON or YAML specification files to define the structure and data for generating dynamic applications from template code. This document describes the format and requirements for these YAML spec files.

Table of Contents

Overview

The YAML/JSON spec file defines the structure for generating applications using the mtemplate system. It specifies project metadata, server/client configuration, and most importantly, the data models that will be used to generate CRUD applications with various field types.

Required Top-Level Fields

All YAML spec files must include these three top-level fields: project, server, and client.

project

The project field defines metadata about the generated application:

project:
  name:
    lower_case: 'my project name'
  description: 'A description of what this project does'
  author:
    name: 'Your Name'
    email: 'your.email@example.com'

Required subfields:

  • name.lower_case: The project name in lowercase with spaces, see Name block for more information
  • description: A text description of the project
  • author.name: The author's full name
  • author.email: The author's email address

server

The server field configures the backend server settings:

server:
  port: 8080

Required subfields:

  • port: The port number the server will listen on

client

The client field configures client-side settings:

client:
  default_host: 'http://localhost:8080'

Required subfields:

  • default_host: The default host URL the client will connect to

Modules, Models and Fields

modules

The modules field defines one or more modules, each containing related models:

modules:
  my_module:
    name:
      lower_case: 'my module name'
    models:
      # ... model definitions

Required subfields:

  • name.lower_case: The module name in lowercase with spaces, see Name block for more information
  • models: A collection of model definitions

models

Each module must contain one or more models:

models:
  user_model:
    name:
      lower_case: 'user'
    fields:
      # ... field definitions

Required subfields:

  • name.lower_case: The model name in lowercase with spaces, see Name block for more information
  • fields: A collection of field definitions

fields

Each model must contain one or more fields that define the data structure:

fields:
  username:
    type: str
    examples:
      - "john_doe"
      - "jane_smith"
    random: custom_username_generator  # optional

Required subfields:

  • type: The field data type (see Field Types)
  • examples: An array of one or more example values

Optional subfields:

  • random: Custom random generator name (overrides the default generator for the field type)

Field Types and Examples

Basic Types

bool: Boolean values

is_active:
  type: bool
  examples:
    - true
    - false

int: Integer numbers

age:
  type: int
  examples:
    - 25
    - 30
    - 45

float: Floating point numbers

price:
  type: float
  examples:
    - 19.99
    - 99.50
    - 0.99

str: String values

name:
  type: str
  examples:
    - "Alice"
    - "Bob"
    - "Charlie"

Use enum to restrict the value to a list of strings:

color:
  type: str
  enum:
    - "red"
    - "green"
    - "blue"

datetime: Date and time values (format %Y-%m-%dT%H:%M:%S per python datetime formatting)

created_at:
  type: datetime
  examples:
    - "2023-01-15T10:30:00"
    - "2023-12-25T09:00:00"

List Types

Lists can contain any of the basic types by specifying element_type:

tags:
  type: list
  element_type: str
  examples:
    - ["red", "blue", "green"]
    - ["important", "urgent"]

scores:
  type: list
  element_type: int
  examples:
    - [95, 87, 92]
    - [100]

Custom Random Generators

Fields can specify custom random generators to override the default random value generation:

username:
  type: str
  examples:
    - "alice123"
    - "bob_the_builder"
  random: random_user_name

email:
  type: str
  examples:
    - "user@example.com"
  random: random_email

phone:
  type: str
  examples:
    - "+1 (555) 123-4567"
  random: random_phone_number

Name block

Name blocks are used in several places in the spec. They define variations of a name for various casing styles.

name:
  lower_case: 'my model'
  snake_case: 'my_model'
  pascal_case: 'MyModel'
  kebab_case: 'my-model'
  camel_case: 'myModel'

For most scenarios each name can be autogenerated by mspec from just lower_case which is a human readable name using spaces between words an all lower case letters:

name:
  lower_case: 'my model'

It is recommended to only provide lower_case and let mspec autogenerate the remainder. But in edge cases where the naming conventions are not obvious the other names can be provided to overrided the generated names.

Complete Example

Here's a complete YAML spec file demonstrating all the features:

project:
  name:
    lower_case: 'my sample store'

  description: 'A sample project for mspec-alpha python app generator'

  author:
    name: 'B rad C'
    email: 'sample@email.com'

server:
  port: 7007

client:
  default_host: 'http://localhost:7007'

modules:
  store:
    name:
      lower_case: 'store'

    models:
      products:
        name:
          lower_case: 'products'

        fields:

          product_name:
            type: str
            examples:
              - 'Laptop'
              - 'Smartphone'
              - 'Tablet'

            random: random_thing_name

          price:
            type: float
            examples:
              - 999.99
              - 499.99
              - 299.99

          in_stock:
            type: bool
            examples:
              - true
              - false
      
      customers:
        name:
          lower_case: 'customers'

        fields:

          customer_name:
            type: str
            examples:
              - 'Alice'
              - 'Bob'
              - 'Charlie'
            random: random_person_name

          email:
            type: str
            examples:
              - 'alice@email.com'
              - 'bob@email.com'
            random: random_email

          phone_number:
            type: str
            examples:
              - '+1 (123) 456-7890'
              - '+1 (987) 654-3210'
            random: random_phone_number

  admin:
    name:
      lower_case: 'admin'

    models:
      employees:
        name:
          lower_case: 'employees'

        fields:

          employee_name:
            type: str
            examples:
              - 'David'
              - 'Eve'
              - 'Frank'
            random: random_person_name

          position:
            type: str
            enum:
              - 'Manager'
              - 'Sales'
              - 'Support'
            examples:
              - 'Manager'
              - 'Sales'
              - 'Support'

          hire_date:
            type: str
            examples:
              - '2000-01-11T12:34:56'
              - '2020-10-02T15:30:00'

          email:
            type: str
            examples:
              - 'my-name@email.com'
            random: random_email

          phone_number:
            type: str
            examples:
              - '+1 (123) 456-7890'
              - '+1 (987) 654-3210'
            random: random_phone_number

          salary:
            type: float
            examples:
              - 60000.00
              - 45000.00
              - 35000.00

This YAML spec file can be used with the mtemplate system to generate applications from the template code in templates/py and templates/browser1.