---
seo:
    title: "Editing Specifications"
    description: "Switch a specification out of read-only mode and edit DRAFT or ACTIVE documents with the Editor role."
llm_context: "Guide to editing specifications in the UI - the Editor role requirement, the DRAFT/ACTIVE/FINAL status rules, and how to toggle edit mode."
category: "guide"
related:
    - "/platform/guides/specifications/start_cloning_spec"
    - "/platform/guides/specifications/exporting_specification"
    - "/platform/guides/specifications/creating_issuers"
    - "/platform/concepts/doc_library"
---

## Editing Specifications

:::warning Editor Role Required
Only users with the Documentation **Editor** role may edit :color:DRAFT:#fff:#039be5: or :color:ACTIVE:#fff:#ec407a: specifications. Remember that :color:FINAL:#fff:#43a047: specifications are frozen by design.

Think you should be an editor, but can't access it? Ask an admin to check the [Issuer-level controls](/platform/guides/specifications/creating_issuers#managing-issuer-editors).
:::

### Overview

When you open a specification, it starts in read-only mode. To start making changes, toggle the :icon:fa-regular fa-pencil: icon in the left-hand sidebar.

![Figure: Editing informational sections within a specification](https://docs.fixspec.com/api/docs/image/spec_editing_info.png)

### Adding Sections (Pages)

A **Section** refers to a high-level chapter within a specification, which is presented as a single (potentially) long page. We reserve the `H1` heading for their title, and this will always appear as the first content block at the top of the page.

To add a new Section, you can either:

1. Click the "Add, Move Or Merge Sections" button in the left-hand menu, or
2. Split an existing Section by using the :icon:fa-regular fa-file-half-dashed:#ff9800: button. If you click this just before an existing heading, that next heading will be promoted to the title of the new section.

Adding a Section will automatically adjust the top-level navigation menu in the left-hand menu.

:::info Sections within PDF
If you have PDF export enabled, then each Section will be preceded by a page break, and the heading will be displayed as normal.
:::

While it is possible to delete empty sections, it is more likely that you would wish to merge two existing sections together. For information on that, see the [Merging & Moving Sections](#merging-moving-sections) below.

### Adding Content Blocks

On any given Section (page), we have multiple **Blocks**, each of which represents a chunk of content within the page. These take the form of:

- A heading (with H1 reserved for _Section_ titles),
- A block of rich text,
- An image,
- A table,
- A [PlantUML](https://plantuml.com/sequence-diagram) sequence diagram, or
- A structured API message (e.g. FIX)

Each Block type has its own user interface elements, most of which are self-explanatory. See [Adding Components & Messages](#adding-components-messages) for further details of maintaining structured API messages.

:::info Impact of Headings on Navigation
Heading _Block_ levels 2 and 3 are used to automatically create both the expanding left-hand navigation menu for the specification, and the right-hand "On This Page" intra-page navigation. If you have PDF export enabled, then headings up to and including level 4 will be used to derive the Table of Contents.
:::

### Merging & Moving Sections

Click the "Add, Move or Merge Sections" button, and use the :icon:fa-solid fa-grip-dots:#4caf50: icon to drag re-order, and the :icon:fa-regular fa-merge:#1976D2: icon to merge sections. Don't forget to click "Save" when you are done!

![Figure: Managing Sections](https://docs.fixspec.com/api/docs/image/spec_editing_merge_sections.png)

:::tip Splitting Sections
You can also split an existing Section by using the :icon:fa-regular fa-file-half-dashed:#ff9800: button.
:::

### Adding Components & Messages

When firms need to add a new FIX **Component** or **Message** to their API, they inevitably start by importing from the FIX standards — so that's the approach we've followed here too.

1. Click the :color:+ ADD:#fff:#ff9800: button where you would like the fieldset to appear, and then choose :color:Fieldset:#fff:#26A69A:.
2. In the wizard that appears, choose _Component_ or _Standard Message_ and search for the fieldset you need.
3. Because the later FIX standards have a habit of deeply-nested components, you have the option to "flatten" them if you like. This unwraps them from the Component but (of course) keeps all repeating groups intact.
4. Finally, you can choose whether to import just mandatory fields, type a list, or import everything.
5. Click :color:SAVE:#fff:#4caf50: and your fieldset will be added to your specification.

:::tip Try Mandatory Only
While we offer it as an option, we recommend **NOT** importing all fields, as it simply creates a lot of noise that you will spend time removing later. Instead, we recommend importing just the mandatory fields, and then adding any optional fields you need.
:::

Once you have added your fieldset, it will appear in the stream of content Blocks as an abbreviated panel as below. You can then click to :color:EDIT:#fff:#607d8b: further.

![Figure: Fieldset view in Edit Mode](https://docs.fixspec.com/api/docs/image/spec_editing_fieldset.png)

### Adding Fields

1. With the page in edit mode (:icon:fa-regular fa-pencil:#ef5350:), find and click to :color:EDIT:#fff:#607d8b: the fieldset.
2. Move to the "FIELDS" tab to list the fields, and scroll to the bottom to find the fast entry box (see below).
3. Type the tag numbers or component names and either click :color:+:#fff:#9e9e9e: or hit _Enter_ to look them up and append them to your fieldset.

![Figure: Fast Field Entry](https://docs.fixspec.com/api/docs/image/spec_editing_fast_entry.png)

:::tip Beware of Component Naming!
Adding fields by number is easy, but FIX has some quirks when looking up Components. Be sure to enter the name exactly as specified by FIX, which typically uses CamelCasing.
:::

When you add a field or Component using this method, the data imported by the platform follows a sequence of resolution rules:

1. If the field/Component is already defined in the current specification, then use that definition.
2. Else, lookup the field/Component in the [Repository](/platform/concepts/doc_library#repositories). If it exists, use that definition.
3. Otherwise, look it up in FIX standards, and use that.
4. As a last resort, a field will be marked "custom" and added. Note that Components can not be marked "custom".

Since it may take a few seconds to iterate through these various options (including querying external sources), adding fields/Components in this way operates as a simple queue; if one entry fails for any reason it will block subsequent entries behind it. This safety feature stops sequencing failures in the event of rapid entry.

### Editing Fields

Within the "Fields" tab of a fieldset, a variety of editing controls are available:

![Figure: Field editing controls](https://docs.fixspec.com/api/docs/image/spec_editing_field.png)

- Use the :icon:fa-solid fa-grip-dots:#4caf50: icon to move the row up or down. The Standard Header and Trailer are - of course - fixed.
- The _Tag_ column displays the field tag number or a :icon:fa-regular fa-layer-group: icon to indicate it is a Component. Tag numbers are only editable for custom fields.
- The _Name_ column shows field or Component name. This can only be edited in the case of custom fields.
- _Req'd_ is a toggle field to switch between mandatory (Y), optional (N) and conditionally-required (C). You are invited to write an expression to describe _when_ a row is conditionally-required.
- _Type_ is the FIX datatype (or blank for components). This becomes a select box for custom fields.
- Use the _Description_ column to provide a rich-text description of the field or Component's purpose and usage.
- For eligible datatypes, the _Values_ column can be used to provide either a list of enumerations, or to set minimum and/or maximum values.
- Use the :icon:fa-regular fa-outdent: icon (where shown) to break out of a [repeating group](#handling-repeating-groups).
- Use the :icon:fa-regular fa-xmark:#f44336: icon to delete the row.

### Handling Repeating Groups

Repeating Groups are a unique complexity in FIX fieldsets; they represent a repeating, strictly-sequenced list of fields (or Components) which are preceded by a special field with a _NumInGroup_ datatype indicating how many repetitions are present. In traditional PDF documents, the repeating fields are indented with a particular character such as :icon:fa-regular fa-arrow-right:. Add in the fact that repeating groups can be nested, and you quickly end up with an error-prone documentation process.

To assist with managing this complexity, the platform automates much of the repeating group logic:

- When adding a _NumInGroup_ field, we automatically indent subsequent fields that should be part of the group (per FIX standards), and outdent again when we reach the end.
- You can manually break out of a repeating group using the :icon:fa-regular fa-outdent: icon, which also impacts all subsequent fields.
- Dragging a field or Component row into a repeating group will automatically indent it, and dragging it out will outdent it.
- The above logic also works for nested repeating groups.

:::info
Repeating group handling is a complex UI component. If you hit any issues with it, please reach out for help using the chat function.
:::

### Defining Functional Views

:::info Create Your Messages First!
[Functional views](/platform/concepts/doc_library#fieldsets-messages-components-views) are a powerful concept that is unique to FixSpec and does not exist in the FIX standards. For this reason, we can't look them up in the FIX Standards, they must be defined locally. So before you create a functional view, it is important to first create the messages that will be used in that view.
:::

1. Click the :color:+ ADD:#fff:#ff9800: button where you would like the new view to appear, and then choose :color:Fieldset:#fff:#26A69A:.
2. In the wizard that appears, choose _Functional View_ and search for the Message that it should be based upon.
3. We strongly recommend changing the default name of the view, and editing the description (which will be based on the underlying Message).
4. Finally, you can use the condition builder to define the condition under which the view should be applied.
5. Click :color:SAVE:#fff:#4caf50: and your view will be added to your specification.

### Frequently Asked Questions

:::faqs
::faq[Can I use Mermaid instead of PlantUML?]{#faq_editing_spec_mermaid}
We understand that Mermaid is popular for sequence diagrams, and so adding support is in our development backlog.

We prioritised PlantUML, however, because of its rich feature set and robust tooling.
::
::faq[How do I add my custom fields?]{#faq_editing_spec_custom_fields}
No problem. You can simply [add the field](#adding-fields) as you normally would. If it exists elsewhere in the spec or in your repository, then we will pick up those descriptions. If not, we will simply mark it as a custom field and let you edit it however you need.
::
::faq[Do I really need to maintain descriptive sections?]{#faq_editing_spec_fields_only}
The minimum data required to allow conformance to run is the fieldset data (messages, fields and enumerations). For protocols such as FIX, this limited data is also enough to export to QuickFIX. If this is the limit of your goals, then - yes - you can ignore the descriptive sections.

If, however, your goal is to remove duplicate specification maintenance, exporting to PDF or to render on a portal, then the descriptive sections become important.
::
:::
