MosisService/portal/internal/web/docs/api/manifest.md

# Manifest Reference

Every Mosis app requires a `manifest.json` file in the root of the package. This file describes your app and its requirements.

## Complete Schema

```json
{
  "id": "com.example.myapp",
  "name": "My App",
  "version": "1.0.0",
  "version_code": 1,
  "entry": "assets/main.rml",
  "permissions": [],
  "min_mosis_version": "1.0.0",
  "author": {
    "name": "Developer Name",
    "email": "dev@example.com",
    "url": "https://example.com"
  },
  "icons": {
    "32": "icons/icon-32.png",
    "64": "icons/icon-64.png",
    "128": "icons/icon-128.png"
  },
  "description": "A short description of your app",
  "category": "utilities",
  "screenshots": [
    "screenshots/1.png",
    "screenshots/2.png"
  ],
  "locales": {
    "default": "en",
    "supported": ["en", "es", "fr"]
  }
}
```

## Required Fields

### id

**Type:** `string`

Unique package identifier in reverse domain notation. Must match the ID registered in the developer portal.

```json
"id": "com.yourcompany.appname"
```

Rules:
- Lowercase letters, numbers, and periods only
- Must have at least two segments (e.g., `com.app`)
- Maximum 255 characters
- Cannot start or end with a period

### name

**Type:** `string`

Display name shown to users. Maximum 50 characters.

```json
"name": "My Awesome App"
```

### version

**Type:** `string`

Human-readable version string following semantic versioning (MAJOR.MINOR.PATCH).

```json
"version": "1.0.0"
"version": "2.1.3-beta"
```

### version_code

**Type:** `integer`

Numeric version code that must increase with each release. Used to determine if an update is available.

```json
"version_code": 1
```

Rules:
- Must be a positive integer
- Must be greater than all previously published versions
- Maximum value: 2147483647

### entry

**Type:** `string`

Path to the main RML file, relative to package root.

```json
"entry": "assets/main.rml"
```

### author

**Type:** `object`

Information about the app developer.

```json
"author": {
  "name": "Developer Name",
  "email": "dev@example.com",
  "url": "https://example.com"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | Yes | Developer or company name |
| `email` | string | Yes | Contact email |
| `url` | string | No | Website URL |

### icons

**Type:** `object`

App icons at various sizes. At minimum, provide a 128px icon.

```json
"icons": {
  "32": "icons/icon-32.png",
  "64": "icons/icon-64.png",
  "128": "icons/icon-128.png"
}
```

Supported sizes: 32, 64, 128, 256, 512

Requirements:
- PNG format recommended
- Square aspect ratio
- No transparency on edges (for proper display)

## Optional Fields

### description

**Type:** `string`

Short description shown in app listings. Maximum 200 characters.

```json
"description": "A simple calculator for everyday math."
```

### permissions

**Type:** `array<string>`

List of permissions your app requires. Apps cannot access restricted features without declaring permissions.

```json
"permissions": ["storage", "network"]
```

See [Permissions](#permissions-reference) below.

### min_mosis_version

**Type:** `string`

Minimum Mosis version required to run this app.

```json
"min_mosis_version": "1.0.0"
```

If omitted, defaults to `"1.0.0"`.

### category

**Type:** `string`

App store category for discovery.

```json
"category": "productivity"
```

Valid categories:
- `games`
- `entertainment`
- `productivity`
- `utilities`
- `social`
- `communication`
- `lifestyle`
- `education`
- `health`
- `finance`
- `news`
- `other`

### screenshots

**Type:** `array<string>`

Paths to screenshot images for app store listing.

```json
"screenshots": [
  "screenshots/home.png",
  "screenshots/settings.png",
  "screenshots/detail.png"
]
```

Requirements:
- PNG format
- 1080x1920 (9:16 portrait) recommended
- Maximum 5 screenshots

### locales

**Type:** `object`

Internationalization configuration.

```json
"locales": {
  "default": "en",
  "supported": ["en", "es", "fr", "de", "ja"]
}
```

| Field | Type | Description |
|-------|------|-------------|
| `default` | string | Default locale code |
| `supported` | array | List of supported locale codes |

Locale files should be placed in `locales/{code}.json`.

## Permissions Reference

| Permission | Description | Example Use |
|------------|-------------|-------------|
| `storage` | Persist data locally | Save user preferences |
| `network` | Make HTTP requests | Fetch remote data |
| `clipboard` | Read/write clipboard | Copy text |
| `notifications` | Show notifications | Reminders |
| `camera` | Access device camera | Photo capture |
| `location` | Get device location | Maps, weather |
| `contacts` | Read contacts | Contact picker |
| `microphone` | Record audio | Voice notes |

### Permission Declaration

```json
"permissions": [
  "storage",
  "network"
]
```

Users are informed of permissions before installing. Request only what you need.

## Validation

The package builder validates your manifest. Common errors:

| Error | Cause | Solution |
|-------|-------|----------|
| `Invalid package ID` | ID doesn't match pattern | Use `com.company.app` format |
| `Missing required field` | Required field omitted | Add the field |
| `Invalid version_code` | Not a positive integer | Use positive number |
| `Icon not found` | Icon path doesn't exist | Check file paths |
| `Invalid permission` | Unknown permission | Use valid permission name |

## Example: Minimal Manifest

```json
{
  "id": "com.example.hello",
  "name": "Hello World",
  "version": "1.0.0",
  "version_code": 1,
  "entry": "main.rml",
  "author": {
    "name": "Developer",
    "email": "dev@example.com"
  },
  "icons": {
    "128": "icon.png"
  }
}
```

## Example: Full Manifest

```json
{
  "id": "com.acme.calculator",
  "name": "ACME Calculator",
  "version": "2.1.0",
  "version_code": 5,
  "entry": "assets/main.rml",
  "description": "A powerful calculator with scientific functions.",
  "category": "utilities",
  "permissions": [
    "storage",
    "clipboard"
  ],
  "min_mosis_version": "1.2.0",
  "author": {
    "name": "ACME Corp",
    "email": "apps@acme.com",
    "url": "https://acme.com"
  },
  "icons": {
    "32": "icons/icon-32.png",
    "64": "icons/icon-64.png",
    "128": "icons/icon-128.png",
    "256": "icons/icon-256.png"
  },
  "screenshots": [
    "screenshots/basic.png",
    "screenshots/scientific.png",
    "screenshots/history.png"
  ],
  "locales": {
    "default": "en",
    "supported": ["en", "es", "fr", "de"]
  }
}
```

## Next Steps

- [Getting Started](../getting-started.md) - Create your first app
- [Permissions Guide](../guides/permissions.md) - Understanding permissions
- [Publishing Guide](../guides/publishing.md) - Submit your app