Skip to content
SHC Docs

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 byValidationRendered as
tags:the app’s apprfree-form: anything at allthe tag row (unchanged)
features:the app’s appr★ a closed vocabulary: a value not in it is COMPLETELY IGNOREDits own treatment, not the tag row
badges★ the marketplace curator, from the back officecurator-selectedits 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: supported

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.

features: is a tri-state plus one, and the extra state is the reason the block is safe to ship on day one.

TokenMeans
supportedUpstream ships it, in a build a self-hoster can run for nothing.
paidUpstream 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”.
absentUpstream does not have it, at any price, by any supported means. A real no, that somebody established.
unknownNobody 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.

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.

TokenMeans
coreIn the shipped application. The default.
pluginAn add-on the operator installs, upstream’s or a third party’s.
forkOnly in a fork, including one SHC maintains (openreplay’s OIDC is the worked example).

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_by: [email protected]
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 wrongWhat 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 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:

GroupKeys
Identitysso ldap mfa scim rbac multiuser multi_tenancy
Communicationemail_outbound email_inbound
Data & interopapi webhooks object_storage import_export
Operationsmetrics audit_log
Clientsmobile_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 by mobile_app plus 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.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_by: [email protected]
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.

ValueMeans
fossEverything the operator runs is under an OSI-approved licence, and there is no edition they cannot have.
open-coreThe code is open, but a paid edition holds capabilities the open one does not.
source-availableSource is published; the licence restricts redistribution or resale but not self-hosting: SSPL, BUSL, Elastic-2.0, RSALv2, FCL. Costs a self-hoster nothing.
proprietaryNo source, or source you may not run in production without paying.
unknownNobody 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”.

ValueMeans
freeNothing to pay for anything a self-hoster needs.
flatA paid tier priced per instance or per server. It does not get more expensive as the team grows.
per-user★ Priced per seat.
per-resourcePriced per host, agent, scan or document rather than per person.
unknownNobody 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.

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:

AppCapWhat happens at the cap
affine10 per workspacethe whole workspace goes read-only for everybody in it
windmill10 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-kuma1not 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.


make catalog/capabilities runs scripts/gen-app-capabilities-md.go, which:

  1. reads every app’s declared features: and license.openness;
  2. derives the SHC-side answer from the app’s files: plugs, sockets, backup.yaml, exporters, access: gated;
  3. writes app capabilities with the gap list, the reverse list, the inert list and the per-app matrix;
  4. 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.

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:

WhereWhat is owed
frappe/apps/marketplace/scripts/import_catalog.pya 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.