How to use sphinx directives and multi-line strings in property descriptions

[GlenNicholls]

I have the below schema defined in a python file where I am trying to use reST in the description of a property.

import inspect 

schema_debug: dict = {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "title": "Schema",
    "type": "object",
    "properties": {
        "spec": {
            "type": "number",
            "enum": [1, 2],
            "description": inspect.cleandoc(
                """
                Specification to parse the core file with

                .. note::
                    This is used to retain backward compatibility when breaking features
                    are added.
                """
            )
        }
    }
}

Note that inspect.cleandoc() is just used to remove the leading white space within the multi-line string. I was hoping that this string would be parsed similarly to a python docstring such that reST would take care of wrapping when appropriate for lines that continue on the next line and then keeping \n\n as an actual line break.

For reference, I am seeing this:

I attempted to use :pass_unmodified: which produces this:

I'm assuming schema's defined in YAML files with multi-line strings would also produce the same issue.

Lastly, I also noticed that long descriptions do not cleanly break at the edge of the table but instead add a scroll bar. I was hoping in this scenario that the lines would wrap to fill up the space (producing a larger row) similar to python docstrings

[lnoor]

In JSON line continuation is not possible. Specifically for this problem the non-standard $$description key was introduced. It accepts a list of strings instead of a single string; should be ignored by other schema processors which is either a blessing or a curse. Can you make do with $$description?

[GlenNicholls]

Specifically for this problem the non-standard $$description key was introduced. It accepts a list of strings instead of a single string; should be ignored by other schema processors which is either a blessing or a curse. Can you make do with $$description?

I see, I'll give that a shot and see if it helps. Out of curiosity, is it expected that \n do not work in descriptions?

[lnoor]

I think not but an empty string in the array should get you the same result.