How to edit a catalogue specification
Update an existing catalogue specification for the selected organisation or location, including its name, description, colour and optional image. Translation maps are supported through the API, not the current app form.
In this article
Specifications are catalogue attributes that products can reference, such as labels or operational product notes. Editing one keeps the same specification id, so products already linked to it continue to use the updated metadata.
In the GB demo context, use Harbor Demo Group and Harbor Soho for location-owned catalogue work. The same flow also applies to organisation-owned specifications, but saving then depends on organisation-scope catalogue permissions.
Before you start
- An existing specification must be available in the current catalogue context.
- Harbor Demo Group, or another organisation, must be selected. For the location route, Harbor Soho, or another location, must also be selected.
- The operator needs `catalog:manage` in the real owner scope of the specification to save changes. `catalog:view` only opens the record in read-only mode.
- To replace the image, upload the file first through the app image control or `POST /api/app/files` so the saved specification can reference the returned `image_file_id`.
- Use an API client for `name_translations` or `description_translations`; the current app form does not expose those fields.
Instructions
- 1.
Open Specifications
Open catalogue management for the location or organisation and switch to the Specifications tab. The list shows each specification with its name, description and owner scope.
- 2.
Open The Specification
Select the row or use the edit action for the specification you want to update. If the item is view-only for the current user, the form opens without editable controls.
- 3.
Update The Fields
Change the name, description, colour or image. Name is required; description is optional; colour controls the badge shown in catalogue lists and product selection surfaces.
- 4.
Replace The Image If Needed
Use the image field only when the specification needs a new visual. The app uploads the file separately, then stores the returned file id when the specification is saved.
- 5.
Save Changes
Press Save when changes are present and the form is valid. The app uses the location endpoint for a location-owned specification and the organisation endpoint for an organisation-owned specification.
- 6.
Confirm The List Result
After a successful save, the app returns to the Specifications tab. Search for the updated name and confirm that the list shows the new name, description, colour or image marker with the same owner scope.
- 7.
Update Translations By API
When an integration needs translated labels, send `name_translations` and `description_translations` in the same PUT payload. These maps replace the stored translation maps and are not editable in the app form.
Validations and limits
- A selected organisation is required; a selected location is also required on `/location/catalogs?tab=specifications`.
- Name must contain text after trimming spaces.
- Save is enabled only when the form is dirty, valid and not submitting or uploading an image.
- The app normalises empty or invalid colour input to `#98A2B3`; the backend does not validate hexadecimal colour format.
- If image upload fails, the new `image_file_id` is not applied. The operator can retry the image or save other valid field changes.
- System specifications, out-of-scope specifications and missing ids are treated as not editable or not found.
- A specification opened from a location may still be organisation-owned; saving then requires organisation-scope `catalog:manage` and uses the organisation endpoint.
- If translation maps are omitted from the API payload, the backend stores them as nil rather than preserving an unchanged map.
Expected result
The specification is updated in place with the same id and owner scope, existing product links remain intact, catalogue data refreshes, and the operator returns to the Specifications list.