Validate

Validating your app's JSON against schemas.revenexx.com before you deploy, and the rules that only fail later — summary length, tag naming, event-name shape and the vendor/app key.

Every declarative file in an app has a published JSON Schema. Wiring your editor to them is the cheapest quality gate available, and it catches most of what would otherwise fail a build.

text
https://schemas.revenexx.com/manifest.schema.json
https://schemas.revenexx.com/manifest.capabilities.schema.json
https://schemas.revenexx.com/schema.schema.json
https://schemas.revenexx.com/cockpit.schema.json
https://schemas.revenexx.com/settings.schema.json
https://schemas.revenexx.com/billing.schema.json
https://schemas.revenexx.com/search.schema.json
https://schemas.revenexx.com/analytics.schema.json

Point each file at its schema with $schema and your editor validates and completes as you type:

manifest.json
{
  "$schema": "https://schemas.revenexx.com/manifest.schema.json",
  "name": "serials"
}

additionalProperties is false at every level of the manifest, so a typo'd key fails rather than being silently ignored. That is the behaviour you want: warmups: true is a bug you find in your editor instead of wondering why the app is still cold.

Validate before you deploy

The loop after any change to a declaration:

Terminal
revenexx apps capabilities --write   # regenerate manifest.capabilities.json from schema.json
revenexx apps generate               # regenerate the typed client
npm test                             # run the suite

Both generators are idempotent, so running them on an unchanged schema produces no diff — which makes a dirty working tree after them a useful signal that you forgot a step earlier.

In CI, run them and fail on a diff. An app whose generated files are out of date with its schema.json will deploy and then behave in ways the source does not explain.

What the schemas catch

  • Missing required fields — name, vendor, version, title, type in the manifest; entities in the schema; columns and a pk per entity.
  • Unknown keys, at every level.
  • Wrong types and malformed enums.
  • A permissions entry with more than one resource key, or a key that is not one of the nine.
  • An event name that is not exactly two dot-separated segments.
  • A column type that is not one of the supported PostgreSQL types.
  • A tenant_id or org_id column you tried to declare.

The rules that fail later

Some rules cannot be expressed in a single file's schema, because they are about how two files agree or about the platform-wide namespace. These pass locally and fail at apply or publish time.

Only at apply time

A dependencies or peerDependencies key that is not vendor/app. "markets": "^0.1" is a valid JSON object and an invalid dependency. See Dependencies.

A cross-app foreign key. A references naming another app's entity. See Relationships.

A notNull column with no default on a populated table, and a changed generated expression. See Migrations.

A dropped_columns tombstone the platform refuses — 422 while the column holds data or anything still references it.

Only at publish time

A summary longer than 255 characters. Put the prose in description; keep the summary to a line.

A tag naming rule. A tag must be a capability namespace this app defines or a dotted refinement of one, and a capability may only name a tag declared in the manifest's top-level tags. Because the capability register and the manifest are generated separately, a tag added to one and not the other passes every local check. See Tags.

An event-name shape. The two-segment rule is in the schema, but it is checked again here — so a hand-edited manifest that slipped past a stale editor config still fails on the way out.

A globally claimed name. A provides_scopes dimension, a provides_permissions key or a provides_roles subject another app already owns. There is nothing local that could know this: the namespace is platform-wide.

A pre-deploy checklist

  1. Every JSON file has its $schema and your editor reports no problems.
  2. dependencies and peerDependencies keys all contain exactly one slash.
  3. Every capability summary is one line, under 255 characters.
  4. Every capability that names a tag has that tag in the manifest's tags.
  5. Every event name is exactly two lowercase dot-separated segments.
  6. Paged list capabilities declare limit, offset and order; nothing else does.
  7. Creates declare their 201; unique columns declare their 409.
  8. revenexx apps capabilities --write and revenexx apps generate produce no diff.
  9. npm test is green.
  10. version in manifest.json has been bumped.

Next steps

Was this page helpful?