This report accompanies the other one at #1599 regarding a lexer which its user docs are lacking detail that helps understand even what the lexer is intended for.

In this case, the json-object docs state "For JSON data structures (with missing object curly braces)" (JsonBareObjectLexer) but a bit more in-depth information and even a usage sample would do lots in term of helping to understand the feature.

I have a JSON file (here, regardless of how good or bad decision it was to choose JSON for user-editable configuration... JSON is used for historical reasons) of which I want to document a small section (see here for the actual case).

I tried using json-object like this, under the assumption that it would work because that's what I'm able to understand from "with missing object curly braces":

.. code-block:: json-object

   "secure": {
     "port": 8433,
     "certificate": "cert+key.pem",
     "password": "KEY_PASSWORD"
   }

but it fails parsing and Sphinx warns about it:

security.rst:152: WARNING: Could not lex literal_block as "json-object". Highlighting skipped.

Curiously enough, this valid JSON also fails:

.. code-block:: json-object

   {
     "secure": {
       "port": 8433,
       "certificate": "cert+key.pem",
       "password": "KEY_PASSWORD"
     }
   }

The Sphinx warning is the same as before.

(and nevertheless I'd like to avoid putting the additional braces to make it JSON-compliant, because it would add noise and might drive users to think they should somehow write the setting under a new, independent object)

This probably is just a silly misunderstanding like what happened in #1599 so a bit more extended docs would probably help a lot.