How to specify a S-Group (Substituted Functional Group) in a molecule structure in Ketcher file format?

There are 2 options to specify a S-Group (Substituted Functional Group) in a molecule structure:

1. Specify S-Group without Group Substructure: Just replace the atom symbol at the s-group attaching point with the s-group name. The s-group substructure is not specified.

    {
        "label": "<group_name>",
        "location": [ ... ]
    }

2. Specify S-Group with Hidden Group Substructure: The s-group substructure is fully specified as part of the molecule structure. Then the s-group definition is added to the "sgroups" array to hide the s-group:

    "sgroups": [
        {
            "type": "SUP",
            "atoms": [ ... ],
            "name": "<group_name>"
        }
    ]

For example, the following Ketcher file represents a molecule with an "OMs" s-group fully specified.

{
    "root": {
        "nodes": [
            { "$ref": "mol0" }
        ]
    },
    "mol0": {
        "type": "molecule",
        "atoms": [
            {
                "label": "C",
                "location": [ 0, 0, 0 ]
            },
            {
                "label": "C",
                "location": [ 1, 0, 0 ]
            },
            {
                "label": "O",
                "location": [ 2, 0, 0 ]
            },
            {
                "label": "S",
                "location": [ 3, 0, 0 ]
            },
            {
                "label": "C",
                "location": [ 4, 0, 0 ]
            },
            {
                "label": "O",
                "location": [ 3, -1, 0 ]
            },
            {
                "label": "O",
                "location": [ 3, 1, 0 ]
            }
        ],
        "bonds": [
            {
                "type": 1,
                "atoms": [ 0, 1 ]
            },
            {
                "type": 1,
                "atoms": [ 1, 2 ]
            },
            {
                "type": 1,
                "atoms": [ 2, 3 ]
            },
            {
                "type": 1,
                "atoms": [ 3, 4 ]
            },
            {
                "type": 2,
                "atoms": [ 3, 5 ]
            },
            {
                "type": 2,
                "atoms": [ 3, 6 ]
            }
        ]
    }
}

The "OMs" s-group substructure is highlighted in the following molecule structure diagram:

Now if we take option 1, we can remove the s-group substructure from the Ketcher file and replace the "O" with "OMs" at the attachment point:

{
    "root": {
        "nodes": [
            { "$ref": "mol0" }
        ]
    },
    "mol0": {
        "type": "molecule",
        "atoms": [
            {
                "label": "C",
                "location": [ 0, 0, 0 ]
            },
            {
                "label": "C",
                "location": [ 1, 0, 0 ]
            },
            {
                "label": "OMs",
                "location": [ 2, 0, 0 ]
            }
        ],
        "bonds": [
            {
                "type": 1,
                "atoms": [ 0, 1 ]
            },
            {
                "type": 1,
                "atoms": [ 1, 2 ]
            }
        ]
    }
}

If we take option 2, we can keep the s-group substructure from the Ketcher file and add the "OMs" s-group definition in the "sgroups" array:

{
    "root": {
        "nodes": [
            { "$ref": "mol0" }
        ]
    },
    "mol0": {
        "type": "molecule",
        "atoms": [
            {
                "label": "C",
                "location": [ 0, 0, 0 ]
            },
            {
                "label": "C",
                "location": [ 1, 0, 0 ]
            },
            {
                "label": "O",
                "location": [ 2, 0, 0 ]
            },
            {
                "label": "S",
                "location": [ 3, 0, 0 ]
            },
            {
                "label": "C",
                "location": [ 4, 0, 0 ]
            },
            {
                "label": "O",
                "location": [ 3, -1, 0 ]
            },
            {
                "label": "O",
                "location": [ 3, 1, 0 ]
            }
        ],
        "bonds": [
            {
                "type": 1,
                "atoms": [ 0, 1 ]
            },
            {
                "type": 1,
                "atoms": [ 1, 2 ]
            },
            {
                "type": 1,
                "atoms": [ 2, 3 ]
            },
            {
                "type": 1,
                "atoms": [ 3, 4 ]
            },
            {
                "type": 2,
                "atoms": [ 3, 5 ]
            },
            {
                "type": 2,
                "atoms": [ 3, 6 ]
            }
        ],
        "sgroups": [
            {
                "type": "SUP",
                "atoms": [ 2, 3, 4, 5, 6 ],
                "name": "OMs"
            }
        ]
    }
}

One advantage of using option 2 is that the s-group substructure can be expanded or collapsed in the Ketcher editor by clicking the right-mouse button:

⇒ Adding Text Labels in Ketcher File

⇐ Bond Type Codes in Ketcher File

⇑ Ketcher File Format for Chemical Structures

⇑⇑ Ketcher - Chemical Structure Editor