# vesperprofiled-config-schema

Schema definitions package for VesperOS configuration profiles.

Installed at `/usr/share/vesperprofiled/schema/profile.schema.yml`.

---

## What this package does

`vesperprofiled` reads this schema at startup to determine which payload types and fields are valid for the current installation. Any `.vconfig` profile containing a payload type not listed in `allowed-payload-types` will be **rejected at install time** with a clear error.

Shipping the schema separately from the daemon means:

- **Independent updates** — schema additions (new payload types, new optional fields) don't require rebuilding or reflashing the daemon binary.
- **OEM restriction** — OEMs building VesperOS-based products can ship a trimmed schema that only exposes the configuration surface their platform supports. A digital signage OEM might allow only `wifi`, `cert`, `kiosk`, and `mdm`. An enterprise desktop OEM might allow everything except `kiosk` and `asam`.
- **Schema versioning** — the `schema-version` field is checked by the daemon at startup. A newer daemon with an older schema is always fine. An older daemon with a newer schema logs a warning and falls back to its compiled-in defaults.

---

## OEM customisation

To restrict available payload types, create a replacement Debian package:

**1. Copy and trim the schema**

```bash
cp /usr/share/vesperprofiled/schema/profile.schema.yml \
   my-schema/profile.schema.yml

# Edit my-schema/profile.schema.yml:
# - Remove payload type entries from allowed-payload-types
# - Remove their blocks from the payloads: section
# - Bump schema-version if you consider this a new schema variant
```

**2. Create your package**

`debian/control`:
```
Package: my-vesperos-config-schema
Architecture: all
Depends: ${misc:Depends}
Provides: vesperprofiled-config-schema
Conflicts: vesperprofiled-config-schema
Replaces: vesperprofiled-config-schema
Description: Trimmed VesperOS profile schema for My Product
 Only allows: wifi, cert, mdm, kiosk, passcode, restrictions.
```

`debian/rules`:
```makefile
#!/usr/bin/make -f
%:
	dh $@
override_dh_auto_install:
	install -Dm 0644 profile.schema.yml \
		debian/my-vesperos-config-schema/usr/share/vesperprofiled/schema/profile.schema.yml
```

**3. Add to your product package list**

```makefile
# In your VesperOS device makefile or product.mk:
PRODUCT_PACKAGES += my-vesperos-config-schema
```

Because your package `Provides: vesperprofiled-config-schema` and `Conflicts: vesperprofiled-config-schema`, `apt` will automatically use yours in place of the default when both are available.

---

## Schema versioning

The `schema-version` field in the YAML file follows `MAJOR.MINOR.PATCH`:

- **PATCH** — non-breaking: new optional fields added to existing payload types.
- **MINOR** — new payload types added to `allowed-payload-types`. Older daemons that don't know the new type will accept profiles containing it but log a warning and skip the unknown payload.
- **MAJOR** — breaking: required fields renamed, payload types removed, or semantics changed. Daemons older than this MAJOR version must not run with a schema of a higher MAJOR version.

---

## Building the package

```bash
dpkg-buildpackage -us -uc -b -A   # Architecture: all, no signing
```

---

## Files installed

```
/usr/share/vesperprofiled/schema/profile.schema.yml
```