Uploading content to the Marketplace
This content is intended for all licensed Studio users.
Uploading content to the Marketplace
The Marketplace is a shared resource, and its quality depends on contributors who document and upload content carefully. This page covers everything you need to know about the upload process: From signing in and selecting a file to versioning existing content and making it available in the public library.
Uploading content requires a Marketplace account and the appropriate permissions for the library you are uploading to. Sign in using your Studio credentials. If you do not yet have upload permissions, contact marketplace@better.care.
Who can upload content
Any user with a Marketplace account can upload content to a library they are a member of, provided they have been granted upload permissions for that library.
Upload permissions are not granted automatically on joining a library. If you are a library member but cannot see the Upload button in the Marketplace, contact your library administrator or write to marketplace@better.care to request upload access.
To upload content to the public library, additional verification is required. See Content sharing on the public library below.
Supported content types for upload
The following content types can be uploaded to the Marketplace:
- Widgets
- Templates (as filesets)
- Forms
- Bundles
- AQL views
- Plugins
- Apps (as listing entries with a link to the external application)
Each content type has its own metadata requirements and documentation standards.
Upload flow
To upload content to the Marketplace:
- Open the Marketplace and sign in.
- Select Upload from the top right of the screen.
- Select the file you want to upload. The supported file formats depend on the content type — for example, widgets and plugins are uploaded as package files, while templates are uploaded as filesets.
- A modal appears. Select the library you want to upload the content to.
- If the content is a new version of existing content, select the existing item and indicate that this is an update. See Versioning and changelog below.
- Complete the metadata fields. See the section below for a description of each field.
- Preview your content listing, then confirm the upload.
Metadata fields
During the upload flow, you are prompted to complete the following fields. Required fields are marked in the interface.
| Field | Description |
|---|---|
| Name | The display name of the content. Use sentence case, British English. Do not include version numbers or redundant type labels (for example, do not write "Vital signs widget" — write "Vital signs"). |
| Contributor | The name of the team or organisation that created the content. Use a consistent contributor name across all uploads from your organisation (for example, "Better" for all internal assets). |
| Supporting content | Related assets this content depends on or works best with. For templates, the fileset is mandatory. For widgets with presets, include the AQL views or API calls the presets rely on. |
| Intro statement | A short statement displayed on the preview screen. Use this to give users an immediate sense of what the content does. |
| Preview image | A screenshot or image displayed on the preview screen. Use a high-resolution image that accurately represents the content in use. |
| What's New | A brief description of what has changed in this version. See Editing documentation and What's New after upload. |
| Description | A 3–5 sentence overview of the content's purpose and scope. |
| Keywords and tags | 5–10 keywords to support discoverability. Include both technical and clinical terms. |
| Documentation | Full structured documentation for the content. |
| Attachments | Supporting files such as PDFs, Word documents, or presentations. See Supporting files below. |
The What's New, Description, and Documentation fields support Markdown formatting. When pasting content, use the Keep text only option to ensure Markdown code pastes correctly.
Editing documentation and What's New after upload
You can update the documentation and What's New sections of any content you have uploaded at any time — you do not need to upload a new version to make documentation changes.
To edit documentation after upload:
- Open the Marketplace and navigate to the content item.
- Open the item's detail page.
- Select the edit option for the Documentation or What's New section.
- Make your changes in the Markdown editor and save.
Changes are saved immediately and are visible to all library members. There is no staging or approval step for documentation edits within the Marketplace interface.
Documentation edits are a library-level action. If you are editing content in the public library, your changes are immediately visible to all Studio users. Review your changes carefully before saving.
Supporting files
In addition to the structured documentation fields, you can attach supporting files to any content item. Supporting files allow you to provide additional context (examples like a clinical validation report, a presentation, or an implementation guide) that would not fit naturally into the documentation field.
Supported file formats for attachments:
- PDF (
.pdf) - Word document (
.docx) - PowerPoint presentation (
.pptx) - Markdown file (
.md)
To attach a supporting file:
- During the upload flow, scroll to the Attachments section.
- Select Add attachment and upload the file.
- Add a short label or description for the file so users know what it contains.
Supporting files can also be added or updated after the initial upload, from the content item's detail page.
Versioning and changelog
Every content item in the Marketplace is versioned. When you upload a new version of existing content, you are updating the item's version record — not creating a separate listing.
Better Studio uses semantic versioning. Version numbers follow the format MAJOR.MINOR.PATCH (for example, 1.2.0). As a contributor, you define the version number when uploading.
When to increment each component:
- MAJOR: Significant changes that may affect compatibility with existing implementations (for example, removing a field or changing the data structure of a template).
- MINOR: New functionality or additions that are backwards compatible (for example, adding a new preset or an additional configuration option).
- PATCH: Small fixes or documentation updates that do not change the content's behaviour (for example, correcting a typo in the description or fixing a minor bug in a widget).
When uploading a new version:
- Select Upload and choose the updated file.
- In the upload modal, indicate that this is a new version of existing content and select the existing item.
- Enter the new version number.
- Complete the What's New field with a clear summary of what has changed. Use bullet points to list specific changes — added fields, updated logic, improved descriptions, and so on.
- Complete any other metadata fields that have changed and confirm the upload.
The version history and changelog are displayed on the What's New tab of the content's detail page.
Content sharing on the public library
Content uploaded to a private library is only visible to library members. To make content available to all Studio users, it must be shared to the public library.
Sharing to the public library is a deliberate, permissioned step — not an automatic part of the upload flow. This ensures that content in the public library meets the quality and documentation standards expected for broad reuse.
To share content to the public library, contact marketplace@better.care.
Before sharing, ensure that:
- All required metadata fields are complete.
- The content has structured documentation.
- Supporting files, if relevant, are attached.
- The content has been reviewed and is ready for use by teams outside your organisation.
Frequently asked questions (FAQs)
Do I need special permissions to upload content?
Yes. You must be a member of a library and have upload permissions for that library. Membership alone does not grant upload access. Contact your library administrator or write to marketplace@better.care if you need upload access.
Can I upload content directly to the public library?
No. Content must first be uploaded to a private library. Once it meets the required standards, you can request that it be shared to the public library. Contact marketplace@better.care to initiate this process.
What file format should I use to upload a template?
Templates must be uploaded as filesets, which bundle the template together with its dependent archetypes. Do not upload a template file on its own.
Can I update the documentation without uploading a new version of the content?
Yes. You can edit the Description, Documentation, and What's New sections at any time from the content item's detail page. You do not need to upload a new file to make documentation-only changes.
What should I include in the What's New field?
Write a concise summary of what has changed in this version. Use bullet points to list specific changes — added fields, updated logic, new presets, or bug fixes. Users rely on this field to decide whether to update their installed version.
Who can see my content once I upload it to a private library?
All members of that library can see and install the content immediately after upload. It is not visible to users outside the library until it is shared to the public library.
What happens if I upload a file with the same name as existing content?
The upload modal prompts you to indicate whether this is a new version of existing content or a new item. If you select new version, you are asked to choose the existing item to update. This ensures the version history is maintained correctly and avoids duplicate listings.