App features and openness
Layer 6. Services. Services
Three things render as chips on a marketplace listing, and they are three different kinds of thing told apart by who authors them. Getting this wrong is how a store ends up letting a vendor award itself a medal.
| Authored by | Validation | Rendered as | |
|---|---|---|---|
tags: | the app’s appr | free-form: anything at all | the tag row (unchanged) |
features: | the app’s appr | ★ a closed vocabulary: a value not in it is COMPLETELY IGNORED | its own treatment, not the tag row |
| badges | ★ the marketplace curator, from the back office | curator-selected | its own treatment |
Badges are deliberately not a key in app.yaml. They are applied by a
curator, and a badges: field an appr can write is a badge an appr can
award themselves. Nothing on this page describes them; a sibling lane owns them.
features: declares what the APPLICATION supports
Section titled “features: declares what the APPLICATION supports”features: sso: supported ldap: absent mfa: state: supported via: plugin note: >- Not in the core server: this app ships twofactor_totp and otpmanager as add-ons. email_outbound: supportedThe one rule that decides everything else
Section titled “The one rule that decides everything else”features: describes the APPLICATION, never the app. Owner ruling,
verbatim:
“you need to be careful about scoring the apps based on what the SHC APP supports. Because if the SHC app doesn’t support something, but the app developers’ app DOES support it, you don’t wanna just punish them for that… Let’s focus more on WHAT THE APP ITSELF SUPPORTS, and it’s really kinda SHC’s job to get those things working on it.”
So the value of sso: is “does this application have single sign-on”, and it
stays supported whether or not this app ships an oidc.plug.yaml. What
SHC wires is a separate, derived axis that nobody declares; see
app capabilities, which computes it from the files in
each app directory and prints the gap between the two.
The states
Section titled “The states”features: is a tri-state plus one, and the extra state is the reason the
block is safe to ship on day one.
| Token | Means |
|---|---|
supported | Upstream ships it, in a build a self-hoster can run for nothing. |
paid | Upstream has it, but only in an edition that costs money. Not the same as absent: the operator’s question is “can I have it?”, and the answer is “yes, for money”. |
absent | Upstream does not have it, at any price, by any supported means. A real no, that somebody established. |
unknown | Nobody has established it. The default. An absent key is this. |
★ unknown must never be scored as absent. On the day this block shipped,
90 apps had declared nothing; a schema in which silence reads as failure
marks the entire catalogue down for existing. A consumer that cannot represent
“we do not know” must not consume this data.
★ The tokens are not yes and no, and that is not a style choice. This
catalogue is read by a Go loader (go.yaml.in/yaml/v3, YAML 1.2 core schema:
yes resolves to the string "yes") and by the marketplace seeder
(frappe/apps/marketplace/scripts/import_catalog.py, PyYAML, YAML 1.1: yes
resolves to the boolean True). A vocabulary spelled yes/no would mean
two different things in the two readers of the same file. Every token above is a
word no YAML dialect coerces.
via: how upstream supports it
Section titled “via: how upstream supports it”Only meaningful beside supported or paid. “Jellyfin has SSO” and “Jellyfin
has SSO if you install an unofficial plugin” are different purchasing decisions,
and this catalogue contains both shapes.
| Token | Means |
|---|---|
core | In the shipped application. The default. |
plugin | An add-on the operator installs, upstream’s or a third party’s. |
fork | Only in a fork, including one SHC maintains (openreplay’s OIDC is the worked example). |
The two authoring shapes
Section titled “The two authoring shapes”List, the ergonomic 80% case. Every element is supported, and the block
says nothing at all about any other key: they stay unknown. This shape
cannot lie, which is why it is the one to reach for first.
features: [sso, email_outbound, object_storage]Map, the full tri-state, and the only shape that can assert absent.
features: sso: absent mfa: {state: paid, note: "MFA is Premium", source: "https://…"} reviewed_on: "2026-08-18"Reserved sub-keys inside the map form (reviewed_by, reviewed_on, source,
note) are block-level provenance and are never feature names. (license:
mixes reserved sub-keys into one flat map the same way.)
What happens to a value that is not in the vocabulary
Section titled “What happens to a value that is not in the vocabulary”★ It is completely ignored. Not rendered, not scored, not an error, by owner ruling. A tag is whatever the developer typed; a feature is a fact a shopper can filter on, and that only holds if the vocabulary is closed.
Two failure shapes, and they are handled differently on purpose:
| What is wrong | What happens |
|---|---|
The feature name is not in the vocabulary (features: {single_sign_on: supported}) | The entry is dropped entirely. |
The state token is not in the vocabulary (features: {sso: partial}) | The feature degrades to unknown, ★ never to absent. A typo must not be able to assert that a capability is missing. |
Ignored is not invisible to the author. Silence belongs at the render
surface, not in the author’s terminal. Every drop is printed on stderr by
make catalog/capabilities:
features: myapp: IGNORED ("single_sign_on" is not a feature in the vocabulary)and every drop is listed in the Ignored declarations section of
app capabilities. This mirrors the seeder’s existing
posture for malformed gallery: entries, which likewise skip-and-print rather
than failing the run.
The vocabulary
Section titled “The vocabulary”The canonical list (with, for each entry, the argument for why it earned its
place and how the SHC side of it is derived) is generated into
app capabilities from scripts/gen-app-capabilities-md.go,
which is where the vocabulary is defined in code. Do not maintain a second copy
here; a vocabulary in two places is a vocabulary that disagrees with itself.
The 16 keys, in display order:
| Group | Keys |
|---|---|
| Identity | sso ldap mfa scim rbac multiuser multi_tenancy |
| Communication | email_outbound email_inbound |
| Data & interop | api webhooks object_storage import_export |
| Operations | metrics audit_log |
| Clients | mobile_app |
Every one of them varies across the 90 apps. A capability every app has, or that no app in this catalogue has, distinguishes nothing and is not a feature. Two entries were considered and rejected on exactly that test:
cli: nearly every server app in this tree ships some admin CLI (occ,gitlab-rails,wp-cli). Near-total coverage distinguishes nothing, and narrowing it to “first-party end-user CLI client” made it a word two people would read two ways.offline: genuinely hard to establish, and what it would tell a reader is already carried bymobile_appplus the app’s own description.
★ Seven of the 16 have no SHC derivation at all: there is no plug, no
socket and no computable answer anywhere in the tree for ldap, mfa, scim,
multiuser, multi_tenancy, audit_log or mobile_app. That is not a hole in
this design; it is the proof that the declared axis is not redundant with the
derived one. ldap is the sharpest case: the
SSO coverage policy names LDAP as the third rung of the
ladder and states plainly that “No ldap.plug.yaml exists in the catalog yet”.
license.openness: how OPEN the app is
Section titled “license.openness: how OPEN the app is”license.id records what licence the code is under. It cannot record how
open the app is to somebody who wants to run it, and the two are orthogonal in
both directions: an AGPL app can paywall SSO (openreplay upstream), and an
SSPL-family app can be entirely free to run (mongodb).
license: id: unverified openness: model: open-core pricing: per-user seat_cap: 10 reviewed_on: "2026-08-18" note: >- The pinned image is the proprietary CE build. Free instance-wide caps: 10 OAuth accounts, 50 accounts total, 3 workspaces.★ Everything in this block is EDITORIAL and it is marked as such. Nothing in
this repository can establish an upstream vendor’s price list: there is no file
to read and no command to run. reviewed_by and reviewed_on are therefore
required, and the generated tables print them. A judgement with a byline is
evidence; the same judgement rendered as a bare number is a laundered guess.
This is the same standing rule the scoring lane works under: editorial inputs
stay visibly separate from measured ones.
openness.model
Section titled “openness.model”| Value | Means |
|---|---|
foss | Everything the operator runs is under an OSI-approved licence, and there is no edition they cannot have. |
open-core | The code is open, but a paid edition holds capabilities the open one does not. |
source-available | Source is published; the licence restricts redistribution or resale but not self-hosting: SSPL, BUSL, Elastic-2.0, RSALv2, FCL. Costs a self-hoster nothing. |
proprietary | No source, or source you may not run in production without paying. |
unknown | Nobody has established it. The default. |
★ open-core is not the same as requires_paid_license. fleet,
sonarqube and ciso-assistant are all open-core, and all three give away the
thing an SHC estate actually needs (SSO) while charging for SCIM. They are
correctly requires_paid_license: false and correctly not in
apps/enterprise/. Keeping the two keys separate is what stops “has a paid
tier” being confused with “you must pay”.
openness.pricing
Section titled “openness.pricing”| Value | Means |
|---|---|
free | Nothing to pay for anything a self-hoster needs. |
flat | A paid tier priced per instance or per server. It does not get more expensive as the team grows. |
per-user | ★ Priced per seat. |
per-resource | Priced per host, agent, scan or document rather than per person. |
unknown | Nobody has established it. The default. |
★ per-user is why this axis exists. Owner, verbatim: “if it’s charging on
a per-user basis, that might affect the score.” A self-hoster buys hardware once
and adds people for free; per-seat pricing inverts that, and it is completely
invisible in an SPDX identifier. Worked examples in the catalogue today:
docuseal at $240/year/user on-prem, plane from $7/seat/month, affine
requiring a subscription sized to the seat count.
openness.seat_cap
Section titled “openness.seat_cap”An integer, and only for a cap on the free build. Absent or 0 means
no cap. Four apps have one and each bites differently:
| App | Cap | What happens at the cap |
|---|---|---|
affine | 10 per workspace | the whole workspace goes read-only for everybody in it |
windmill | 10 OAuth accounts (50 total) | the 11th human to log in is refused at the OAuth callback, silently; disabling a user does not free a seat |
uptime-kuma | 1 | not commercial: there is one shared admin and no user model at all |
★ A seat cap does not by itself make a capability paid. Windmill’s SSO
works on the free build, so it is declared sso: supported with a note naming
the cap, and the cap itself lives here. paid is reserved for a capability that
is unavailable at any scale without paying. That keeps paid crisp and keeps
a free-but-capped app from being marked down as though it had nothing.
How this is consumed
Section titled “How this is consumed”The derived half, and the gap
Section titled “The derived half, and the gap”make catalog/capabilities runs scripts/gen-app-capabilities-md.go, which:
- reads every app’s declared
features:andlicense.openness; - derives the SHC-side answer from the app’s files: plugs, sockets,
backup.yaml, exporters,access: gated; - writes app capabilities with the gap list, the reverse list, the inert list and the per-app matrix;
- prints every ignored declaration on stderr.
-format json emits the machine artifact for the scoring lane. This
generator deliberately emits no score, no weight and no total: the two axes
here are inputs to a scoring model that lives elsewhere.
It is deliberately not wired into make docs/check: a staleness check is a
guard, and guards are closed on this tree by owner ruling.
The storefront seam: owed, not built here
Section titled “The storefront seam: owed, not built here”Features render as chips, in their own treatment, not in the tag row. Two things are needed and both belong to the lanes that own those surfaces:
| Where | What is owed |
|---|---|
frappe/apps/marketplace/scripts/import_catalog.py | a features_json entry in listing_fields, carrying the normalized map ({key: {state, via}}) with unrecognised entries already dropped, the same skip-and-print posture the gallery: parser uses |
features/marketplace/src/listing/ | a ListingFeatures surface beside ListingFacts. ★ Not an addition to ListingFacts’s tag row: that row is the page’s one metadata surface, and features are a different kind of claim |
Both files sit inside pinned subtrees or lanes already in flight (shc!264, the
Flathub-parity work), so this page specifies the seam rather than cutting it.
shc validate growing a warning for an ignored feature name is the third owed
piece, and it belongs in ce’s modules/app/validate.go, which already carries
a warnings channel.
See also
Section titled “See also”- App capabilities: the generated two-axis matrix, gap list and vocabulary rationale
- App definition: the rest of the
app.yamlschema - Licensing postures: the catalogue’s standing posture on each no-SaaS licence family
- SSO coverage policy: the OIDC → SAML → LDAP ladder